1.\" $OpenBSD: release.8,v 1.16 2001/07/27 20:29:19 krw Exp $ 2.\" 3.\" Copyright (c) 2000 Marco S. Hyman 4.\" 5.\" Permission to copy all or part of this material for any purpose is 6.\" granted provided that the above copyright notice and this paragraph 7.\" are duplicated in all copies. THIS SOFTWARE IS PROVIDED ``AS IS'' 8.\" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT 9.\" LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 10.\" FOR A PARTICULAR PURPOSE. 11.\" 12.Dd July 6, 2000 13.Dt RELEASE 8 14.Os 15.Sh NAME 16.Nm release 17.Nd building an 18.Ox 19release 20.Sh DESCRIPTION 21There are several steps necessary to build a system release. 22They are: 23.Pp 24.Bl -enum -compact 25.It 26Update sources. 27.It 28Build and install a new kernel. 29.It 30Build a new system. 31.It 32Make and validate the system release. 33.It 34Build and install XF4. 35.It 36Make and validate the XF4 release. 37.It 38Make the third party packages. 39.El 40.Pp 41The following sections describe each of the required steps in detail. 42.Ss "1. Update sources" 43.Pp 44A 45.Nm 46should always start from a known set of 47.Em coherent 48sources. 49The easiest way to ensure that the sources are complete and coherent 50is to check them out using the 51.Tn CVS 52tag the 53.Ox 54developers add to the repository prior to making a release. 55There are two tags, one which identifies the release as it exists on the 56.Tn CD\-ROM 57and another which identifies the 58.Em stable 59branch. 60The 61.Em stable 62branch, starting with 63.Ox 2.7 , 64contains the patches described in 65.Pa http://www.openbsd.org/errata.html . 66The tags are of the form: 67.Bl -tag -width OPENBSD_x_y_BASE 68.It Va OPENBSD_x_y_BASE 69This tag marks the source as it exists on the release 70.Tn CD\-ROM 71where 72.Ar x 73is the major release number and 74.Ar y 75is the minor release number. 76.It Va OPENBSD_x_y 77This tag is a moving target. 78It marks the sources that belong to the stable branch. 79This branch 80.Em only 81contains errata, no new features. 82.El 83.Pp 84To update your sources to the versions identified by one of the above 85tags use the commands: 86.Pp 87.Bl -bullet -offset indent -compact 88.It 89.Li "cd /usr/src && cvs up -r TAG -Pd" 90.It 91.Li "cd XF4SRC && cvs up -r TAG -Pd" 92.It 93.Li "cd PORTSPATH && cvs up -r TAG -Pd" 94.El 95.Pp 96Replace 97.Va XF4SRC 98with the path to your 99.Tn X11R6 100sources. 101Replace 102.Va PORTSPATH 103with the path to your ports tree sources, typically 104.Pa /usr/ports . 105The above command assume an existing source tree. 106.Pp 107See 108.Pa http://www.openbsd.org/anoncvs.html 109for instructions on fetching the sources for the first time. 110.Bd -offset indent 111.Sy Warning : 112.Tn CVS 113tags are 114.Sq sticky . 115See 116.Xr cvs 1 117for more information. 118.Ed 119.Ss "2. Build and install a new kernel" 120.Pp 121For safety, you should always build and install a new kernel before 122building the programs that will use the kernel. 123This ensures that any new system calls, for example, will be present 124when needed. 125To build a kernel the steps are: 126.Pp 127.Bl -bullet -offset indent -compact 128.It 129.Li "cd /sys/arch/${ARCH}/conf" 130.br 131where 132.Va ${ARCH} 133is the architecture of your machine, e.g., 134.Li i386 . 135.It 136.Li "vi ${NAME}" 137.br 138where 139.Va ${NAME} 140is your kernel configuration file. 141You should 142.Em not 143edit 144.Li GENERIC , 145create your own kernel configuration if you need to make modifications. 146If using 147.Li GENERIC 148you can skip this step. 149And yes, you may use 150.Li emacs 151or any other editor you choose. 152.It 153.Li "config ${NAME}" 154.It 155.Li "cd ../compile/${NAME}" 156.It 157.Li "make clean && make depend && make" 158.br 159In this instance 160.Li "make clean" 161is your friend. 162.It 163.Li su 164.It 165.Li "mv /bsd /bsd.old && mv bsd / && chown root.wheel /bsd" 166.It 167.Li "shutdown -r now" 168.El 169.Pp 170If the system does not come up you can boot using 171.Pa bsd.old . 172.Ss "3. Build a new system" 173.Pp 174Now that you are running using your new kernel you can build a new system. 175It's safer (but slower) to remove and re-build your object directories 176and re-building them before the build. 177The steps are: 178.Pp 179.Bl -bullet -offset indent -compact 180.It 181.Li "cd /usr/obj && mkdir -p .old && sudo mv * .old && sudo rm -rf .old &" 182.br 183This moves all your existing object out of the way and then removes them in 184the background. 185.It 186.Li "cd /usr/src && nice make obj" 187.br 188this re-builds your obj directories 189.It 190.Li su 191.It 192.Li "nice make build" 193.br 194If you have set 195.Xr sudo 8 196up, you can combine this with the previous step using the command 197.Bd -literal -offset indent -compact 198nice make SUDO=sudo build 199.Ed 200.It 201Update 202.Pa /etc , 203.Pa /var , 204and 205.Pa /dev/MAKEDEV 206by hand. 207.El 208.Pp 209At this point your system is up-to-date and running the code that you 210are going to make into a release. 211.Ss "4. Make and validate the system release" 212.Pp 213The system release consists of a generic kernel, one 214.Tn CD\-ROM 215and two floppy boot-able file-systems, the release 216.Sq tarballs , 217installation instructions, and checksum files. 218.Pp 219The release process requires two work areas. 220They are: 221.Bl -tag -width "RELEASEDIR " 222.It Va DESTDIR 223This is the name of a directory which will be the root of a a complete 224.Ox 225installation, thus it must be on a disk partition large enough to 226store the entire operating system (less 227.Tn X11R6 228and any third party 229.Sq packages ) . 230The directory can be removed once the release is created. 231In any case the release process ensures the directory is empty before starting. 232.It Va RELEASEDIR 233This is the name of a directory where the release output files are stored. 234The following process will create the directory if necessary. 235.It " " 236.Sy Warning : 237.Va DESTDIR 238and 239.Va RELEASEDIR 240must not refer to any directory with 241.Pa /mnt 242in its path as 243.Pa /mnt 244is used in the release generation process. 245.El 246.Pp 247The floppy and 248.Tn CD\-ROM 249.Pa RAMDISK 250images require a special tool which is created first. 251The release process is: 252.Pp 253.Bl -bullet -offset indent -compact 254.It 255.Li su 256.br 257you must be root to create a release 258.It 259.Li "cd /usr/src/distrib/crunch && make clean && make && make install" 260.br 261create the special tools needed to build the release 262.It 263.Li "export DESTDIR=your-destdir RELEASEDIR=your-releasedir" 264.It 265.Li "test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && rm -rf ${DESTDIR}- &" 266.It 267.Li "mkdir -p ${DESTDIR} ${RELEASEDIR}" 268.br 269these two steps ensure 270.Va ${DESTDIR} 271exists as an empty directory and 272.Va ${RELEASEDIR} 273exists. 274.Va ${RELEASEDIR} 275need not be empty. 276.It 277.Li "cd /usr/src/etc && nice make release" 278.It 279.Li "cd /usr/src/distrib/sets && csh checkflist" 280.br 281this checks that the contents of 282.Va ${DESTDIR} 283pretty much match the contents of the release 284.Sq tarballs . 285.It 286.Li "unset RELEASEDIR DESTDIR" 287.El 288.Pp 289At this point you have most of an 290.Ox 291release. 292The only thing missing is 293.Va X11R6 294(which is covered in the next section). 295.Ss "5. Build and install XF4" 296.Pp 297The 298.Va XF4 299tree is primarily 300.Xr imake 1 No Ns -based 301and doesn't contain the 302.Dq obj 303directory mechanism that comes with Berkeley 304.Xr make 1 . 305While the tree can be built in place, it's better to refrain from 306polluting the cvs sources. 307An alternate build location needs to be selected, large enough to hold the 308.Tn X11R6 309object files, libraries, and binaries. 310Call this location 311.Va XF4BLD . 312.Va XF4SRC 313is the path to your 314.Tn X11R6 315sources. 316Once you've selected 317.Va XF4BLD 318the build process is: 319.Pp 320.Bl -bullet -offset indent -compact 321.It 322.Li su 323.It 324.Li "test -d XF4BLD && mv XF4BLD XF4BLD- && rm -rf XF4BLD- &" 325.It 326.Li "mkdir -p XF4BLD" 327.It 328.Li "cd XF4BLD && lndir XF4SRC && nice make build" 329.El 330.Pp 331.Sy Note (only for i386) : 332.Pa XF86Setup , 333built and installed above, requires version 8.3 of the 334.Pa tcl/tk 335libraries. They must be installed to do a proper build. Version 8.3 of 336.Pa tcl/tk 337can be found in the ports tree at 338.Pa /usr/ports/lang/tcl/8.3/ 339and 340.Pa /usr/ports/x11/tk/8.3/ . 341Version 8.3 is required to build XF4. 342Version 8.3 may coexist with version 8.0. 343.Pp 344The above method mimics a 345.Ic "make build" 346in the 347.Pa /usr/src 348directory. 349.Pa X11R6 350is created and installed in 351.Pa 352/usr/X11R6 . 353However, the install phase of the build does 354.Em not 355overwrite 356.Pa /etc/X11/xdm . 357That directory must be installed by hand. Or you can 358.Ic "cd /etc/X11 && mv xdm xdm-" 359before the build and copy any local configuration from 360.Pa xdm- 361to 362.Pa xdm 363after the build. 364.Ss "6. Make and validate the XF4 release" 365.Pp 366.Va X11R6 367uses the same 368.Va DESTDIR 369and 370.Va RELEASEDIR 371mechanism noted in the section on building a system release, above. 372They may be the same values used above, but be warned that the 373contents of 374.Va DESTDIR 375will be removed if you follow this procedure. However, 376.Va DESTDIR 377should not be the same directory used to build the system release. 378It may be the same if you don't care to keep the contents of the 379system release 380.Va DESTDIR . 381(The XF4 382.Va DESTDIR 383needs to be emptied for release checklist processing.) 384.Pp 385The steps to build the release are (assuming you are still root, and still in 386.Va XF4BLD ) : 387.Pp 388.Bl -bullet -offset indent -compact 389.It 390.Li "export DESTDIR=your-destdir RELEASEDIR=your-releasedir" 391.It 392.Li "test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && rm -rf ${DESTDIR}- &" 393.It 394.Li "mkdir -p ${DESTDIR} ${RELEASEDIR}" 395.It 396.Li "nice make release" 397.It 398.Li "unset RELEASEDIR DESTDIR" 399.El 400.Pp 401At this point you have both system and 402.Tn X11R6 403.Sq tarballs 404in your release directory. 405.Ss "7. Make the third party packages" 406.Pp 407The 408.Sq ports 409sub-system of contributed applications is described in 410.Xr ports 7 . 411For ease of installation ports can be pre-compiled into 412.Sq packages 413which can then be installed onto machines using 414.Xr pkg_add 1 . 415Packages are created by: 416.Pp 417.Bl -bullet -offset indent -compact 418.It 419Select an application to build, we'll call it 420.Va CATEGORY/PORT . 421.It 422.Li "cd /usr/ports/CATEGORY/PORT" 423.It 424.Li su 425.It 426.Li "make package" 427.El 428.Pp 429That's all there is to it. 430.Sh SEE ALSO 431.Xr cvs 1 , 432.Xr pkg_add 1 , 433.Xr ports 7 , 434.Xr sudo 8 435.Sh HISTORY 436This document first appeared in 437.Ox 2.8 . 438