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 XF4.
     6.   Make and validate the XF4 release.
     7.   Make the third party packages.

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

   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:

           o   cd /usr/src && cvs up -r TAG -Pd
           o   cd XF4SRC && cvs up -r TAG -Pd
           o   cd PORTSPATH && cvs up -r TAG -Pd

     Replace XF4SRC with the path to your X11R6 sources.  Replace PORTSPATH
     with the path to your ports tree sources, typically /usr/ports. The above
     command 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:

           o   cd /sys/arch/${ARCH}/conf
               where ${ARCH} is the architecture of your machine, e.g., i386.
           o   vi ${NAME}
               where ${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 emacs or any other editor you
               choose.
           o   config ${NAME}
           o   cd ../compile/${NAME}
           o   make clean && make depend && make
               In this instance make clean is your friend.
           o   su
           o   mv /bsd /bsd.old && mv bsd / && chown root.wheel /bsd
           o   shutdown -r now

     If the system does not come up you can boot using bsd.old.

   3. Build a new system

     Now that you are running using your new kernel you can build a new sys-
     tem.  It's safer (but slower) to remove and re-build your object directo-
     ries and re-building them before the build.  The steps are:

           o   cd /usr/obj && mkdir -p .old && sudo mv * .old && sudo rm -rf
               .old &
               This moves all your existing object out of the way and then re-
               moves them in the background.
           o   cd /usr/src && nice make obj
               this re-builds your obj directories
           o   su
           o   nice make build
               If you have set sudo(8) up, you can combine this with the pre-
               vious step using the command
                     nice make SUDO=sudo build
           o   Update /etc, /var, and /dev/MAKEDEV by hand.

     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 a generic kernel, one CD-ROM and two flop-
     py boot-able file-systems, the release `tarballs', installation instruc-
     tions, 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
                  a complete OpenBSD installation, thus it must be on a disk
                  partition large enough to store the entire operating system
                  (less X11R6 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 start-
                  ing.

     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.

     The floppy and CD-ROM RAMDISK images require a special tool which is cre-
     ated first.  The release process is:

           o   su
               you must be root to create a release
           o   cd /usr/src/distrib/crunch && make clean && make && make
               install

               create the special tools needed to build the release
           o   export DESTDIR=your-destdir RELEASEDIR=your-releasedir
           o   test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && rm -rf
               ${DESTDIR}- &
           o   mkdir -p ${DESTDIR} ${RELEASEDIR}
               these two steps ensure ${DESTDIR} exists as an empty directory
               and ${RELEASEDIR} exists.  ${RELEASEDIR} need not be empty.
           o   cd /usr/src/etc && nice make release
           o   cd /usr/src/distrib/sets && csh checkflist
               this checks that the contents of ${DESTDIR} pretty much match
               the contents of the release `tarballs'.
           o   unset RELEASEDIR DESTDIR

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

   5. Build and install XF4

     The XF4 tree is primarily imake(1)-based and doesn't contain the ``obj''
     directory mechanism that comes with Berkeley make(1). While the tree can
     be built in place, it's better to refrain from polluting the cvs sources.
     An alternate build location needs to be selected, large enough to hold
     the X11R6 object files, libraries, and binaries.  Call this location
     XF4BLD. XF4SRC is the path to your X11R6 sources.  Once you've selected
     XF4BLD the build process is:

           o   su
           o   test -d XF4BLD && mv XF4BLD XF4BLD- && rm -rf XF4BLD- &
           o   mkdir -p XF4BLD
           o   cd XF4BLD && lndir XF4SRC && nice make build

     Note (only for i386): XF86Setup, built and installed above, requires ver-
     sion 8.3 of the tcl/tk libraries.   They must be installed to do a proper
     build. Version 8.3 of tcl/tk can be found in the ports tree at
     /usr/ports/lang/tcl/8.3/ and /usr/ports/x11/tk/8.3/. Version 8.3 is re-
     quired to build XF4.  Version 8.3 may coexist with version 8.0.

     The above method mimics a make build in the /usr/src directory.  X11R6 is
     created and installed in ~ /usr/X11R6 .  However, the install phase of
     the build does not overwrite /etc/X11/xdm. That directory must be in-
     stalled by hand.   Or you can cd /etc/X11 && mv xdm xdm- before the build
     and copy any local configuration from xdm- to xdm after the build.

   6. Make and validate the XF4 release

     X11R6 uses the same DESTDIR and RELEASEDIR mechanism noted in the section
     on building a system release, above.  They may be the same values used
     above, but be warned that the contents of DESTDIR will be removed if you
     follow this procedure.   However, DESTDIR should not be the same directo-
     ry used to build the system release.  It may be the same if you don't
     care to keep the contents of the system release DESTDIR. (The XF4 DESTDIR
     needs to be emptied for release checklist processing.)

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

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

     At this point you have both system and X11R6 `tarballs' in your release
     directory.
   7. Make the third party packages

     The `ports' sub-system of contributed applications is described in
     ports(7). For ease of installation ports can be pre-compiled into
     `packages' which can then be installed onto machines using pkg_add(1).
     Packages are created by:

           o   Select an application to build, we'll call it CATEGORY/PORT.
           o   cd /usr/ports/CATEGORY/PORT
           o   su
           o   make package

     That's all there is to it.

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

HISTORY
     This document first appeared in OpenBSD 2.8.

OpenBSD 2.9                      July 6, 2000                                4
