freebsd-nq/share/man/man7/release.7

.\" Copyright (c) 2002 Murray Stokely <murray@FreeBSD.org>
.\" 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 March 12, 2002
.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
CVS 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,
installation floppies, and an FTP install directory.
This command is aptly named
.Dq Li "make release" .
.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 with
.Dq Li "make world" .
The release build process requires that
.Pa /usr/obj
be populated with the output of
.Dq Li "make buildworld" .
This is necessary so that the object files for a complete system can
be installed into a clean
.Xr chroot 8
environment.
The release procedure also requires that the
.Xr md 4
(memory disk) device driver be present in the kernel
(either by being compiled in or loaded as a module).
.Pp
This document does not cover source code management, quality
assurance, or other aspects of the release engineering process.
.Sh TARGETS
The release makefile
.Pq Pa src/release/Makefile
is fairly abstruse.
Most developers will only be concerned with the
.Cm release
target.
.\" XXX: Some sort of introduction to this list?  All the others have one.
.Bl -tag -width ".Cm rerelease"
.It Cm release
Uses
.Dq Li "make installworld"
to install a clean system into a
.Xr chroot 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
.Dq Li "make world" .
The detailed steps that follow are then executed to package up the
different distributions, build the installation floppy disks, build
release documentation, and so on.
.It Cm 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
.Dq Li "make release" .
.It Cm floppies
Generate a new set of boot floppies.
This will call the
.Cm release.5 ,
.Cm release.9 ,
and
.Cm release.10
targets to re-generate the floppy images of a previous
.Dq Li "make release" .
This is most often used to build custom boot floppies.
.El
.Pp
Targets called by
.Dq Li "make release" :
.Bl -tag -width ".Cm release.10"
.It Cm release.1
Cleans out the
.Pa ${CHROOTDIR}/R
directory and uses
.Xr mtree 8
to build the directory hierarchy for the system.
.It Cm release.2
Installs the system into the distribution directories.
.It Cm release.3
Builds and installs
.Dq crypto ,
.Dq krb4
and
.Dq krb5
distributions.
.It Cm release.4
.\" XXX: We build more than one kernel.  We build a stripped down
.\" kernel for the boot media in addition to a full GENERIC kernel.
Makes and installs the
.Pa GENERIC
kernel.
.It Cm release.5
Uses
.Xr crunchgen 1
to build
.Dq crunched
binaries to live on the installation floppies.
.It Cm release.6
Builds synthetic distributions, and cleans up the previously built
distribution trees.
.It Cm release.7
Creates tarballs of the assembled distribution trees.
.It Cm release.8
Makes source distributions.
.It Cm release.9
Creates the boot and MFS root floppies.
.It Cm release.10
Creates the fixit floppy.
.It Cm ftp.1
Sets up a suitable area for FTP installations in
.Pa ${CHROOTDIR}/R/ftp .
.It Cm cdrom.1
Sets up a suitable area to build CD-ROM images in
.Pa ${CHROOTDIR}/R/cdrom .
.It Cm iso.1
Builds two ISO images (installation and
.Dq live
filesystem) from the CD-ROM release area
(disabled by default, see
.Va MAKE_ISOS
below).
.It Cm doc.1
Builds all of the necessary tools to turn the
.Fx
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.
.It Cm doc.2
Builds the release documentation.
This includes the release notes,
hardware guide, and installation instructions.
.El
.Sh ENVIRONMENT
Variables that must be specified:
.Bl -tag -width ".Va BUILDNAME"
.It Va BUILDNAME
The name of the release to be built.
This is used to set the
.Va RELEASE
value in
.Pa sys/conf/newvers.sh ,
which affects the output of
.Xr uname 1 .
.It Va CHROOTDIR
The directory to be used as the
.Xr chroot 8
environment for the entire release build.
.\" XXX: I recommend against hardcoding specific numbers like "2.3" here;
.\" XXX: perhaps it should be replaced with something to the effect of
.\" XXX: "we don't know how much space you'll need, but make sure you have
.\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number,
.\" XXX: but at least it looks less like a decree and more like an estimate.
This filesystem should have at least 2.3 gigabytes of free space on the
i386 architecture.
.It Va CVSROOT
The location of the
.Fx
CVS repository.
This path name is in reference to the real system root,
.Em not
the root of the
.Xr chroot 8
directory tree.
.El
.Pp
Optional variables:
.Bl -tag -width ".Va PREFETCHDISTFILES"
.It Va CVSCMDARGS
Additional arguments for
.Xr cvs 1
.Ic checkout
and
.Ic update
commands.
For example, setting this variable to
.Dq Li "-D '01/01/2002 00:00:00 GMT'"
for
.Dq Li "make release"
or
.Dq Li "make rerelease"
will ask
.Xr cvs 1
to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively.
.It Va 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.
.It Va DOCRELEASETAG
The CVS tag to use when checking out the documentation tree.
Usually,
the head of the documentation tree is used by default.
If
.Va RELEASETAG
specifies a release tag,
then the associated release version is used as the default instead.
.It Va EXTLOCALDIR
The directory that will be copied to
.Pa ${CHROOTDIR}/usr/local .
.It Va KERNEL_FLAGS
The contents of this variable are passed to
.Xr make 1
when building kernels during the release build.
For example, setting this variable to
.Dq Li "-j 4"
will instruct
.Xr make 1
to execute up to four processes at a time.
.It Va KERNELS
Specifies a list of additional kernel configurations to compile and
install into the
.Dq base
distribution.
Each kernel is installed into
.Pa /boot/<config>
so that it can be booted from the loader via
.Dq Li "boot <config>" .
.It Va LOCAL_PATCHES
A patch file against
.Pa /usr/src
that will be applied in the
.Xr chroot 8
environment before the release build begins.
.It Va PATCH_FLAGS
Arguments for the
.Xr patch 1
command used to apply
.Va LOCAL_PATCHES
patch file.
.It Va LOCAL_SCRIPT
A script that will be run in the
.Xr chroot 8
environment immediately after any local patches are applied.
.It Va MAKE_ISOS
If defined, bootable ISO CD-ROM images will be created from the
contents of the CD-ROM stage directory.
.It Va NOCDROM
If defined, the CD-ROM stage directories will not be created.
.It Va NODOC
If set to
.Dq Li YES ,
the SGML-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 NO_FLOPPIES
If defined, no floppy disk image files will be created.
.It Va NOPORTS
If set to
.Dq Li YES
then the Ports Collection will be omitted from the release.
.It Va NOPORTREADMES
If defined, readme files will not be created for each individual port
in the Ports Collection.
The default behavior is for
.Dq Li "make release"
to run
.Dq Li "make readmes"
from
.Pa ${CHROOTDIR}/usr/ports ,
which can be a very time consuming operation.
.It Va PORTSRELEASETAG
The CVS tag to use when checking out the ports tree.
Usually,
the head of the ports tree is used by default.
If
.Va RELEASETAG
specifies a release tag,
then the associated release version is used as the default instead.
.It Va PREFETCHDISTFILES
If this variable is defined,
then distfiles needed during the release build will be downloaded prior to
entering the
.Xr chroot 8
environment.
Note that this is done after any distfiles are obtained via
.Va RELEASEDISTFILES .
.It Va 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.
.It Va RELEASENOUPDATE
If this variable is defined for
.Dq Li "make rerelease" ,
the source code will not be updated with
.Dq Li "cvs update" .
.It Va RELEASETAG
The CVS tag corresponding to the release that is to be built.
If undefined, the release will be built from the
.Dv HEAD
of the CVS tree
(a
.Dq "-CURRENT snapshot" ) .
.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.
.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 .
.It Va WORLD_FLAGS
The contents of this variable are passed to
.Xr make 1
when building world during the release build.
For example, setting this variable to
.Dq Li "-j 4"
will instruct
.Xr make 1
to execute up to four processes at a time.
.El
.Sh FILES
.Bl -tag -compact
.It Pa /etc/make.conf
.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/${arch}/drivers.conf
.It Pa /usr/src/release/${arch}/boot_crunch.conf
.It Pa /usr/src/release/${arch}/fixit_crunch.conf
.El
.Sh EXAMPLES
The following sequence of commands was used to build the
.Fx 4.5
release:
.Bd -literal -offset indent
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
.Ed
.Pp
After running these commands, a complete system suitable for FTP or
CD-ROM distribution is available in the
.Pa /local3/release/R
directory.
.Pp
The following sequence of commands can be used to build a
.Dq "-CURRENT snapshot"
of a
locally modified source tree:
.Bd -literal -offset indent
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
.Ed
.Sh SEE ALSO
.Xr cc 1 ,
.Xr crunchgen 1 ,
.Xr cvs 1 ,
.Xr install 1 ,
.Xr make 1 ,
.Xr patch 1 ,
.Xr uname 1 ,
.Xr md 4 ,
.Xr drivers.conf 5 ,
.Xr make.conf 5 ,
.Xr build 7 ,
.Xr ports 7 ,
.Xr chroot 8 ,
.Xr mtree 8
.Rs
.%T "FreeBSD Release Engineering"
.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
.Re
.Rs
.%T "FreeBSD Release Engineering of Third Party Packages"
.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
.Re
.Rs
.%T "FreeBSD Developers' Handbook"
.%O 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 filesystems 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
With its almost 1000 revisions spread over multiple branches, the
.Xr cvs 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 .