1.\" $OpenBSD: release.8,v 1.74 2016/07/23 00:10:15 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: July 23 2016 $ 13.Dt RELEASE 8 14.Os 15.Sh NAME 16.Nm release 17.Nd building an OpenBSD release 18.Sh DESCRIPTION 19There are several steps necessary to build a system release. 20They are: 21.Pp 22.Bl -enum -compact -offset indent 23.It 24Update sources. 25.It 26Build and install a new kernel. 27.It 28Build a new system. 29.It 30Make and validate the system release. 31.It 32Build and install xenocara. 33.It 34Make and validate the xenocara release. 35.It 36Make the third party packages. 37.It 38Create boot and installation disk images. 39.El 40.Pp 41The following sections describe each of the required steps in detail. 42.Pp 43Commands to be run as a user are preceded by a dollar sign 44.Pq Sq $ . 45Commands that must be run as the superuser are preceded by a hash mark 46.Pq Sq # . 47.Ss 1. Update sources 48A 49.Nm 50should always start from a known set of 51.Em coherent 52sources. 53The easiest way to ensure that the sources are complete and coherent 54is to check them out using the 55.Tn CVS 56tag the 57.Ox 58developers add to the repository prior to making a release. 59There are two tags, one which identifies the release as it exists on the 60.Tn CD-ROM 61and another which identifies the 62.Em stable 63branch. 64The 65.Em stable 66branch, starting with 67.Ox 2.7 , 68contains the patches described in 69.Lk http://www.openbsd.org/errata.html . 70The tags are of the form: 71.Bl -tag -width OPENBSD_x_y_BASE 72.It Va OPENBSD_x_y_BASE 73This tag marks the source as it exists on the release 74.Tn CD-ROM 75where 76.Ar x 77is the major release number and 78.Ar y 79is the minor release number. 80.It Va OPENBSD_x_y 81This tag is a moving target. 82It marks the sources that belong to the stable branch. 83This branch 84.Em only 85contains errata, no new features. 86.El 87.Pp 88To update your sources to the versions identified by one of the above 89tags use the commands: 90.Bd -literal -offset indent 91$ cd /usr/src && cvs up -r TAG -Pd 92$ cd XSRCDIR && cvs up -r TAG -Pd 93$ cd PORTSPATH && cvs up -r TAG -Pd 94.Ed 95.Pp 96Replace 97.Va XSRCDIR 98with the path to your X Window System sources, typically 99.Pa /usr/xenocara . 100Replace 101.Va PORTSPATH 102with the path to your ports tree sources, typically 103.Pa /usr/ports . 104The above commands assume an existing source tree. 105.Pp 106See 107.Lk http://www.openbsd.org/anoncvs.html 108for instructions on fetching the sources for the first time. 109.Pp 110.Sy Warning : 111.Tn CVS 112tags are 113.Sq sticky . 114See 115.Xr cvs 1 116for more information. 117.Ss 2. Build and install a new kernel 118For safety, you should always build and install a new kernel before 119building the programs that will use the kernel. 120This ensures that any new system calls, for example, will be present 121when needed. 122To build a kernel the steps are: 123.Pp 124Change the current working directory. 125.Va ${ARCH} 126is the architecture of your machine, e.g.\& 127.Li i386 . 128.Pp 129.Dl $ cd /usr/src/sys/arch/${ARCH}/conf 130.Pp 131Edit the kernel configuration file. 132.Va ${NAME} 133is your kernel configuration file. 134You should 135.Em not 136edit 137.Li GENERIC ; 138create your own kernel configuration if you need to make modifications. 139If using 140.Li GENERIC 141you can skip this step. 142And yes, you may use 143.Xr vi 1 , 144.Xr mg 1 , 145or any other editor you choose. 146.Pp 147.Dl $ vi ${NAME} 148.Pp 149Build the kernel compilation directory and compile the kernel: 150.Bd -literal -offset indent 151$ config ${NAME} 152$ cd ../compile/${NAME} 153$ make clean && make 154.Ed 155.Pp 156(In this instance 157.Li "make clean" 158is your friend.) 159.Pp 160Replace the old kernel and reboot. 161The current kernel is copied to 162.Pa /obsd 163and the new kernel to 164.Pa /bsd . 165.Bd -literal -offset indent 166$ su 167# make install 168# shutdown -r now 169.Ed 170.Pp 171If the system does not come up you can boot using 172.Pa /obsd . 173.Ss 3. Build a new system 174Now that you are running your new kernel you can build a new system. 175It's safer (but slower) to remove your object directories and re-create 176them before the build. 177The steps are: 178.Pp 179Move all your existing object files out of the way and then remove 180them in the background: 181.Bd -literal -offset indent 182$ cd /usr/obj && mkdir -p .old && doas mv * .old && \e 183 doas rm -rf .old & 184.Ed 185.Pp 186Re-build your obj directories: 187.Pp 188.Dl $ cd /usr/src && make obj 189.Pp 190Create directories that might be missing: 191.Pp 192.Dl $ cd /usr/src/etc && doas env DESTDIR=/ make distrib-dirs 193.Pp 194Begin the build: 195.Pp 196.Dl $ cd /usr/src && make SUDO=doas build 197.Pp 198Update 199.Pa /etc , 200.Pa /var , 201and 202.Pa /dev/MAKEDEV , 203either by hand or using 204.Xr sysmerge 8 . 205.Pp 206At this point your system is up-to-date and running the code that you 207are going to make into a release. 208.Ss 4. Make and validate the system release 209The system release consists of at least one generic kernel, 210some installation media, the release 211.Sq tarballs , 212installation instructions, and checksum files. 213.Pp 214The release process requires two work areas. 215They are: 216.Bl -tag -width "RELEASEDIR " 217.It Va DESTDIR 218This is the name of a directory which will be the root of a complete 219.Ox 220installation, thus it must be on a disk partition large enough to store the 221entire operating system (less the X Window System and any third party 222.Sq packages ) . 223The directory can be removed once the release is created. 224In any case the release process ensures the directory is empty before starting. 225.It Va RELEASEDIR 226This is the name of a directory where the release output files are stored. 227The following process will create the directory if necessary. 228.It " " 229.Sy Warning : 230.Va DESTDIR 231and 232.Va RELEASEDIR 233must not refer to any directory with 234.Pa /mnt 235in its path, as 236.Pa /mnt 237is used in the release generation process. 238Additionally the first 239.Xr vnd 4 240device, vnd0, 241is also used and must not be configured. 242.El 243.Pp 244The release process is: 245.Pp 246Ensure 247.Va ${DESTDIR} 248exists as an empty directory and 249.Va ${RELEASEDIR} 250exists. 251.Va ${RELEASEDIR} 252need not be empty. 253You must be root to create a release: 254.Bd -literal -offset indent 255$ su 256# export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir 257# test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \e 258 rm -rf ${DESTDIR}- & 259# mkdir -p ${DESTDIR} ${RELEASEDIR} 260.Ed 261.Pp 262Make the release and check that the contents of 263.Va ${DESTDIR} 264pretty much match the contents of the release 265.Sq tarballs : 266.Bd -literal -offset indent 267# cd /usr/src/etc && make release 268# cd /usr/src/distrib/sets && sh checkflist 269# unset RELEASEDIR DESTDIR 270.Ed 271.Pp 272At this point you have most of an 273.Ox 274release. 275The only thing missing is the X Window System 276(which is covered in the next section). 277.Ss 5. Build and install xenocara 278.Va Xenocara 279is based on the X.Org modular build system. 280Xenocara sources are supposed to be in 281.Va XSRCDIR 282which defaults to 283.Pa /usr/xenocara . 284This variable should be set in 285.Xr mk.conf 5 286if a non-default value is used. 287The 288.Pa /usr/src 289tree is also needed while building xenocara. 290The following steps will build and install everything for the first time. 291.Bd -literal -offset indent 292$ su 293# cd XSRCDIR 294# make bootstrap 295# make obj 296# make build 297.Ed 298.Pp 299The X Window System is created and installed in 300.Pa /usr/X11R6 . 301.Ss 6. Make and validate the xenocara release 302.Va xenocara 303uses 304.Va DESTDIR 305and 306.Va RELEASEDIR 307as described above. 308While they may be set to the values used to build the rest of the 309system, be aware that the existing contents of 310.Va DESTDIR 311will be removed as part of the xenocara build (this is necessary for 312release checklist processing). 313.Pp 314The steps to build the release are (assuming you are still root, and still in 315.Va XSRCDIR ) : 316.Bd -literal -offset indent 317# export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir 318# test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \e 319 rm -rf ${DESTDIR}- & 320# mkdir -p ${DESTDIR} ${RELEASEDIR} 321# make release 322# unset RELEASEDIR DESTDIR 323.Ed 324.Pp 325At this point you have both 326.Ox 327system and X Window System 328.Sq tarballs 329in your release directory. 330.Ss 7. Make the third party packages 331The 332.Sq ports 333subsystem of contributed applications is capable of producing 334.Sq packages 335for installation, either individually or in bulk. 336This is described in 337.Xr ports 7 . 338.Ss 8. Create boot and installation disk images 339At this point, 340.Va RELEASEDIR 341contains the 342.Ox 343tarballs necessary to upgrade. 344.Pp 345The following steps will create the boot and installation images 346.No install${ Ns Ar VERSION Ns }.fs 347and 348.No install${ Ns Ar VERSION Ns }.iso 349suitable for installs without network connectivity. 350These images contain the tarballs and ports built in the previous 351steps. 352.Bd -literal -offset indent 353# export RELDIR=your-releasedir 354# export RELXDIR=your-xenocara-releasedir 355# cd /usr/src/distrib/${ARCH}/iso && make 356# make install 357# unset RELDIR RELXDIR 358.Ed 359.Pp 360The two installer images are now stored in the local release 361directory. 362.Sh SEE ALSO 363.Xr cvs 1 , 364.Xr doas 1 , 365.Xr pkg_add 1 , 366.Xr ports 7 , 367.Xr sysmerge 8 368.Sh HISTORY 369This document first appeared in 370.Ox 2.8 . 371