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

FreeBSD Manual Pages


home | help
RELEASE(7)	   FreeBSD Miscellaneous Information Manual	    RELEASE(7)

     release --	release	building infrastructure

     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 FreeBSD source code	repos-
     itory in src/release.  A complete release can actually be built with only
     a single command, including the creation of ISO images suitable for burn-
     ing to CD-ROM, memory stick images, and an	FTP install directory.	This
     command is	aptly named ``make 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/ 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 sys-
     tems from source.

     The release build process requires	that /usr/obj be populated with	the
     output of ``make buildworld'' and ``make buildkernel''.  This is neces-
     sary to provide the object	files for the release or, when using, so that the object files for a complete system can
     be	installed into a clean chroot(8) environment. In this second case, the
     built world must be capable of running on the build system	(i.e. it must
     be	for the	same architecture and be compatible with the installed ker-
     nel).  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.

     Official releases of FreeBSD are produced in a totally clean environment
     to	ensure consistency between the versions	of the src, ports, and doc
     trees and to avoid	contamination from the host system (e.g. local
     patches, changes to make.conf(5), etc.). This is accomplished using the
     wrapper script src/release/ svn-branch scratch-dir calls ``make installworld'' to	generate a chroot(8)
     environment in scratch-dir.  It then checks out the src tree specified by
     svn-branch	using svn(1) and (optionally) the ports	and documentation
     trees using csup(1) or cvs(1).  Once the various source trees have	been
     obtained, it executes ``make release'' within the chroot(8) environment
     and places	the result in $scratch-dir/R.  Note that because this uses a
     chroot, it	cannot be used to cross-build FreeBSD release media.

     Environment variables:

     CVSUP_HOST	 The CVSUP server to use for the doc and ports trees. One of
		 CVSUP_HOST or CVSROOT must be specified for ports and docu-
		 mentation to be included in the release.

     CVSROOT	 The location of the FreeBSD CVS repository to use for the doc
		 and ports trees. One of CVSUP_HOST or CVSROOT must be speci-
		 fied for ports	and documentation to be	included in the

     CVS_TAG	 If the	variable CVS_TAG is set, that tag will be used for CVS
		 checkouts (doc	and ports), otherwise will
		 use HEAD.

     MAKE_FLAGS	 This environment variable can be set to pass flags (e.g. -j)
		 to make(1) when invoked by the	script.

     SVNROOT	 The location of the FreeBSD SVN source	repository. Defaults
		 to svn://

     RELSTRING	 Optional base name for	generated media	images (e.g. Free-
		 BSD-9.0-RC2-amd64).  Defaults to the output of	`uname
		 -s`-`uname -r`-`uname -p` within the chroot.

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

     release	    Meta-target	to build all release media and distributions
		    applicable to this platform.

     install	    Copy all produced release media to ${DESTDIR}.

     cdrom	    Builds installation	CD-ROM images. On some systems,	this
		    may	require	that mkisofs(8)	be installed
		    (sysutils/cdrtools)	and possibly that the md(4) (memory
		    disk) device driver	be present in the kernel (either by
		    being compiled in or available as a	module). This target
		    produces files called release.iso and bootonly.iso as its

     memstick	    Builds an installation memory stick	image named memstick.
		    Not	applicable on all platforms. Requires that the md(4)
		    (memory disk) device driver	be present in the kernel
		    (either by being compiled in or available as a module).

     ftp	    Creates a directory	named ftp containing the distribution
		    files used in network installations	and suitable for
		    upload to an FTP mirror.

     Major subtargets called by	targets	above:

     packagesystem  Generates all the distribution archives (e.g. base,	ker-
		    nel, ports,	doc) applicable	on this	platform.

     system	    Builds a bootable installation system containing all the
		    distribution files packaged	by the packagesystem target,
		    and	suitable for imaging by	the cdrom and memstick tar-

     reldoc	    Builds the release documentation.  This includes the
		    release notes, hardware guide, and installation instruc-
		    tions. Other documentation (e.g.  the Handbook) is built
		    during the base.txz	target invoked by packagesystem.

     Optional variables:

     WORLDDIR	  Location of a	directory containing the src tree. By default,
		  the directory	above the one containing the makefile (src).

     PORTSDIR	  Location of a	directory containing the ports tree. By
		  default, /usr/ports.	If it is unset or cannot be found,
		  ports	will not be included in	the release.

     DOCDIR	  Location of a	directory containing the doc tree. By default,
		  /usr/doc.  If	it is unset or cannot be found,	most documen-
		  tation will not be included in the release; see NODOC	below.

     NOPORTS	  If defined, the Ports	Collection will	be omitted from	the

     NOSRC	  If set, do not include system	source code in the release.

     NODOC	  If defined, 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.

     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.  If not
		  set, TARGET defaults to the current hardware platform.

     TARGET_ARCH  The target machine processor architecture.  This is analo-
		  gous to the ``uname -p'' output.  Set	this to	cross-build
		  for a	different architecture.	 If not	set, TARGET_ARCH
		  defaults to the current machine architecture,	unless TARGET
		  is also set, in which	case it	defaults to the	appropriate
		  value	for that platform.  Typically, one only	needs to set


     The following sequence of commands	can be used to build a ``-CURRENT

	   cd /usr
	   svn co svn:// src
	   cd src
	   make	buildworld buildkernel
	   cd release
	   make	release
	   make	install	DESTDIR=/var/freebsd-snapshot

     After running these commands, all produced	distribution files (tarballs
     for FTP, CD-ROM images, etc.) are available in the	/var/freebsd-snapshot

     The following sequence of commands	can be used to build a ``-CURRENT
     snapshot''	in a clean environment,	including ports	and documentation:

	   cd /usr/src/release
	   sh head /local3/release

     After running these commands, all prepared	release	files are available in
     the /local3/release/R directory.

     cc(1), cvs(1), install(1),	make(1), svn(1)
     (ports/devel/subversion-freebsd), uname(1), md(4),	make.conf(5),
     build(7), ports(7), chroot(8), mtree(8), sysctl(8)

     FreeBSD Release Engineering,

     FreeBSD Release Engineering of Third Party	Packages,

     FreeBSD Developers' Handbook,

     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 file systems 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

     For the FreeBSD 9.0 release, src/release/Makefile was overhauled and the
     wrapper script src/release/ introduced to support the
     introduction of a new installer.

     At	near 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.

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

FreeBSD	9.1		       January 14, 2012			   FreeBSD 9.1


Want to link to this manual page? Use this URL:

home | help