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
     vn(4) (vnode 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 filesystem.	Checks out the specified
		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  dis-
		tributions,  build  the installation floppy disks, build release
		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" filesystem) from
		 the CD-ROM release area (disabled by default, see MAKE_ISOS be-
		 low).

     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:

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

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

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

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

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

     LOCAL_PATCHES     A patch file 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) 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.

     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.

     NOPORTS	       If set to "YES" then the Ports Collection will be omitted
		       from the release.

     NOPORTREADMES     If defined, readme files will not be created for each in-
		       dividual port in the Ports Collection.  The  default  be-
		       havior  is  for "make release" to run "make readmes" from
		       ${CHROOTDIR}/usr/ports, which can be a very time  consum-
		       ing operation.

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

     TARGET_ARCH       The target machine processor architecture.  This is anal-
		       ogous  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.

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),
     vn(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 filesystems 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 4.7			 March 12, 2002 		      RELEASE(7)

home | help