1.\" $OpenBSD: release.8,v 1.94 2018/06/23 23:19:11 rob Exp $ 2.\" 3.\" Copyright (c) 2000 Marco S. Hyman 4.\" Copyright (c) 2016 Theo Buehler <tb@openbsd.org> 5.\" 6.\" Permission to copy all or part of this material for any purpose is 7.\" granted provided that the above copyright notice and this paragraph 8.\" are duplicated in all copies. THIS SOFTWARE IS PROVIDED ``AS IS'' 9.\" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT 10.\" LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 11.\" FOR A PARTICULAR PURPOSE. 12.\" 13.Dd $Mdocdate: June 23 2018 $ 14.Dt RELEASE 8 15.Os 16.Sh NAME 17.Nm release 18.Nd building an OpenBSD release 19.Sh DESCRIPTION 20There are several steps necessary to build a release: 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 base system. 29.It 30Make and validate the base 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 41This manual describes the steps for the 42.Em release 43and 44.Em stable 45branches. 46To build a 47.Em current 48release, additional steps may be required. 49See 50.Lk https://www.openbsd.org/faq/current.html 51for any needed workarounds. 52.Pp 53Commands to be run as a user are preceded by a dollar sign 54.Sq $ . 55Commands that must be run as the superuser are preceded by a hash mark 56.Sq # . 57Privileges will be de-escalated to the user 58.Sy build 59whenever possible. 60.Pp 61Most of the defaults can be overridden by setting 62the appropriate variables in 63.Xr mk.conf 5 . 64.Ss 1. Update sources 65A 66.Nm 67should use sources that were checked out using the same 68.Xr cvs 1 69tag. 70There are two families of tags: 71.Bl -tag -width OPENBSD_x_y_BASE 72.It OPENBSD_x_y_BASE 73The sources for the 74.Ox x.y 75release. 76.It OPENBSD_x_y 77The sources for the 78.Ox x.y 79stable branch. 80It contains the patches described in 81.Lk https://www.openbsd.org/stable.html . 82.El 83.Pp 84See 85.Lk https://www.openbsd.org/anoncvs.html 86for instructions on fetching the sources for the first time. 87.Pp 88To update existing 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 /usr/xenocara && cvs up -r TAG -Pd 93$ cd /usr/ports && cvs up -r TAG -Pd 94.Ed 95.Pp 96.Sy Warning : 97.Xr cvs 1 98tags are 99.Sq sticky . 100See 101.Xr cvs 1 102for more information. 103.Ss 2. Build and install a new kernel 104Always build and install a new kernel and reboot before 105building the programs that will use the kernel. 106This ensures that any new system calls, for example, will be present 107when needed. 108.Pp 109.Dl # cd /sys/arch/$(machine)/compile/GENERIC.MP 110.Pp 111Replace 112.Pa GENERIC.MP 113with a different kernel configuration if necessary. 114.Pp 115Create the build directory and configuration file, 116then compile and install the kernel: 117.Bd -literal -offset indent 118# make obj 119# make config 120# make && make install 121.Ed 122.Pp 123The current kernel is copied to 124.Pa /obsd 125and the new kernel to 126.Pa /bsd . 127Reboot. 128.Ss 3. Build a new base system 129The build process will place the object files in a tree under 130.Pa /usr/obj . 131This directory must be owned by build:wobj with mode 770. 132.Pp 133Create the tree of obj directories and begin the build: 134.Bd -literal -offset indent 135# cd /usr/src 136# make obj && make build 137.Ed 138.Pp 139After the build is completed, update 140.Pa /etc , 141.Pa /var , 142and 143.Pa /dev , 144using 145.Xr sysmerge 8 146and 147.Xr MAKEDEV 8 : 148.Bd -literal -offset indent 149# sysmerge 150# cd /dev && ./MAKEDEV all 151.Ed 152.Pp 153At this point, the base system is up to date with the code 154that will be made into a release. 155.Ss 4. Make and validate the base system release 156The base system release consists of at least one generic kernel, 157some installation media, the release tarballs, 158installation instructions, and checksum files. 159.Pp 160Create a 161.Va RELEASEDIR 162directory to store the release files. 163This directory must be writable by 164.Sy build . 165.Pp 166To build a release, it is necessary to prepare a filesystem mounted with the 167.Em noperm 168.Xr mount 8 169option. 170Either standard FFS or 171.Xr mount_mfs 8 172may be used. 173The root of this filesystem must have owner 174.Sy build 175and mode 700. 176On this filesystem, create a 177.Va DESTDIR 178directory. 179This will be the root of a complete 180.Ox 181installation. 182.Pp 183.Sy Warning : 184.Va DESTDIR 185and 186.Va RELEASEDIR 187must not refer to any directory with 188.Pa /mnt 189in its path, as 190.Pa /mnt 191is used in the release generation process. 192The 193.Xr vnd 4 194device vnd0 195is also used and must not be configured. 196.Pp 197Make the release and check the contents of the release tarballs: 198.Bd -literal -offset indent 199# export DESTDIR=your-destdir RELEASEDIR=your-releasedir 200# cd /usr/src/etc && make release 201# cd /usr/src/distrib/sets && sh checkflist 202# unset RELEASEDIR DESTDIR 203.Ed 204.Ss 5. Build and install Xenocara 205Xenocara is based on the X.Org modular build system. 206Its sources are supposed to be in 207.Pa /usr/xenocara . 208The 209.Pa /usr/src 210tree is also needed while building Xenocara. 211The object directory 212.Pa /usr/xobj 213should be empty and owned by build:wobj with mode 770. 214.Pp 215The following steps will build and install Xenocara. 216.Bd -literal -offset indent 217# cd /usr/xenocara 218# make bootstrap 219# make obj 220# make build 221.Ed 222.Ss 6. Make and validate the Xenocara release 223Xenocara uses 224.Va DESTDIR 225and 226.Va RELEASEDIR 227as described above. 228Use a different 229.Va DESTDIR 230for the Xenocara release than for the base release, 231as the contents of 232.Va DESTDIR 233will be removed. 234.Pp 235The steps to build and validate the Xenocara release are: 236.Bd -literal -offset indent 237# export DESTDIR=your-destdir RELEASEDIR=your-releasedir 238# make release 239# make checkdist 240# unset RELEASEDIR DESTDIR 241.Ed 242.Pp 243At this point, 244.Ox 245base system and X Window System tarballs are in 246.Va RELEASEDIR . 247.Ss 7. Make the third party packages 248The ports subsystem of contributed applications is capable of producing 249packages for installation, either individually or in bulk. 250This is described in 251.Xr ports 7 . 252.Ss 8. Create boot and installation disk images 253The disk images 254.No install${ Ns Va VERSION Ns }.fs 255and 256.No install${ Ns Va VERSION Ns }.iso 257are suitable for installs without network connectivity. 258They contain the tarballs and ports built in the previous steps. 259.Bd -literal -offset indent 260# export RELDIR=your-releasedir RELXDIR=your-xenocara-releasedir 261# cd /usr/src/distrib/$(machine)/iso && make 262# make install 263.Ed 264.Pp 265The two installer images are now stored in the local release 266directory. 267.Sh SEE ALSO 268.Xr cvs 1 , 269.Xr pkg_add 1 , 270.Xr mk.conf 5 , 271.Xr ports 7 , 272.Xr sysmerge 8 273.Sh HISTORY 274This document first appeared in 275.Ox 2.8 . 276