Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
RELEASE(7)         FreeBSD Miscellaneous Information Manual         RELEASE(7)

NAME
     release -- release building infrastructure

DESCRIPTION
     FreeBSD provides a complete build environment suitable for users to make
     full releases of the FreeBSD operating system.  All of the tools neces-
     sary to build a release are available from the CVS repository in
     src/release.  A complete release can actually be built with only a single
     command, including the creation of ISO images suitable for burning to CD-
     ROM, installation floppies, and an FTP install directory.  This command
     is aptly named ``make release''.

     Before attempting to build a release, the user is expected to be familiar
     with the contents of build(7), and should have experience upgrading sys-
     tems from source with ``make world''.  The release build process requires
     that /usr/obj be populated with the output of ``make buildworld''.  This
     is necessary so that the object files for a complete system can be
     installed into a clean chroot(8) environment.  The release procedure also
     requires that the vn(4) (vnode disk) device driver be present in the ker-
     nel (either by being compiled in or loaded as a module).

     This document does not cover source code management, quality assurance,
     or other aspects of the release engineering process.

TARGETS
     The release makefile (src/release/Makefile) is fairly abstruse.  Most
     developers will only be concerned with the release target.

     release    Uses ``make installworld'' to install a clean system into a
                chroot(8) environment on the filesystem.  Checks out the spec-
                ified version of the source code and then rebuilds the entire
                system in the clean environment with ``make world''.  The
                detailed steps that follow are then executed to package up the
                different distributions, build the installation floppy disks,
                build release documentation, and so on.

                This target must be built as root with the kern.securelevel
                sysctl set to -1 (the default).

     rerelease  Assumes that the output of a release build has been manually
                modified, and performs the minimal number of steps to rebuild
                the release using the intermediate output of the previous
                ``make release''.

     floppies   Generate a new set of boot floppies.  This will call the
                release.5, release.9, and release.10 targets to re-generate
                the floppy images of a previous ``make release''.  This is
                most often used to build custom boot floppies.

     Targets called by ``make release'':

     release.1   Cleans out the ${CHROOTDIR}/R directory and uses mtree(8) to
                 build the directory hierarchy for the system.

     release.2   Installs the system into the distribution directories.

     release.3   Builds and installs ``crypto'', ``krb4'' and ``krb5'' distri-
                 butions.

     release.4   Makes and installs the GENERIC kernel.

     release.5   Uses crunchgen(1) to build ``crunched'' binaries to live on
                 the installation floppies.

     release.6   Builds synthetic distributions, and cleans up the previously
                 built distribution trees.

     release.7   Creates tarballs of the assembled distribution trees.

     release.8   Makes source distributions.

     release.9   Creates the boot and MFS root floppies.

     release.10  Creates the fixit floppy.

     ftp.1       Sets up a suitable area for FTP installations in
                 ${CHROOTDIR}/R/ftp.

     cdrom.1     Sets up a suitable area to build CD-ROM images in
                 ${CHROOTDIR}/R/cdrom.

     iso.1       Builds two ISO images (installation and ``live'' filesystem)
                 from the CD-ROM release area (disabled by default, see
                 MAKE_ISOS below).

     doc.1       Builds all of the necessary tools to turn the FreeBSD Docu-
                 mentation Project source documents (SGML, XML) into HTML and
                 text documents that will accompany the release.  Also, builds
                 and installs the actual user documentation.  This includes
                 the Handbook, FAQ, articles, and so on.

     doc.2       Builds the release documentation.  This includes the release
                 notes, hardware guide, and installation instructions.

