home | help
RELEASE(7)		 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  necessary
     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, includ-
     ing 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 systems
     from source with "make world".  The release  build  process  requires  that
     /usr/obj be populated with the output of "make buildworld".  This is neces-
     sary 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 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 de-
     velopers will only be concerned with the release target.

     release	Uses "make installworld" to install a clean system  into  a  ch-
		root(8)  environment  on the file system.  Checks out the speci-
		fied 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  re-
		lease documentation, and so on.

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

     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"  file  system)
		 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	Documen-
		 tation  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:

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

     CHROOTDIR	The  directory	to  be used as the chroot(8) environment for the
		entire release build.  This file system should have at least 2.3
		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 ch-
		root(8) directory tree.

     Optional variables:

     CVSCMDARGS 	Additional arguments for cvs(1) checkout and update com-
			mands.	 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, respec-
			tively.

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

     DOCRELEASETAG	The CVS tag to use when checking out  the  documentation
			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  de-
			fault instead.

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

     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 configurations  to
			compile  and install into the "base" distribution.  Each
			kernel is installed into /boot/<config> so that  it  can
			be booted from the loader via "boot <config>".

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

     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.

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

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

     NO_FLOPPIES	If defined, no floppy disk image files will be created.

     NOPORTS		If set to "YES" then the Ports Collection will be  omit-
			ted 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.

     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 associ-
			ated release version is used as the default instead.

     PREFETCHDISTFILES	If this variable is defined, then distfiles needed  dur-
			ing the release build will be downloaded prior to enter-
			ing  the  chroot(8) environment.  Note that this is done
			after any distfiles are obtained via RELEASEDISTFILES.

     RELEASEDISTFILES	The directory where the distribution files for ports re-
			quired by the release build can be found.  This may save
			a significant amount of time over downloading the  dist-
			files 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").

     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.

     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 instruct make(1) to
			execute up to four processes at a time.

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  re-
     lease:

	   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  snap-
     shot" 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),
     md(4),  drivers.conf(5),  make.conf(5),  build(7),   ports(7),   chroot(8),
     mtree(8)

     FreeBSD Release Engineering, http://www.FreeBSD.org/doc/en_US.ISO8859-1/ar-
     ticles/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  envi-
     ronment.

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

FreeBSD 5.0			 March 12, 2002 		      RELEASE(7)

home | help