1.\" $OpenBSD: release.8,v 1.56 2008/08/23 07:05:40 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 $Mdocdate: August 23 2008 $ 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 -offset indent 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 xenocara. 35.It 36Make and validate the xenocara 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 dollar 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.Bd -literal -offset indent 97$ cd /usr/src && cvs up -r TAG -Pd 98$ cd XSRCDIR && cvs up -r TAG -Pd 99$ cd PORTSPATH && cvs up -r TAG -Pd 100.Ed 101.Pp 102Replace 103.Va XSRCDIR 104with the path to your X Window System sources. 105Replace 106.Va PORTSPATH 107with the path to your ports tree sources, typically 108.Pa /usr/ports . 109The above commands assume an existing source tree. 110.Pp 111See 112.Pa http://www.openbsd.org/anoncvs.html 113for instructions on fetching the sources for the first time. 114.Pp 115.Sy Warning : 116.Tn CVS 117tags are 118.Sq sticky . 119See 120.Xr cvs 1 121for more information. 122.Ss 2. Build and install a new kernel 123For safety, you should always build and install a new kernel before 124building the programs that will use the kernel. 125This ensures that any new system calls, for example, will be present 126when needed. 127To build a kernel the steps are: 128.Pp 129Change the current working directory. 130.Va ${ARCH} 131is the architecture of your machine, e.g.\& 132.Li i386 . 133.Pp 134.Dl $ cd /sys/arch/${ARCH}/conf 135.Pp 136Edit the kernel configuration file. 137.Va ${NAME} 138is your kernel configuration file. 139You should 140.Em not 141edit 142.Li GENERIC ; 143create your own kernel configuration if you need to make modifications. 144If using 145.Li GENERIC 146you can skip this step. 147And yes, you may use 148.Xr vi 1 , 149.Xr mg 1 , 150or any other editor you choose. 151.Pp 152.Dl $ vi ${NAME} 153.Pp 154Build the kernel compilation directory and compile the kernel: 155.Bd -literal -offset indent 156$ config ${NAME} 157$ cd ../compile/${NAME} 158$ make clean && make depend && make 159.Ed 160.Pp 161(In this instance 162.Li "make clean" 163is your friend.) 164.Pp 165Replace the old kernel and reboot. 166The current kernel is copied to 167.Pa /obsd 168and the new kernel to 169.Pa /bsd . 170.Bd -literal -offset indent 171$ su 172# make install 173# shutdown -r now 174.Ed 175.Pp 176If the system does not come up you can boot using 177.Pa /obsd . 178.Ss 3. Build a new system 179Now that you are running your new kernel you can build a new system. 180It's safer (but slower) to remove your object directories and re-create 181them before the build. 182The steps are: 183.Pp 184Move all your existing object files out of the way and then remove 185them in the background: 186.Bd -literal -offset indent 187$ cd /usr/obj && mkdir -p .old && sudo mv * .old && \e 188 sudo rm -rf .old & 189.Ed 190.Pp 191Re-build your obj directories: 192.Pp 193.Dl $ cd /usr/src && nice make obj 194.Pp 195Create directories that might be missing: 196.Pp 197.Dl $ cd /usr/src/etc && env DESTDIR=/ sudo make distrib-dirs 198.Pp 199Begin the build: 200.Bd -literal -offset indent 201$ su 202# cd /usr/src && nice make build 203.Ed 204.Pp 205If you have set 206.Xr sudo 8 207up, you can combine this with the previous step using the command 208.Pp 209.Dl $ nice make SUDO=sudo build 210.Pp 211Update 212.Pa /etc , 213.Pa /var , 214and 215.Pa /dev/MAKEDEV , 216either by hand or using 217.Xr sysmerge 8 . 218.Pp 219At this point your system is up-to-date and running the code that you 220are going to make into a release. 221.Ss 4. Make and validate the system release 222The system release consists of a generic kernel, one 223.Tn CD-ROM 224and two floppy bootable file systems, the release 225.Sq tarballs , 226installation instructions, and checksum files. 227.Pp 228The release process requires two work areas. 229They are: 230.Bl -tag -width "RELEASEDIR " 231.It Va DESTDIR 232This is the name of a directory which will be the root of a complete 233.Ox 234installation, thus it must be on a disk partition large enough to store the 235entire operating system (less the X Window System and any third party 236.Sq packages ) . 237The directory can be removed once the release is created. 238In any case the release process ensures the directory is empty before starting. 239.It Va RELEASEDIR 240This is the name of a directory where the release output files are stored. 241The following process will create the directory if necessary. 242.It " " 243.Sy Warning : 244.Va DESTDIR 245and 246.Va RELEASEDIR 247must not refer to any directory with 248.Pa /mnt 249in its path, as 250.Pa /mnt 251is used in the release generation process. 252Additionally the first 253.Xr svnd 4 254device, svnd0, 255is also used and must not be configured. 256.El 257.Pp 258The release process is: 259.Pp 260Ensure 261.Va ${DESTDIR} 262exists as an empty directory and 263.Va ${RELEASEDIR} 264exists. 265.Va ${RELEASEDIR} 266need not be empty. 267You must be root to create a release: 268.Bd -literal -offset indent 269$ su 270# export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir 271# test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \e 272 rm -rf ${DESTDIR}- & 273# mkdir -p ${DESTDIR} ${RELEASEDIR} 274.Ed 275.Pp 276Check that the contents of 277.Va ${DESTDIR} 278pretty much match the contents of the release 279.Sq tarballs : 280.Bd -literal -offset indent 281# cd /usr/src/etc && nice make release 282# cd /usr/src/distrib/sets && sh checkflist 283# unset RELEASEDIR DESTDIR 284.Ed 285.Pp 286At this point you have most of an 287.Ox 288release. 289The only thing missing is the X Window System 290(which is covered in the next section). 291.Ss 5. Build and install xenocara 292.Va Xenocara 293is based on the X.Org modular build system. 294Xenocara sources are supposed to be in 295.Va XSRCDIR 296which defaults to 297.Pa /usr/xenocara . 298This variable should be set in 299.Xr mk.conf 5 300if a non-default value is used. 301The following steps will build and install everything for the first time. 302.Bd -literal -offset indent 303$ su 304# cd XSRCDIR 305# make bootstrap 306# make obj 307# make build 308.Ed 309.Pp 310The X Window System is created and installed in 311.Pa /usr/X11R6 . 312.Ss 6. Make and validate the xenocara release 313.Va xenocara 314uses 315.Va DESTDIR 316and 317.Va RELEASEDIR 318as described above. 319While they may be set to the values used to build the rest of the 320system, be aware that the existing contents of 321.Va DESTDIR 322will be removed as part of the xenocara build (this is necessary for 323release checklist processing). 324.Pp 325The steps to build the release are (assuming you are still root, and still in 326.Va XSRCDIR ) : 327.Bd -literal -offset indent 328# export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir 329# test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \e 330 rm -rf ${DESTDIR}- & 331# mkdir -p ${DESTDIR} ${RELEASEDIR} 332# nice make release 333# unset RELEASEDIR DESTDIR 334.Ed 335.Pp 336At this point you have both 337.Ox 338system and X Window System 339.Sq tarballs 340in your release directory. 341.Ss 7. Make the third party packages 342The 343.Sq ports 344sub-system of contributed applications is described in 345.Xr ports 7 . 346For ease of installation ports can be pre-compiled into 347.Sq packages 348which can then be installed on multiple machines using 349.Xr pkg_add 1 . 350Packages are created by selecting an application to build 351(we'll call this one CATEGORY/PORT) and then running the following: 352as root: 353.Bd -literal -offset indent 354$ cd /usr/ports/CATEGORY/PORT 355$ su 356# make package 357.Ed 358.Pp 359That's all there is to it. 360.Sh SEE ALSO 361.Xr cvs 1 , 362.Xr pkg_add 1 , 363.Xr ports 7 , 364.Xr sudo 8 , 365.Xr sysmerge 8 366.Sh HISTORY 367This document first appeared in 368.Ox 2.8 . 369