747a26f4af
MFC after: 3 days X-MFC-With: r258310 Sponsored by: The FreeBSD Foundation
551 lines
14 KiB
Groff
551 lines
14 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 November 18, 2013
|
|
.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/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 release.sh ,
|
|
so that the object files for a complete system can be installed into a clean
|
|
.Xr chroot 8
|
|
environment.
|
|
.Pp
|
|
If the target release build is for a different architecture or machine type,
|
|
the
|
|
.Va TARGET
|
|
and
|
|
.Va TARGET_ARCH
|
|
variables must be used.
|
|
See the supported
|
|
.Fa release.conf
|
|
variables for more information.
|
|
.Pp
|
|
The release procedure on some architectures may also require that the
|
|
.Xr md 4
|
|
(memory disk) device driver be present in the kernel
|
|
.Pq 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
|
|
.Fx
|
|
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
|
|
.Po such as local patches, changes
|
|
to
|
|
.Xr make.conf 5 ,
|
|
etc.
|
|
.Pc .
|
|
This is accomplished using the wrapper script
|
|
.Pa src/release/release.sh .
|
|
.Pp
|
|
.Ic release.sh
|
|
.Op Fl c Ar release.conf
|
|
.Pp
|
|
.Ic release.sh
|
|
checks out the
|
|
.Li src/ ,
|
|
.Li ports/ ,
|
|
and
|
|
.Li doc/
|
|
trees to
|
|
.Va CHROOTDIR ,
|
|
then calls
|
|
.Dq Li "make buildworld"
|
|
and
|
|
.Dq Li "make installworld"
|
|
to generate a
|
|
.Xr chroot 8
|
|
environment.
|
|
Next,
|
|
.Dq Li "make release"
|
|
is run within the
|
|
.Xr chroot 8
|
|
environment and places the result in
|
|
.Pa $CHROOTDIR/R .
|
|
.Pp
|
|
The optional
|
|
.Fa release.conf
|
|
configuration file supports the following variables:
|
|
.Bl -tag -width Ev
|
|
.It Va CHROOTDIR
|
|
The directory within which the release will be built.
|
|
.It Va SVNROOT
|
|
The
|
|
.Xr svn 1
|
|
host used to check out the various trees.
|
|
Defaults to
|
|
.Pa svn://svn.FreeeBSD.org .
|
|
.It Va SRCBRANCH
|
|
The
|
|
.Li src/
|
|
branch to use.
|
|
Defaults to
|
|
.Va head/@rHEAD .
|
|
.It Va DOCBRANCH
|
|
The
|
|
.Li doc/
|
|
branch to use.
|
|
Defaults to
|
|
.Va head/@rHEAD .
|
|
.It Va PORTBRANCH
|
|
The
|
|
.Li ports/
|
|
branch to use.
|
|
Defaults to
|
|
.Va head/@rHEAD .
|
|
.It Va TARGET
|
|
The target machine type for cross-building a release.
|
|
.It Va TARGET_ARCH
|
|
The target machine architecture for cross-building a release.
|
|
.Pp
|
|
For the supported list of
|
|
.Va TARGET
|
|
and
|
|
.Va TARGET_ARCH
|
|
combinations, consult the output of
|
|
.Dq make targets
|
|
as documented in
|
|
.Xr build 7 .
|
|
.It Va KERNEL
|
|
The target kernel configuration to use.
|
|
Defaults to
|
|
.Va GENERIC .
|
|
Multiple
|
|
.Va KERNEL
|
|
entries may be specified.
|
|
.It Va MAKE_CONF
|
|
The
|
|
.Xr make.conf 5
|
|
to use for the release build.
|
|
Defaults to
|
|
.Fa /dev/null
|
|
to prevent polluting the release with local system changes.
|
|
.It Va SRC_CONF
|
|
The
|
|
.Xr src.conf 5
|
|
to use for the release build.
|
|
Defaults to
|
|
.Fa /dev/null
|
|
to prevent polluting the release with local system changes.
|
|
.It Va MAKE_FLAGS
|
|
Additional flags to pass to
|
|
.Xr make 1 .
|
|
.It Va WORLD_FLAGS
|
|
Additional flags to pass to
|
|
.Xr make 1
|
|
during the
|
|
.Dq buildworld
|
|
phase.
|
|
Defaults to setting the number of
|
|
.Xr make 1
|
|
jobs
|
|
.Pq Ar -j
|
|
to the number of CPUs available on a SMP-capable system.
|
|
.It Va KERNEL_FLAGS
|
|
Additional flags to pass to
|
|
.Xr make 1
|
|
during the
|
|
.Dq buildkernel
|
|
phase.
|
|
Defaults to setting the number of
|
|
.Xr make 1
|
|
jobs
|
|
.Pq Ar -j
|
|
to half the number of CPUs available on a SMP-capable system.
|
|
.It Va NODOC
|
|
Set to a non-empty value to skip the
|
|
.Li doc/
|
|
tree checkout.
|
|
When set,
|
|
.Va NODOC
|
|
will prevent the
|
|
.Fa doc.txz
|
|
distribution package from being created.
|
|
.It Va NODVD
|
|
Set to a non-empty value to skip the
|
|
.Cm dvdrom
|
|
target.
|
|
.It Va NOPORTS
|
|
Set to a non-empty value to skip the
|
|
.Li ports/
|
|
tree checkout.
|
|
When set,
|
|
.Va NOPORTS
|
|
will prevent the
|
|
.Fa ports.txz
|
|
distribution package from being created.
|
|
Setting this also sets
|
|
.Va NODOC .
|
|
.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.
|
|
This may require 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 disc1.iso
|
|
and
|
|
.Pa bootonly.iso
|
|
as its output.
|
|
.It Cm dvdrom
|
|
Builds installation DVD-ROM images.
|
|
This may require 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 the
|
|
.Pa dvd1.iso
|
|
file as its output.
|
|
.It Cm memstick
|
|
Builds an installation memory stick image named
|
|
.Pa memstick.img .
|
|
Not applicable on all platforms.
|
|
Requires that the
|
|
.Xr md 4
|
|
.Pq memory disk
|
|
device driver be present in the kernel
|
|
.Pq either by being compiled in or available as a module .
|
|
.It Cm mini-memstick
|
|
Similar to
|
|
.Cm memstick ,
|
|
with the exception that the installation distribution sets
|
|
are not included.
|
|
.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
|
|
.Pq 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 ,
|
|
.Cm dvdrom
|
|
and
|
|
.Cm memstick
|
|
targets.
|
|
.It Cm reldoc
|
|
Builds the release documentation.
|
|
This includes the release notes,
|
|
hardware guide, and installation instructions.
|
|
Other documentation, such as the Handbook,
|
|
is built during the
|
|
.Cm base.txz
|
|
target invoked by
|
|
.Cm packagesystem .
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
Optional variables:
|
|
.Bl -tag -width ".Ev TARGET_ARCH"
|
|
.It Ev OSRELEASE
|
|
Optional base name for generated media images
|
|
.Pq e.g., FreeBSD-9.0-RC2-amd64 .
|
|
Defaults to the output of
|
|
.Ic `uname -s`-`uname -r`-`uname -p`
|
|
within the chroot.
|
|
.It Ev WORLDDIR
|
|
Location of a directory containing the src tree.
|
|
By default, the directory
|
|
above the one containing the makefile
|
|
.Pq Pa src .
|
|
.It Ev 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 Ev 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 Ev NOPORTS
|
|
If defined, the Ports Collection will be omitted from the release.
|
|
.It Ev NOSRC
|
|
If set, do not include system source code in the release.
|
|
.It Ev 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 Ev 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
|
|
.Ev TARGET_ARCH Ns = Ns Li i386
|
|
and
|
|
.Ev TARGET Ns = Ns Li pc98 .
|
|
If not set,
|
|
.Ev TARGET
|
|
defaults to the current hardware platform.
|
|
.It Ev 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,
|
|
.Ev TARGET_ARCH
|
|
defaults to the current machine architecture, unless
|
|
.Ev TARGET
|
|
is also set, in which case it defaults to the appropriate
|
|
value for that platform.
|
|
Typically, one only needs to set
|
|
.Ev 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/release.sh
|
|
.It Pa /usr/src/release/release.conf.sample
|
|
.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
|
|
sh release.sh
|
|
.Ed
|
|
.Pp
|
|
Optionally, a configuration file can be used customize the release build,
|
|
such as the subversion revision to use, the branch of the subversion tree for
|
|
.Li src/ ,
|
|
.Li ports/ ,
|
|
and
|
|
.Li doc/ .
|
|
.Bd -literal -offset indent
|
|
cd /usr/src/release
|
|
sh release.sh -c $HOME/release.conf
|
|
.Ed
|
|
.Pp
|
|
After running these commands, all prepared release files are available in the
|
|
.Pa /scratch
|
|
directory.
|
|
The target directory can be changed by specifying the
|
|
.Va CHROOTDIR
|
|
variable in
|
|
.Li release.conf .
|
|
.Sh SEE ALSO
|
|
.Xr cc 1 ,
|
|
.Xr install 1 ,
|
|
.Xr make 1 ,
|
|
.Xr svn 1 Pq Pa ports/devel/subversion ,
|
|
.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
|
|
For the
|
|
.Fx 9.2
|
|
release,
|
|
.Pa src/release/release.sh
|
|
was introduced to support per-build configuration files.
|
|
.Pa src/release/release.sh
|
|
is heavily based on the
|
|
.Pa src/release/generate-release.sh
|
|
script.
|
|
.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 .
|
|
.Pp
|
|
This manual page was originally written by
|
|
.An Murray Stokely Aq murray@FreeBSD.org .
|
|
.Pp
|
|
It was updated by
|
|
.An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org
|
|
to include the
|
|
.Fa generate-release.sh
|
|
script used for the
|
|
.Fx 9.0
|
|
release cycle.
|
|
.Pp
|
|
It was later updated by
|
|
.An Glen Barber Aq gjb@FreeBSD.org
|
|
to include the
|
|
.Fa release.sh
|
|
script used for the
|
|
.Fx 9.2
|
|
release cycle.
|