ENVIRONMENT
     Variables that must be specified:

     CHROOTDIR   The directory to be used as the chroot(8) environment for the
                 entire release build.  This filesystem should have at least
                 2.3 gigabytes of free space on the i386 architecture.

     BUILDNAME   The name of the release to be built.  This is used to set the
                 RELEASE value in sys/conf/newvers.sh, which affects the out-
                 put of uname(1).

     CVSROOT     The location of the FreeBSD CVS repository.  This path name
                 is referenced to the real system root, not the root of the
                 chroot(8) directory tree.

     RELEASETAG  The CVS tag corresponding to the release that is to be built.
                 If undefined, the release will be built from the HEAD of the
                 CVS tree (a ``-CURRENT snapshot'').

     Optional variables:

     CVSCMDARGS        Additional arguments for cvs(1) checkout and update
                       commands.  For example, setting this variable to ``-D
                       '01/01/2002 00:00:00 GMT''' for ``make release'' or
                       ``make rerelease'' will ask cvs(1) to check out or
                       update sources as of 00:00:00 GMT, January 1 2002,
                       respectively.

     LOCAL_PATCHES     A patch file against /usr/src that will be applied in
                       the chroot(8) environment before the release build
                       begins.

     PATCH_FLAGS       Arguments for the patch(1) command used to apply
                       LOCAL_PATCHES patch file.

     LOCAL_SCRIPT      A script that will be run in the chroot(8) environment
                       immediately after any local patches are applied.

     MAKE_ISOS         If defined, bootable ISO CD-ROM images will be created
                       from the contents of the CD-ROM stage directory.

     DISC1_LABEL       The label used for the CD-ROM created from the disc1
                       contents, the default label will be ``fbsd_miniinst''.

     DISC1_NAME        The name used as part of the ISO file name for the CD-
                       ROM created from the disc1 contents, the default will
                       be ``miniinst''.

     DISC2_LABEL       The label used for the CD-ROM created from the disc2
                       contents, the default label will be ``fbsd_livefs''.

     DISC2_NAME        The name used as part of the ISO file name for the CD-
                       ROM created from the disc2 contents, the default will
                       be ``disc2''.

     NODOC             If set to ``YES'', the SGML-based documentation from
                       the FreeBSD Documentation Project will not be built.
                       However, the ``doc'' distribution will still be created
                       with the minimal documentation set provided in
                       src/share/doc.

     NOPORTS           If set to ``YES'' then the Ports Collection will be
                       omitted from the release.

     NOPORTREADMES     If defined, readme files will not be created for each
                       individual port in the Ports Collection.  The default
                       behavior is for ``make release'' to run ``make
                       readmes'' from ${CHROOTDIR}/usr/ports, which can be a
                       very time consuming operation.

     RELEASEDISTFILES  The directory where the distribution files for ports
                       required by the release build can be found.  This may
                       save a significant amount of time over downloading the
                       distfiles through a slow link.

     RELEASENOUPDATE   If this variable is defined for ``make rerelease'', the
                       source code will not be updated with ``cvs update''.

     TARGET_ARCH       The target machine processor architecture.  This is
                       analogous to the ``uname -p'' output.  Set this to
                       cross-build for a different architecture.

     TARGET            The target hardware platform.  This is analogous to the
                       ``uname -m'' output.  This is necessary to cross-build
                       some target architectures.  For example, cross-building
                       for PC98 machines requires TARGET_ARCH=i386 and
                       TARGET=pc98.

FILES
     /etc/make.conf
     /usr/doc/Makefile
     /usr/doc/share/mk/doc.project.mk
     /usr/ports/Mk/bsd.port.mk
     /usr/ports/Mk/bsd.sites.mk
     /usr/share/examples/etc/make.conf
     /usr/src/Makefile
     /usr/src/Makefile.inc1
     /usr/src/release/Makefile
     /usr/src/release/${arch}/drivers.conf
     /usr/src/release/${arch}/boot_crunch.conf
     /usr/src/release/${arch}/fixit_crunch.conf

EXAMPLES
     The following sequence of commands was used to build the FreeBSD 4.5
     release:

           cd /usr
           cvs co -rRELENG_4_5_0_RELEASE src
           cd src
           make buildworld
           cd release
           make release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \
             CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_5_0_RELEASE

     After running these commands, a complete system suitable for FTP or CD-
     ROM distribution is available in the /local3/release/R directory.

     The following sequence of commands can be used to build a ``-CURRENT
     snapshot'' of a locally modified source tree:

           cd /usr/src
           cvs diff -u > /path/to/local.patch
           make buildworld
           cd release
           make release CHROOTDIR=/local3/release BUILDNAME=5.0-CURRENT \
             CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch

SEE ALSO
     cc(1), crunchgen(1), cvs(1), install(1), make(1), patch(1), uname(1),
     vn(4), drivers.conf(5), make.conf(5), build(7), ports(7), chroot(8),
     mtree(8), sysctl(8)

     FreeBSD Release Engineering,
     http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/.

     FreeBSD Release Engineering of Third Party Packages,
     http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/.

     FreeBSD Developers' Handbook,
     http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/.

HISTORY
     FreeBSD 1.x used a manual checklist, compiled by Rod Grimes, to produce a
     release.  Apart from being incomplete, the list put a lot of specific
     demands on available filesystems and was quite torturous to execute.

     As part of the FreeBSD 2.0 release engineering effort, significant effort
     was spent getting src/release/Makefile into a shape where it could at
     least automate most of the tediousness of building a release in a sterile
     environment.

     With its almost 1000 revisions spread over multiple branches, the cvs(1)
     log of src/release/Makefile contains a vivid historical record of some of
     the hardships release engineers go through.

AUTHORS
     src/release/Makefile was originally written by Rod Grimes, Jordan
     Hubbard, and Poul-Henning Kamp.  This manual page was written by Murray
     Stokely <murray@FreeBSD.org>.

BUGS
     Infrastructure changes are occassionally made to the FreeBSD documenta-
     tion set in such a way that release builds on security branches can fail.
     To work around this, release builds can be made to checkout the documen-
     tation from the last fully supported release of FreeBSD.  For example:

           make release RELEASETAG=RELENG_4_5 DOCRELEASETAG=RELEASE_4_5_0 ...

FreeBSD 4.10                    March 12, 2002                    FreeBSD 4.10

NAME | DESCRIPTION | TARGETS | ENVIRONMENT | FILES | EXAMPLES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=release&sektion=7&manpath=FreeBSD+4.10-RELEASE>

home | help