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