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 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.	The release build process requires that	/usr/obj be
     populated with the	output of a native "make buildworld" compiled from
     sources matching the currently running kernel.  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
     md(4) (memory disk) device	driver be present in the kernel	(either	by be-
     ing 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.

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

     release	    Uses "make installworld" to	install	a clean	system into a
		    chroot(8) environment on the file system.  Checks out the
		    specified version of the source code and then rebuilds the
		    entire system in the clean environment with	"make
		    buildworld".  The detailed steps that follow are then exe-
		    cuted 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	manu-
		    ally 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 and fixit floppies.  This will
		    call the release.4,	release.8, floppies.1, floppies.2, and
		    floppies.3 targets to re-generate the floppy images	of a
		    previous "make release".  This is most often used to build
		    custom boot	floppies.

     package-split  Generates the portions of the disc 1 and disc 2 images re-
		    lated to packages.	It uses	the list of desired packages
		    from the src/release/scripts/package-split.py script to
		    pull packages out of a package build provided by the ports
		    team and organize them appropriately.  The resulting di-
		    rectory can	then be	passed to "make	release" via the
		    CD_PACKAGE_TREE variable to	populate the ISO images	built
		    by the iso.1 target	with the correct package related bits.

     Targets called by "make release":

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

     release.2	      Installs the system into the distribution	directories.

     release.3	      Makes and	installs the GENERIC kernel as well as any
		      other kernels listed in KERNELS.

     release.4	      Uses crunchgen(1)	to build "crunched" binaries to	live
		      on the installation floppies.

     release.5	      Builds synthetic distributions, and cleans up the	previ-
		      ously built distribution trees.

     release.6	      Creates tarballs of the assembled	distribution trees.

     release.7	      Makes source distributions.

     release.8	      Creates the MFS root file	systems.

     floppies.1	      Creates the boot and kernel floppies.

     floppies.2	      Creates the fixit	floppy.

     floppies.3	      Finalizes	the ${CHROOTDIR}/R/ftp/stage/floppies staging
		      directory.

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

     cdrom.1	      Create the layout	for the	live file system CD-ROM	image
		      in ${CHROOTDIR}/R/cdrom.

     cdrom.2	      Create the layout	for the	first and second CD-ROM	im-
		      ages.

     cdrom.3	      Create the layout	for the	boot-only CD-ROM image and the
		      boot-only	UFS miniroot image.

     iso.1	      Builds ISO images	(installation and "live" file system)
		      from the CD-ROM release area (disabled by	default, see
		      MAKE_ISOS	below).

     fetch-distfiles  Fetches distfiles	needed during the release build	that
		      are not already in RELEASEDISTFILES.

     doc.1	      Builds all of the	necessary tools	to turn	the FreeBSD
		      Documentation 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 re-
		      lease notes, hardware guide, and installation instruc-
		      tions.

ENVIRONMENT
     Variables that must be specified:

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

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

     Optional variables:

     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 output of uname(1).  If not set,
			   a name with the timestamp and the "-SNAP" suffix
			   will	be generated.

     CD_PACKAGE_TREE	   A directory containing extra	bits for the first and
			   second CD-ROM images.  The extra files for the
			   first disc should be	in ${CD_PACKAGE_TREE}/disc1
			   and the extra files for the second disc should be
			   in ${CD_PACKAGE_TREE}/disc2.	 Typically, this vari-
			   able	will be	set to the output directory of an ear-
			   lier	invocation of the package-split	target.

     CVSARGS		   Additional arguments	for cvs(1) that	come before
			   the subcommands such	as "-qR".

     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.

     DOC_LANG		   The list of languages and encodings the SGML-based
			   documentation should	be built for.  If not set, the
			   documentation is built for all available languages.

     DOCRELEASETAG	   The CVS tag to use when checking out	the documenta-
			   tion	tree.  Usually,	the head of the	documentation
			   tree	is used	by default.  If	RELEASETAG specifies a
			   release tag,	then the associated release version is
			   used	as the default instead.

     EXTLOCALDIR	   The directory that will be copied to
			   ${CHROOTDIR}/usr/local.

     EXTSRCDIR		   The directory specified by this variable will be
			   copied into ${CHROOTDIR}/usr/src instead of that
			   directory being populated by	a CVS checkout.	 For
			   "rerelease",	this will NOT be copied; cvs update
			   will	be used	instead.

     EXTDOCDIR		   The directory specified by this variable will be
			   copied into ${CHROOTDIR}/usr/doc.  For "rerelease",
			   this	will NOT be copied again.

     EXTPORTSDIR	   The directory specified by this variable will be
			   copied into ${CHROOTDIR}/usr/ports.	For
			   "rerelease",	this will do NOTHING.

     KERNEL_FLAGS	   The contents	of this	variable are passed to make(1)
			   when	building kernels during	the release build.
			   For example,	setting	this variable to "-j 4"	will
			   instruct make(1) to execute up to four processes at
			   a time.

     KERNELS		   Specifies a list of additional kernel configura-
			   tions to compile and	install	into the "base"	dis-
			   tribution.  Each kernel is installed	into
			   /boot/_config_ so that it can be booted from	the
			   loader via "boot <config>".

     LOCAL_PATCHES	   Patch files 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) environ-
			   ment	immediately after any local patches are	ap-
			   plied.

     MAKE_DVD		   If defined, build a bootable	ISO DVD	image in the
			   CD-ROM stage	directory.  This option	may not	be
			   available for all architectures.

     MAKE_ISOS		   If defined, bootable	ISO CD-ROM images will be cre-
			   ated	from the contents of the CD-ROM	stage direc-
			   tory.

     NOCDROM		   If defined, the CD-ROM stage	directories will not
			   be created.

     NODOC		   If defined, the SGML-based documentation from the
			   FreeBSD Documentation Project will not be built.
			   However, the	"doc" distribution will	still be cre-
			   ated	with the minimal documentation set provided in
			   src/share/doc.

     NO_FLOPPIES	   If defined, no boot and fixit floppy	disk images
			   will	be created (for	those platforms	supporting
			   them).

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

     PORTSRELEASETAG	   The CVS tag to use when checking out	the ports
			   tree.  Usually, the head of the ports tree is used
			   by default.	If RELEASETAG specifies	a release tag,
			   then	the associated release version is used as the
			   default instead.

     NO_PREFETCHDISTFILES  If this variable is defined,	then distfiles needed
			   during the release build will not be	downloaded
			   prior to entering the chroot(8) environment.	 Note
			   that	if NO_PREFETCHDISTFILES	is not set, the	fetch-
			   ing is done after any distfiles are obtained	via
			   RELEASEDISTFILES.

     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".

     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").

     SEPARATE_LIVEFS	   Store the live file system on its own CD-ROM	image
			   rather than placing it on the first disc.

     SVNCMDARGS		   Additional arguments	for svn	checkout and switch
			   commands.

     SVNROOT		   The location	of the FreeBSD SVN source repository.
			   If this variable is set, then the source tree will
			   be extracted	using Subversion rather	than CVS.

     SVNBRANCH		   The branch to check out from	a SVN source reposi-
			   tory.  It is	specified as a path such as head or
			   stable/7.  If this variable is not set, then	the
			   branch that corresponds to the current value	of
			   RELEASETAG will be used.  If	neither	SVNBRANCH nor
			   RELEASETAG are set, then the	head branch will be
			   used.

     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.

     WORLDDIR		   The directory where "make buildworld" was run; de-
			   faults to ${.CURDIR}/.. which usually points	to
			   /usr/src.

     WORLD_FLAGS	   The contents	of this	variable are passed to make(1)
			   when	building world during the release build.  For
			   example, setting this variable to "-j 4" will in-
			   struct make(1) to execute up	to four	processes at a
			   time.

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/${arch}/boot_crunch.conf
     /usr/src/release/${arch}/fixit_crunch.conf

EXAMPLES
     The following sequence of commands	was used to build the FreeBSD 4.9 re-
     lease:

	   cd /usr
	   cvs co -rRELENG_4_9_0_RELEASE src
	   cd src
	   make	buildworld
	   cd release
	   make	release	CHROOTDIR=/local3/release BUILDNAME=4.9-RELEASE	\
	     CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_9_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=6.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), 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.

     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.

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	occasionally made to the FreeBSD documentation
     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 documenta-
     tion from the last	fully supported	release	of FreeBSD.  For example:

	   make	release	RELEASETAG=RELENG_4_9 DOCRELEASETAG=RELEASE_4_9_0 ...

BSD			       January 31, 2013				   BSD

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

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

home | help