.\"	$OpenBSD: release.8,v 1.80 2016/11/23 20:34:48 tb Exp $
.\"
.\"	Copyright (c) 2000 Marco S. Hyman
.\"
.\"	Permission to copy all or part of this material for any purpose is
.\"	granted provided that the above copyright notice and this paragraph
.\"	are duplicated in all copies.  THIS SOFTWARE IS PROVIDED ``AS IS''
.\"	AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
.\"	LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\"	FOR A PARTICULAR PURPOSE.
.\"
.Dd $Mdocdate: November 23 2016 $
.Dt RELEASE 8
.Os
.Sh NAME
.Nm release
.Nd building an OpenBSD release
.Sh DESCRIPTION
There are several steps necessary to build a system release.
They are:
.Pp
.Bl -enum -compact -offset indent
.It
Update sources.
.It
Build and install a new kernel.
.It
Build a new system.
.It
Make and validate the system release.
.It
Build and install xenocara.
.It
Make and validate the xenocara release.
.It
Make the third party packages.
.It
Create boot and installation disk images.
.El
.Pp
The following sections describe each of the required steps
for the
.Em release
and
.Em stable
branches.
To build a
.Em current
release, additional steps may be required.
See
.Lk https://www.openbsd.org/faq/current.html
for any needed workarounds.
.Pp
Commands to be run as a user are preceded by a dollar sign
.Sq $ .
Commands that must be run as the superuser are preceded by a hash mark
.Sq # .
Privileges will be de-escalated to the user
.Sy build
whenever possible.
.Pp
Most of the defaults can be overridden by setting
the appropriate variables in
.Xr mk.conf 5 .
.Ss 1. Update sources
A
.Nm
should always start from a known set of
.Em coherent
sources.
The easiest way to ensure that the sources are complete and coherent
is to check them out using the appropriate
.Xr cvs 1
tag.
There are two families of tags:
.Bl -tag -width OPENBSD_x_y_BASE
.It OPENBSD_x_y_BASE
This tag marks the source for the
.Ox x.y
release.
.It OPENBSD_x_y
This tag is a moving target.
It marks the sources that belong to the stable branch and
contains the patches described in
.Lk https://www.openbsd.org/stable.html .
.El
.Pp
See
.Lk https://www.openbsd.org/anoncvs.html
for instructions on fetching the sources for the first time.
.Pp
To update existing sources to the versions identified by one of the above
tags, use the commands:
.Bd -literal -offset indent
$ cd /usr/src && cvs up -r TAG -Pd
$ cd /usr/xenocara && cvs up -r TAG -Pd
$ cd /usr/ports && cvs up -r TAG -Pd
.Ed
.Pp
.Sy Warning :
.Xr cvs 1
tags are
.Sq sticky .
See
.Xr cvs 1
for more information.
.Ss 2. Build and install a new kernel
Always build and install a new kernel and reboot before
building the programs that will use the kernel.
This ensures that any new system calls, for example, will be present
when needed.
.Pp
.Dl # cd /sys/arch/$(machine)/compile/GENERIC.MP
.Pp
Replace
.Pa GENERIC.MP
with a different kernel configuration if necessary.
.Pp
Create the build directory and configuration file,
then compile and install the kernel:
.Bd -literal -offset indent
# make obj
# make config
# make && make install
.Ed
.Pp
The current kernel is copied to
.Pa /obsd
and the new kernel to
.Pa /bsd .
Reboot.
.Ss 3. Build a new system
The build process will place the object files in a tree under
.Pa /usr/obj .
This directory should be empty and owned by build:wobj with mode 770.
.Pp
Create the tree of obj directories and begin the build:
.Bd -literal -offset indent
# cd /usr/src
# make obj && make build
.Ed
.Pp
After the build is completed, update
.Pa /etc ,
.Pa /var ,
and
.Pa /dev ,
using
.Xr sysmerge 8
and
.Xr MAKEDEV 8 .
.Pp
At this point, the system is up-to-date and running the code that will be
made into a release.
.Ss 4. Make and validate the system release
The system release consists of at least one generic kernel,
some installation media, the release tarballs,
installation instructions, and checksum files.
.Pp
Create a
.Va RELEASEDIR
directory to store the release files.
This directory must be writable by
.Sy build .
.Pp
To build a release, it is necessary to prepare a filesystem mounted with the
.Em noperm
.Xr mount 8
option.
The root of this filesystem must have owner
.Sy build
and mode 700.
On this filesystem, create a
.Va DESTDIR
directory.
This will be the root of a complete
.Ox
installation.
.Pp
.Sy Warning :
.Va DESTDIR
and
.Va RELEASEDIR
must not refer to any directory with
.Pa /mnt
in its path, as
.Pa /mnt
is used in the release generation process.
The
.Xr vnd 4
device vnd0
is also used and must not be configured.
.Pp
Make the release and check that the contents of
.Va DESTDIR
match the contents of the release tarballs:
.Bd -literal -offset indent
# export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir
# cd /usr/src/etc && make release
# cd /usr/src/distrib/sets && sh checkflist
# unset RELEASEDIR DESTDIR
.Ed
.Ss 5. Build and install xenocara
Xenocara is based on the X.Org modular build system.
Its sources are supposed to be in
.Pa /usr/xenocara .
The
.Pa /usr/src
tree is also needed while building xenocara.
The object directory
.Pa /usr/xobj
should be empty and owned by build:wobj with permissions 770.
.Pp
The following steps will build and install everything for the first time.
.Bd -literal -offset indent
# cd /usr/xenocara
# make bootstrap
# make obj
# make build
.Ed
.Pp
The X Window System is created and installed in
.Pa /usr/X11R6 .
.Ss 6. Make and validate the xenocara release
Xenocara uses
.Va DESTDIR
and
.Va RELEASEDIR
as described above.
While they may be set to the values used to build the rest of the
system, be aware that the existing contents of
.Va DESTDIR
will be removed as part of the xenocara build (this is necessary for
release checklist processing).
.Pp
The steps to build the release are:
.Bd -literal -offset indent
# export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir
# make release
# unset RELEASEDIR DESTDIR
.Ed
.Pp
At this point,
.Ox
system and X Window System tarballs are in
.Va RELEASEDIR .
.Ss 7. Make the third party packages
The ports subsystem of contributed applications is capable of producing
packages for installation, either individually or in bulk.
This is described in
.Xr ports 7 .
.Ss 8. Create boot and installation disk images
At this point,
.Va RELEASEDIR
contains the
.Ox
tarballs necessary to upgrade.
.Pp
The following steps will create the boot and installation images
.No install${ Ns Ar VERSION Ns }.fs
and
.No install${ Ns Ar VERSION Ns }.iso
suitable for installs without network connectivity.
These images contain the tarballs and ports built in the previous
steps.
.Bd -literal -offset indent
# export RELDIR=your-releasedir
# export RELXDIR=your-xenocara-releasedir
# cd /usr/src/distrib/$(machine)/iso && make
# make install
.Ed
.Pp
The two installer images are now stored in the local release
directory.
.Sh SEE ALSO
.Xr cvs 1 ,
.Xr pkg_add 1 ,
.Xr mk.conf 5 ,
.Xr ports 7 ,
.Xr sysmerge 8
.Sh HISTORY
This document first appeared in
.Ox 2.8 .