Manual Pages  — RELEASE

For some users, it may be desirable to provide an absolutely clean build environment, with no local modifications to the source tree or to make.conf(5), and with clean checkouts of specific versions of the doc, src, and ports trees. For this purpose, a script ( src/release/release.sh) is provided to automate these checkouts and then execute "make release" in a clean chroot(8).

Before attempting to build a release, the user is expected to be familiar with the contents of build(7), and should have experience upgrading systems from source.

The release build process requires that /usr/obj be populated with the output of "make buildworld" and "make buildkernel". This is necessary to provide the object files for the release or, when using release.sh, so that the object files for a complete system can be installed into a clean chroot(8) environment.

If the target release build is for a different architecture or machine type, the TARGET and TARGET_ARCH variables must be used. See the supported release.conf variables for more information.

The release procedure on some architectures may also require that the md(4) (memory disk) device driver be present in the kernel (either by being compiled in or available as a module).

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

release.sh [-c release.conf]

release.sh checks out the src/, ports/, and doc/ trees to CHROOTDIR, then calls "make buildworld" and "make installworld" to generate a chroot(8) environment. Next, "make release" is run within the chroot(8) environment and places the result in $CHROOTDIR/R.

The optional release.conf configuration file supports the following variables:

CHROOTDIR
	The directory within which the release will be built.
CHROOT_MAKEENV
	Additional make(1) arguments to pass through, which directly affect the tuning of the build chroot.
SVNROOT
	The svn(1) host used to check out the various trees. Defaults to svn://svn.FreeeBSD.org.
SRCBRANCH
	The src/ branch to use. Defaults to head/@rHEAD.
DOCBRANCH
	The doc/ branch to use. Defaults to head/@rHEAD.
PORTBRANCH
	The ports/ branch to use. Defaults to head/@rHEAD.
TARGET
	The target machine type for cross-building a release.
TARGET_ARCH
	The target machine architecture for cross-building a release. For the supported list of TARGET and TARGET_ARCH combinations, consult the output of "make targets" as documented in build(7).
KERNEL
	The target kernel configuration to use. Defaults to GENERIC. Multiple KERNEL entries may be specified.
MAKE_CONF
	The make.conf(5) to use for the release build. Defaults to /dev/null to prevent polluting the release with local system changes.
SRC_CONF
	The src.conf(5) to use for the release build. Defaults to /dev/null to prevent polluting the release with local system changes.
MAKE_FLAGS
	Additional flags to pass to make(1).
WORLD_FLAGS
	Additional flags to pass to make(1) during the "buildworld" phase. Defaults to setting the number of make(1) jobs (-j) to the number of CPUs available on a SMP-capable system.
KERNEL_FLAGS
	Additional flags to pass to make(1) during the "buildkernel" phase. Defaults to setting the number of make(1) jobs (-j) to half the number of CPUs available on a SMP-capable system.
NODOC
	Set to a non-empty value to skip the doc/ tree checkout. When set, NODOC will prevent the doc.txz distribution package from being created.
NOPORTS
	Set to a non-empty value to skip the ports/ tree checkout. When set, NOPORTS will prevent the ports.txz distribution package from being created. Setting this also sets NODOC.
WITH_DVD
	Set to a non-empty value to include the dvdrom target.
WITH_COMPRESSED_IMAGES
	Set to a non-empty value to compress the release images with xz(1). The original (uncompressed) images are not removed.
XZ_THREADS (int)
	Set to the number of threads xz(1) should use when compressing images. By default, XZ_THREADS is set to 0, which uses all available cores on the system.
VCSCMD
	The command run to obtain the source trees. Defaults to " svn checkout".
CHROOTBUILD_SKIP
	If defined, the buildworld, installworld, and distribution stages of the chroot(8) build environment setup are skipped. This is intended solely for cases where the chroot(8) userland are provided by alternate means.
SRC_UPDATE_SKIP
	Set to a non-empty value to prevent checkout or update of /usr/src within the chroot(8). This is intended for use only when /usr/src is expected to exist by alternative means.
DOC_UPDATE_SKIP
	Set to a non-empty value to prevent checkout or update of /usr/doc within the chroot(8). This is intended for use only when /usr/doc is expected to exist by alternative means.
PORTS_UPDATE_SKIP
	Set to a non-empty value to prevent checkout or update of /usr/ports within the chroot(8). This is intended for use only when /usr/ports is expected to exist by alternative means.

The following make(1) environment variables are supported:

CLOUDWARE
	Set to a list of one or more cloud hosting providers, enclosed in quotes. Requires WITH_CLOUDWARE to also be set.
WITH_CLOUDWARE
	Set to a non-empty value to enable building virtual machine images for various cloud hosting providers. Requires CLOUDWARE to also be set.

Additionally, the CLOUDWARE and WITH_CLOUDWARE variables can be added to release.conf, and used in conjunction with release.sh.

For a list of supported CLOUDWARE values, run:

cd /usr/src
make -C release list-cloudware

cd /usr
svn co svn://svn.freebsd.org/base/head src
cd src
make buildworld buildkernel
cd release
make obj
make release
make install DESTDIR=/var/freebsd-snapshot

cd /usr/src/release
sh release.sh

cd /usr/src/release
sh release.sh -c $HOME/release.conf

Configuration files specific to various supported embedded systems, such as the Raspberry Pi, exist in the directory corresponding to the TARGET make(1) variable. For example, to build an image for the Raspberry Pi:

cd /usr/src/release
sh release.sh -c arm/RPI-B.conf

To build an image for the Raspberry Pi 3:

cd /usr/src/release
sh release.sh -c arm64/RPI3.conf

After running these commands, all prepared release files are available in the /scratch directory. The target directory can be changed by specifying the CHROOTDIR variable in release.conf.

FreeBSD Release Engineering,

FreeBSD Developers' Handbook,