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