RELEASE(8)              OpenBSD System Manager's Manual             RELEASE(8)

NAME
     release - building an OpenBSD release

DESCRIPTION
     There are several steps necessary to build a system release.  They are:

           1.   Update sources.
           2.   Build and install a new kernel.
           3.   Build a new system.
           4.   Make and validate the system release.
           5.   Build and install xenocara.
           6.   Make and validate the xenocara release.
           7.   Make the third party packages.

     The following sections describe each of the required steps in detail.

     Commands to be run as a user with write permissions on the source and
     ports trees (/usr/src and /usr/ports respectively) are preceded by a dol-
     lar sign (`$').  Commands that must be run as the superuser are preceded
     by a hash mark (`#').

   1. Update sources
     A release should always start from a known set of coherent sources.  The
     easiest way to ensure that the sources are complete and coherent is to
     check them out using the CVS tag the OpenBSD developers add to the repos-
     itory prior to making a release.  There are two tags, one which identi-
     fies the release as it exists on the CD-ROM and another which identifies
     the stable branch.  The stable branch, starting with OpenBSD 2.7, con-
     tains the patches described in http://www.openbsd.org/errata.html.  The
     tags are of the form:

     OPENBSD_x_y_BASE  This tag marks the source as it exists on the release
                       CD-ROM where x is the major release number and y is the
                       minor release number.

     OPENBSD_x_y       This tag is a moving target.  It marks the sources that
                       belong to the stable branch.  This branch only contains
                       errata, no new features.

     To update your sources to the versions identified by one of the above
     tags use the commands:

           $ cd /usr/src && cvs up -r TAG -Pd
           $ cd XSRCDIR && cvs up -r TAG -Pd
           $ cd PORTSPATH && cvs up -r TAG -Pd

     Replace XSRCDIR with the path to your X Window System sources.  Replace
     PORTSPATH with the path to your ports tree sources, typically /usr/ports.
     The above commands assume an existing source tree.

     See http://www.openbsd.org/anoncvs.html for instructions on fetching the
     sources for the first time.

     Warning: CVS tags are `sticky'.  See cvs(1) for more information.

   2. Build and install a new kernel
     For safety, you should always build and install a new kernel before
     building the programs that will use the kernel.  This ensures that any
     new system calls, for example, will be present when needed.  To build a
     kernel the steps are:

     Change the current working directory.  ${ARCH} is the architecture of
     your machine, e.g. i386.

           $ cd /sys/arch/${ARCH}/conf

     Edit the kernel configuration file.  ${NAME} is your kernel configuration
     file.  You should not edit GENERIC; create your own kernel configuration
     if you need to make modifications.  If using GENERIC you can skip this
     step.  And yes, you may use vi(1), mg(1), or any other editor you choose.

           $ vi ${NAME}

     Build the kernel compilation directory and compile the kernel:

           $ config ${NAME}
           $ cd ../compile/${NAME}
           $ make clean && make depend && make

     (In this instance make clean is your friend.)

     Replace the old kernel and reboot.  The current kernel is copied to /obsd
     and the new kernel to /bsd.

           $ su
           # make install
           # shutdown -r now

     If the system does not come up you can boot using /obsd.

   3. Build a new system
     Now that you are running your new kernel you can build a new system.
     It's safer (but slower) to remove your object directories and re-create
     them before the build.  The steps are:

     Move all your existing object files out of the way and then remove them
     in the background:

           $ cd /usr/obj && mkdir -p .old && sudo mv * .old && \
                   sudo rm -rf .old &

     Re-build your obj directories:

           $ cd /usr/src && nice make obj

     Create directories that might be missing:

           $ cd /usr/src/etc && env DESTDIR=/ sudo make distrib-dirs

     Begin the build:

           $ cd /usr/src && nice make SUDO=sudo build

     Update /etc, /var, and /dev/MAKEDEV, either by hand or using sysmerge(8).

     At this point your system is up-to-date and running the code that you are
     going to make into a release.

   4. Make and validate the system release
     The system release consists of at least one generic kernel, some instal-
     lation media, the release `tarballs', installation instructions, and
     checksum files.

     The release process requires two work areas.  They are:

     DESTDIR      This is the name of a directory which will be the root of a
                  complete OpenBSD installation, thus it must be on a disk
                  partition large enough to store the entire operating system
                  (less the X Window System and any third party `packages').
                  The directory can be removed once the release is created.
                  In any case the release process ensures the directory is
                  empty before starting.

     RELEASEDIR   This is the name of a directory where the release output
                  files are stored.  The following process will create the di-
                  rectory if necessary.

                  Warning: DESTDIR and RELEASEDIR must not refer to any direc-
                  tory with /mnt in its path, as /mnt is used in the release
                  generation process.  Additionally the first svnd(4) device,
                  svnd0, is also used and must not be configured.

     The release process is:

     Ensure ${DESTDIR} exists as an empty directory and ${RELEASEDIR} exists.
     ${RELEASEDIR} need not be empty.  You must be root to create a release:

           $ su
           # export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir
           # test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \
                   rm -rf ${DESTDIR}- &
           # mkdir -p ${DESTDIR} ${RELEASEDIR}

     Make the release and check that the contents of ${DESTDIR} pretty much
     match the contents of the release `tarballs':

           # cd /usr/src/etc && nice make release
           # cd /usr/src/distrib/sets && sh checkflist
           # unset RELEASEDIR DESTDIR

     At this point you have most of an OpenBSD release.  The only thing miss-
     ing is the X Window System (which is covered in the next section).

   5. Build and install xenocara
     Xenocara is based on the X.Org modular build system.  Xenocara sources
     are supposed to be in XSRCDIR which defaults to /usr/xenocara.  This
     variable should be set in mk.conf(5) if a non-default value is used.  The
     /usr/src tree is also needed while building xenocara.  The following
     steps will build and install everything for the first time.

           $ su
           # cd XSRCDIR
           # make bootstrap
           # make obj
           # make build

     The X Window System is created and installed in /usr/X11R6.

   6. Make and validate the xenocara release
     xenocara uses DESTDIR and 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 DESTDIR will be removed as part of the xenocara
     build (this is necessary for release checklist processing).

     The steps to build the release are (assuming you are still root, and
     still in XSRCDIR):

           # export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir
           # test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \
                   rm -rf ${DESTDIR}- &
           # mkdir -p ${DESTDIR} ${RELEASEDIR}
           # nice make release
           # unset RELEASEDIR DESTDIR

     At this point you have both OpenBSD system and X Window System `tarballs'
     in your release directory.

   7. Make the third party packages
     The `ports' subsystem of contributed applications is described in
     ports(7).  For ease of installation ports can be pre-compiled into
     `packages' which can then be installed on multiple machines using
     pkg_add(1).  Packages are created by selecting an application to build
     (we'll call this one CATEGORY/PORT) and then running the following: as
     root:

           $ cd /usr/ports/CATEGORY/PORT
           $ su
           # make package

     That's all there is to it.

SEE ALSO
     cvs(1), pkg_add(1), ports(7), sudo(8), sysmerge(8)

HISTORY
     This document first appeared in OpenBSD 2.8.

OpenBSD 4.7                     April 25, 2009                               4
