1.\" $OpenBSD: release.8,v 1.60 2009/04/08 15:59:53 stsp 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: April 8 2009 $ 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 at least one generic kernel, 223some installation media, the release 224.Sq tarballs , 225installation instructions, and checksum files. 226.Pp 227The release process requires two work areas. 228They are: 229.Bl -tag -width "RELEASEDIR " 230.It Va DESTDIR 231This is the name of a directory which will be the root of a complete 232.Ox 233installation, thus it must be on a disk partition large enough to store the 234entire operating system (less the X Window System and any third party 235.Sq packages ) . 236The directory can be removed once the release is created. 237In any case the release process ensures the directory is empty before starting. 238.It Va RELEASEDIR 239This is the name of a directory where the release output files are stored. 240The following process will create the directory if necessary. 241.It " " 242.Sy Warning : 243.Va DESTDIR 244and 245.Va RELEASEDIR 246must not refer to any directory with 247.Pa /mnt 248in its path, as 249.Pa /mnt 250is used in the release generation process. 251Additionally the first 252.Xr svnd 4 253device, svnd0, 254is also used and must not be configured. 255.El 256.Pp 257The release process is: 258.Pp 259Ensure 260.Va ${DESTDIR} 261exists as an empty directory and 262.Va ${RELEASEDIR} 263exists. 264.Va ${RELEASEDIR} 265need not be empty. 266You must be root to create a release: 267.Bd -literal -offset indent 268$ su 269# export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir 270# test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \e 271 rm -rf ${DESTDIR}- & 272# mkdir -p ${DESTDIR} ${RELEASEDIR} 273.Ed 274.Pp 275Make the release and check that the contents of 276.Va ${DESTDIR} 277pretty much match the contents of the release 278.Sq tarballs : 279.Bd -literal -offset indent 280# cd /usr/src/etc && nice make release 281# cd /usr/src/distrib/sets && sh checkflist 282# unset RELEASEDIR DESTDIR 283.Ed 284.Pp 285At this point you have most of an 286.Ox 287release. 288The only thing missing is the X Window System 289(which is covered in the next section). 290.Ss 5. Build and install xenocara 291.Va Xenocara 292is based on the X.Org modular build system. 293Xenocara sources are supposed to be in 294.Va XSRCDIR 295which defaults to 296.Pa /usr/xenocara . 297This variable should be set in 298.Xr mk.conf 5 299if a non-default value is used. 300The 301.Pa /usr/src 302tree is also needed while building xenocara. 303The following steps will build and install everything for the first time. 304.Bd -literal -offset indent 305$ su 306# cd XSRCDIR 307# make bootstrap 308# make obj 309# make build 310.Ed 311.Pp 312The X Window System is created and installed in 313.Pa /usr/X11R6 . 314.Ss 6. Make and validate the xenocara release 315.Va xenocara 316uses 317.Va DESTDIR 318and 319.Va RELEASEDIR 320as described above. 321While they may be set to the values used to build the rest of the 322system, be aware that the existing contents of 323.Va DESTDIR 324will be removed as part of the xenocara build (this is necessary for 325release checklist processing). 326.Pp 327The steps to build the release are (assuming you are still root, and still in 328.Va XSRCDIR ) : 329.Bd -literal -offset indent 330# export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir 331# test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \e 332 rm -rf ${DESTDIR}- & 333# mkdir -p ${DESTDIR} ${RELEASEDIR} 334# nice make release 335# unset RELEASEDIR DESTDIR 336.Ed 337.Pp 338At this point you have both 339.Ox 340system and X Window System 341.Sq tarballs 342in your release directory. 343.Ss 7. Make the third party packages 344The 345.Sq ports 346subsystem of contributed applications is described in 347.Xr ports 7 . 348For ease of installation ports can be pre-compiled into 349.Sq packages 350which can then be installed on multiple machines using 351.Xr pkg_add 1 . 352Packages are created by selecting an application to build 353(we'll call this one CATEGORY/PORT) and then running the following: 354as root: 355.Bd -literal -offset indent 356$ cd /usr/ports/CATEGORY/PORT 357$ su 358# make package 359.Ed 360.Pp 361That's all there is to it. 362.Sh SEE ALSO 363.Xr cvs 1 , 364.Xr pkg_add 1 , 365.Xr ports 7 , 366.Xr sudo 8 , 367.Xr sysmerge 8 368.Sh HISTORY 369This document first appeared in 370.Ox 2.8 . 371