394 lines
12 KiB
Groff
394 lines
12 KiB
Groff
.\" 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 January 14, 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
|
|
and (optionally) the ports and documentation trees using
|
|
.Xr csup 1
|
|
or
|
|
.Xr cvs 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 CVSUP_HOST
|
|
The CVSUP server to use for the doc and ports trees. One of
|
|
.Ev CVSUP_HOST
|
|
or
|
|
.Ev CVSROOT
|
|
must be specified for ports and documentation to be included in the release.
|
|
.It Ev CVSROOT
|
|
The location of the
|
|
.Fx
|
|
CVS repository to use for the doc and ports trees. One of
|
|
.Ev CVSUP_HOST
|
|
or
|
|
.Ev CVSROOT
|
|
must be specified for ports and documentation to be included in the release.
|
|
.It Ev CVS_TAG
|
|
If the variable
|
|
.Ev CVS_TAG
|
|
is set, that tag will be used for CVS checkouts (doc and ports), otherwise
|
|
.Ic generate-release.sh
|
|
will use HEAD.
|
|
.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 repository. Defaults to
|
|
.Pa svn://svn.freebsd.org/base .
|
|
.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 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 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
|
|
.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 CVSUP_HOST=cvsupN.freebsd.org
|
|
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 cvs 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 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 .
|