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

FreeBSD Manual Pages

  
 
  

home | help
RELEASE(7)	     BSD 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 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/generate-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 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 necessary to
     provide the object	files for the release or, when using
     generate-release.sh, 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.

CLEAN RELEASE GENERATION
     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/generate-release.sh.

     generate-release.sh svn-branch scratch-dir

     generate-release.sh calls "make installworld" to generate a chroot(8) en-
     vironment in scratch-dir.	It then	checks out the src tree	specified by
     svn-branch	using svn(1).  Once the	various	source trees have been ob-
     tained, it	executes "make release"	within the chroot(8) environment and
     places the	result in $scratch-dir/R.  Note	that because this uses a ch-
     root, it cannot be	used to	cross-build FreeBSD release media.

     Environment variables:

     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, doc, and ports	repos-
		 itories.  Defaults to svn://svn.freebsd.org/base for the
		 source	tree, svn://svn.freebsd.org/ports/head for the Ports
		 Collection, and svn://svn.freebsd.org/doc/head	for the	Docu-
		 mentation Project source.

     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.

MAKEFILE TARGETS
     The release makefile (src/release/Makefile) is fairly abstruse.  Most de-
     velopers 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
		    output.

     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 (ei-
		    ther 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 up-
		    load 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-
		    gets.

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

ENVIRONMENT
     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	de-
		  fault, /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
		  release.

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

     NODOC	  If defined, the XML-based documentation from the FreeBSD
		  Documentation	Project	will not be built.  However, the "doc"
		  distribution will still be created with the minimal documen-
		  tation 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 TARGET.

FILES
     /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/generate-release.sh

EXAMPLES
     The following sequence of commands	can be used to build a "-CURRENT
     snapshot":

	   cd /usr
	   svn co svn://svn.freebsd.org/base/head 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
     directory.

     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
	   export SVNROOT=svn://svn.freebsd.org/base
	   sh generate-release.sh head /local3/release

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

SEE ALSO
     cc(1), install(1),	make(1), svn(1)	(ports/devel/subversion), uname(1),
     md(4), 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 de-
     mands 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
     environment.

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

     At	near 1000 revisions spread over	multiple branches, the svn(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>.

BSD			       January 31, 2013				   BSD

NAME | DESCRIPTION | CLEAN RELEASE GENERATION | MAKEFILE TARGETS | ENVIRONMENT | FILES | EXAMPLES | SEE ALSO | HISTORY | AUTHORS

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

home | help