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 reposito
ry 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 CDROM, 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. 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 nec
essary 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 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 ab
struse. Most
developers 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 executed to package; up the different distributions, build the installa; tion 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: manually modified, and performs the mini; mal 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 re; lease''. This is
most often used to build custom boot; floppies.
package-split Generates the portions of the disc 1 and
disc 2 images: related 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 directory 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 hierar; chy for the
system.
release.2 Installs the system into the distribu
tion directo: ries.
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: previously built distribution trees.
release.6 Creates tarballs of the assembled dis
tribution: 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 instal
lations 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: images.
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 re
lease 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 docu; ments 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 in; stallation
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) en
vironment 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:
CD_PACKAGE_TREE A directory containing extra bits
for the first: and second CD-ROM images. The ex; tra 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. Typi; cally, this
variable will be set to the output; directory of
an earlier 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, re; spectively.
DOC_LANG The list of languages and encod
ings 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 docu: mentation 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; cvs
update will be used instead.
EXTPORTSDIR The directory specified by this
variable will: be copied into; ${CHROOTDIR}/usr/ports. For
``rerelease'', this will do NOTH; ING.
KERNEL_FLAGS The contents of this variable are
passed to: make(1) when building kernels dur; ing the
release build. For example, set; ting 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 configu: rations to compile and install in; to the
``base'' distribution. Each ker; nel 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) environ; ment 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.
NOCDROM If defined, the CD-ROM stage di
rectories will: not be created.
NODOC If defined, the SGML-based docu
mentation from: the FreeBSD Documentation Project; will not be
built. However, the ``doc'' dis; tribution will
still be created 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 omit: ted 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 in; stead.
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 fetching is done; after any distfiles are obtained via; RELEASEDISTFILES.
RELEASEDISTFILES The directory where the distribu
tion files for: ports required by the release; build can be
found. This may save a signifi; cant 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'').
SEPARATE_LIVEFS Store the live file system on its
own CD-ROM: image rather than placing it on; the first disc.
TARGET_ARCH The target machine processor ar
chitecture.: This is analogous to the ``uname; -p'' output.
Set this to cross-build for a dif; ferent architecture.
TARGET The target hardware platform.
This is analo: gous to the ``uname -m'' output.; This is necessary to cross-build some target; architectures. For example, cross-build; ing for PC98
machines requires TARGET_ARCH=i386; and
TARGET=pc98.
WORLDDIR The directory where ``make build
world'' was: run; defaults 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 instruct 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 release:: cd /usr
cvs co -rRELENG_4_9_0_RELEASE src
cd src
make buildworld
cd release
make release CHROOTDIR=/local3/release BUILD; NAME=4.9-RELEASE CVSROOT=/host/cvs/usr/home/ncvs RE; LEASETAG=RELENG_4_9_0_RELEASE
After running these commands, a complete system suitable for
FTP or CDROM distribution is available in the /local3/release/R di
rectory.
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 BUILD; NAME=6.0-CURRENT CVSROOT=/host/cvs/usr/home/ncvs LO; CAL_PATCHES=/path/to/local.patch

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 demands on available file systems and was quite torturous to
execute.
As part of the FreeBSD 2.0 release engineering effort, sig
nificant 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.
With its almost 1000 revisions spread over multiple branch
es, 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 writ
ten 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
documentation from the last fully supported release of FreeBSD. For
example:: make release RELEASETAG=RELENG_4_9 DOCRELEASETAG=RE; LEASE_4_9_0 ...
BSD May 17, 2005

docs.sk

comprehensive documentation repository

See also