1.\" $OpenBSD: release.8,v 1.96 2020/08/20 06:45:48 tb 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: August 20 2020 $ 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 160On arm64 and armv7 architectures, additional files are required. 161For armv7, install u-boot-arm and dtb using 162.Xr pkg_add 1 163or from 164.Xr ports 7 . 165For arm64, install raspberrypi-firmware and u-boot-aarch64. 166.Pp 167Create a 168.Va RELEASEDIR 169directory to store the release files. 170This directory must be writable by 171.Sy build . 172.Pp 173To build a release, it is necessary to prepare a filesystem mounted with the 174.Em noperm 175.Xr mount 8 176option. 177Either standard FFS or 178.Xr mount_mfs 8 179may be used. 180The root of this filesystem must have owner 181.Sy build 182and mode 700. 183On this filesystem, create a 184.Va DESTDIR 185directory. 186This will be the root of a complete 187.Ox 188installation. 189.Pp 190.Sy Warning : 191.Va DESTDIR 192and 193.Va RELEASEDIR 194must not refer to any directory with 195.Pa /mnt 196in its path, as 197.Pa /mnt 198is used in the release generation process. 199The 200.Xr vnd 4 201device vnd0 202is also used and must not be configured. 203.Pp 204Make the release and check the contents of the release tarballs: 205.Bd -literal -offset indent 206# export DESTDIR=your-destdir RELEASEDIR=your-releasedir 207# cd /usr/src/etc && make release 208# cd /usr/src/distrib/sets && sh checkflist 209# unset RELEASEDIR DESTDIR 210.Ed 211.Ss 5. Build and install Xenocara 212Xenocara is based on the X.Org modular build system. 213Its sources are supposed to be in 214.Pa /usr/xenocara . 215The 216.Pa /usr/src 217tree is also needed while building Xenocara. 218The object directory 219.Pa /usr/xobj 220should be empty and owned by build:wobj with mode 770. 221.Pp 222The following steps will build and install Xenocara. 223.Bd -literal -offset indent 224# cd /usr/xenocara 225# make bootstrap 226# make obj 227# make build 228.Ed 229.Ss 6. Make and validate the Xenocara release 230Xenocara uses 231.Va DESTDIR 232and 233.Va RELEASEDIR 234as described above. 235Use a different 236.Va DESTDIR 237for the Xenocara release than for the base release, 238as the contents of 239.Va DESTDIR 240will be removed. 241.Pp 242The steps to build and validate the Xenocara release are: 243.Bd -literal -offset indent 244# export DESTDIR=your-destdir RELEASEDIR=your-releasedir 245# make release 246# make checkdist 247# unset RELEASEDIR DESTDIR 248.Ed 249.Pp 250At this point, 251.Ox 252base system and X Window System tarballs are in 253.Va RELEASEDIR . 254.Ss 7. Make the third party packages 255The ports subsystem of contributed applications is capable of producing 256packages for installation, either individually or in bulk. 257This is described in 258.Xr ports 7 . 259.Ss 8. Create boot and installation disk images 260The disk images 261.No install${ Ns Va VERSION Ns }.img 262and 263.No install${ Ns Va VERSION Ns }.iso 264are suitable for installs without network connectivity. 265They contain the tarballs and ports built in the previous steps. 266.Bd -literal -offset indent 267# export RELDIR=your-releasedir RELXDIR=your-xenocara-releasedir 268# cd /usr/src/distrib/$(machine)/iso && make 269# make install 270.Ed 271.Pp 272The two installer images are now stored in the local release 273directory. 274.Sh SEE ALSO 275.Xr cvs 1 , 276.Xr pkg_add 1 , 277.Xr mk.conf 5 , 278.Xr ports 7 , 279.Xr sysmerge 8 280.Sh HISTORY 281This document first appeared in 282.Ox 2.8 . 283