.\" Copyright (c) 2002 Murray Stokely .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 16, 2012 .Dt RELEASE 7 .Os .Sh NAME .Nm release .Nd "release building infrastructure" .Sh DESCRIPTION .Fx provides a complete build environment suitable for users to make full releases of the .Fx operating system. All of the tools necessary to build a release are available from the .Fx source code repository in .Pa 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, memory stick images, and an FTP install directory. This command is aptly named .Dq Li "make release" . .Pp For some users, it may be desirable to provide an absolutely clean build environment, with no local modifications to the source tree or to .Xr make.conf 5 , and with clean checkouts of specific versions of the doc, src, and ports trees. For this purpose, a script .Pq Pa src/release/generate-release.sh is provided to automate these checkouts and then execute .Dq Li "make release" in a clean .Xr chroot 8 . .Pp Before attempting to build a release, the user is expected to be familiar with the contents of .Xr build 7 , and should have experience upgrading systems from source. .Pp The release build process requires that .Pa /usr/obj be populated with the output of .Dq Li "make buildworld" and .Dq Li "make buildkernel" . This is necessary to provide the object files for the release or, when using .Pa generate-release.sh , so that the object files for a complete system can be installed into a clean .Xr 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 kernel). The release procedure on some architectures may also require that the .Xr md 4 (memory disk) device driver be present in the kernel (either by being compiled in or available as a module). .Pp This document does not cover source code management, quality assurance, or other aspects of the release engineering process. .Sh 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 .Xr make.conf 5 , etc.). This is accomplished using the wrapper script .Pa src/release/generate-release.sh . .Pp .Ic generate-release.sh svn-branch scratch-dir .Pp .Ic generate-release.sh calls .Dq Li "make installworld" to generate a .Xr chroot 8 environment in .Ar scratch-dir . It then checks out the src tree specified by .Ar svn-branch using .Xr svn 1 . Once the various source trees have been obtained, it executes .Dq Li "make release" within the .Xr chroot 8 environment and places the result in .Pa $scratch-dir/R . Note that because this uses a chroot, it cannot be used to cross-build .Fx release media. .Pp Environment variables: .Bl -tag -width ".Cm MAKE_FLAGS" .It Ev MAKE_FLAGS This environment variable can be set to pass flags (e.g. -j) to .Xr make 1 when invoked by the script. .It Ev SVNROOT The location of the FreeBSD SVN source, doc, and ports repositories. Defaults to .Pa svn://svn.freebsd.org/base for the source tree, .Pa svn://svn.freebsd.org/ports/head for the Ports Collection, and .Pa svn://svn.freebsd.org/doc/head for the Documentation Project source. .It Ev RELSTRING Optional base name for generated media images (e.g. FreeBSD-9.0-RC2-amd64). Defaults to the output of .Ic `uname -s`-`uname -r`-`uname -p` within the chroot. .El .Sh MAKEFILE TARGETS The release makefile .Pq Pa src/release/Makefile is fairly abstruse. Most developers will only be concerned with the .Cm release and .Cm install targets. .\" XXX: Some sort of introduction to this list? All the others have one. .Bl -tag -width ".Cm packagesystem" .It Cm release Meta-target to build all release media and distributions applicable to this platform. .It Cm install Copy all produced release media to .Pa ${DESTDIR} . .It Cm cdrom Builds installation CD-ROM images. On some systems, this may require that .Xr mkisofs 8 be installed .Pq Pa sysutils/cdrtools and possibly that the .Xr 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 .Pa release.iso and .Pa bootonly.iso as its output. .It Cm memstick Builds an installation memory stick image named .Pa memstick . Not applicable on all platforms. Requires that the .Xr md 4 (memory disk) device driver be present in the kernel (either by being compiled in or available as a module). .It Cm ftp Creates a directory named .Pa ftp containing the distribution files used in network installations and suitable for upload to an FTP mirror. .El .Pp Major subtargets called by targets above: .Bl -tag -width ".Cm packagesystem" .It Cm packagesystem Generates all the distribution archives (e.g. base, kernel, ports, doc) applicable on this platform. .It Cm system Builds a bootable installation system containing all the distribution files packaged by the .Cm packagesystem target, and suitable for imaging by the .Cm cdrom and .Cm memstick targets. .It Cm reldoc Builds the release documentation. This includes the release notes, hardware guide, and installation instructions. Other documentation (e.g. the Handbook) is built during the .Cm base.txz target invoked by .Cm packagesystem . .El .Sh ENVIRONMENT Optional variables: .Bl -tag -width ".Va TARGET_ARCH" .It Va WORLDDIR Location of a directory containing the src tree. By default, the directory above the one containing the makefile .Pq Pa src . .It Va PORTSDIR Location of a directory containing the ports tree. By default, .Pa /usr/ports . If it is unset or cannot be found, ports will not be included in the release. .It Va DOCDIR Location of a directory containing the doc tree. By default, .Pa /usr/doc . If it is unset or cannot be found, most documentation will not be included in the release; see .Ev NODOC below. .It Va NOPORTS If defined, the Ports Collection will be omitted from the release. .It Va NOSRC If set, do not include system source code in the release. .It Va NODOC If defined, the XML-based documentation from the .Fx Documentation Project will not be built. However, the .Dq doc distribution will still be created with the minimal documentation set provided in .Pa src/share/doc . .It Va TARGET The target hardware platform. This is analogous to the .Dq Nm uname Fl m output. This is necessary to cross-build some target architectures. For example, cross-building for PC98 machines requires .Va TARGET_ARCH Ns = Ns Li i386 and .Va TARGET Ns = Ns Li pc98 . If not set, .Va TARGET defaults to the current hardware platform. .It Va TARGET_ARCH The target machine processor architecture. This is analogous to the .Dq Nm uname Fl p output. Set this to cross-build for a different architecture. If not set, .Va TARGET_ARCH defaults to the current machine architecture, unless .Va TARGET is also set, in which case it defaults to the appropriate value for that platform. Typically, one only needs to set .Va TARGET . .El .Sh FILES .Bl -tag -compact -width Pa .It Pa /usr/doc/Makefile .It Pa /usr/doc/share/mk/doc.project.mk .It Pa /usr/ports/Mk/bsd.port.mk .It Pa /usr/ports/Mk/bsd.sites.mk .It Pa /usr/share/examples/etc/make.conf .It Pa /usr/src/Makefile .It Pa /usr/src/Makefile.inc1 .It Pa /usr/src/release/Makefile .It Pa /usr/src/release/generate-release.sh .El .Sh EXAMPLES The following sequence of commands can be used to build a .Dq "-CURRENT snapshot": .Bd -literal -offset indent 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 .Ed .Pp After running these commands, all produced distribution files (tarballs for FTP, CD-ROM images, etc.) are available in the .Pa /var/freebsd-snapshot directory. .Pp The following sequence of commands can be used to build a .Dq "-CURRENT snapshot" in a clean environment, including ports and documentation: .Bd -literal -offset indent cd /usr/src/release export SVNROOT=svn://svn.freebsd.org/base sh generate-release.sh head /local3/release .Ed .Pp After running these commands, all prepared release files are available in the .Pa /local3/release/R directory. .Sh SEE ALSO .Xr cc 1 , .Xr install 1 , .Xr make 1 , .Xr svn 1 Pq Pa ports/devel/subversion-freebsd , .Xr uname 1 , .Xr md 4 , .Xr make.conf 5 , .Xr build 7 , .Xr ports 7 , .Xr chroot 8 , .Xr mtree 8 , .Xr sysctl 8 .Rs .%T "FreeBSD Release Engineering" .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ .Re .Rs .%T "FreeBSD Release Engineering of Third Party Packages" .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ .Re .Rs .%T "FreeBSD Developers' Handbook" .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ .Re .Sh HISTORY .Fx 1.x used a manual checklist, compiled by .An 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. .Pp As part of the .Fx 2.0 release engineering effort, significant effort was spent getting .Pa src/release/Makefile into a shape where it could at least automate most of the tediousness of building a release in a sterile environment. .Pp For the .Fx 9.0 release, .Pa src/release/Makefile was overhauled and the wrapper script .Pa src/release/generate-release.sh introduced to support the introduction of a new installer. .Pp At near 1000 revisions spread over multiple branches, the .Xr svn 1 log of .Pa src/release/Makefile contains a vivid historical record of some of the hardships release engineers go through. .Sh AUTHORS .Pa src/release/Makefile was originally written by .An -nosplit .An Rod Grimes , .An Jordan Hubbard , and .An Poul-Henning Kamp . This manual page was written by .An Murray Stokely Aq murray@FreeBSD.org .