summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--share/man/man7/release.7301
1 files changed, 230 insertions, 71 deletions
diff --git a/share/man/man7/release.7 b/share/man/man7/release.7
index 8216eef..c872d54 100644
--- a/share/man/man7/release.7
+++ b/share/man/man7/release.7
@@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd February 3, 2013
+.Dd August 11, 2013
.Dt RELEASE 7
.Os
.Sh NAME
@@ -50,8 +50,9 @@ 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
+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
@@ -70,86 +71,194 @@ and
.Dq Li "make buildkernel" .
This is necessary to provide the object files for the release or, when
using
-.Pa generate-release.sh ,
+.Pa 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).
+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
-(either by being compiled in or available as a module).
+.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 FreeBSD are produced in a totally clean environment to
+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 (e.g. local patches, changes
+and to avoid contamination from the host system
+.Po such as local patches, changes
to
.Xr make.conf 5 ,
-etc.). This is accomplished using the wrapper script
-.Pa src/release/generate-release.sh .
+etc.
+.Pc .
+This is accomplished using the wrapper script
+.Pa src/release/release.sh .
.Pp
-.Ic generate-release.sh
-svn-branch scratch-dir
+.Ic release.sh
+.Op Fl c Ar release.conf
.Pp
-.Ic generate-release.sh
-calls
+.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 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
+environment.
+Next,
.Dq Li "make release"
-within the
+is run 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.
+.Pa $CHROOTDIR/R .
.Pp
-Optional environment variables:
-.Bl -tag -width ".Cm WORLD_FLAGS"
-.It Ev WORLD_FLAGS
-This environment variable can be set to pass flags (e.g. -j) to
-.Xr make 1
-when invoked to build a world by the script.
-.It Ev KERNEL_FLAGS
-This environment variable can be set to pass flags (e.g. -j) to
-.Xr make 1
-when invoked to build a kernel by the script.
-.It Ev SVNROOTBASE
-The base part of URL of the FreeBSD SVN repositories.
+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.freebsd.org .
-.It Ev SVNROOTSRC
-The URL of the FreeBSD SVN source repository.
+.Pa svn://svn.FreeeBSD.org .
+.It Va SRCBRANCH
+The
+.Li src/
+branch to use.
Defaults to
-.Pa ${SVNROOTBASE}/base .
-.It Ev SVNROOTDOC
-The URL of the FreeBSD SVN doc repository.
+.Va head/ .
+.It Va DOCBRANCH
+The
+.Li doc/
+branch to use.
Defaults to
-.Pa ${SVNROOTBASE}/doc .
-.It Ev SVNROOTPORTS
-The URL of the FreeBSD SVN ports repository.
+.Va head/ .
+.It Va PORTBRANCH
+The
+.Li ports/
+branch to use.
Defaults to
-.Pa ${SVNROOTBASE}/ports .
-.It Ev BRANCHDOC
-The branch name of the FreeBSD SVN doc repository.
+.Va head/ .
+.It Va SRCREVISION
+The revision of the
+.Li src/
+tree to use.
+Defaults to the current top of tree revision.
+.It Va DOCREVISION
+The revision of the
+.Li doc/
+tree to use.
+Defaults to the current top of tree revision.
+.It Va PORTREVISION
+The revision of the
+.Li ports/
+tree to use.
+Defaults to the current top of tree revision.
+.It Va TARGET
+The target machine type for the release.
+Defaults to the current machine type.
+.It Va TARGET_ARCH
+The target machine architecture for the release.
+Defaults to the value of
+.Va TARGET .
+.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
-.Pa head .
-.It Ev BRANCHPORTS
-The branch name of the FreeBSD SVN ports repository.
+.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
-.Pa head .
+.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 the 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 the 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 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
@@ -175,18 +284,19 @@ This may require the
(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
+.Pa disc1.iso
and
.Pa bootonly.iso
as its output.
.It Cm memstick
Builds an installation memory stick image named
-.Pa memstick .
+.Pa memstick.img .
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).
+.Pq memory disk
+device driver be present in the kernel
+.Pq either by being compiled in or available as a module .
.It Cm ftp
Creates a directory named
.Pa ftp
@@ -197,7 +307,8 @@ and suitable for upload to an FTP mirror.
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)
+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
@@ -211,8 +322,9 @@ 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
+hardware guide, and installation instructions.
+Other documentation, such as the Handbook,
+is built during the
.Cm base.txz
target invoked by
.Cm packagesystem .
@@ -221,20 +333,24 @@ target invoked by
Optional variables:
.Bl -tag -width ".Ev TARGET_ARCH"
.It Ev OSRELEASE
-Optional base name for generated media images (e.g. FreeBSD-9.0-RC2-amd64).
+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
+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,
+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,
+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
@@ -291,7 +407,8 @@ Typically, one only needs to set
.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
+.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
@@ -316,12 +433,27 @@ The following sequence of commands can be used to build a
in a clean environment, including ports and documentation:
.Bd -literal -offset indent
cd /usr/src/release
-sh generate-release.sh head /local3/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 /local3/release/R
+.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 ,
@@ -372,6 +504,16 @@ 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
@@ -386,5 +528,22 @@ was originally written by
.An Jordan Hubbard ,
and
.An Poul-Henning Kamp .
-This manual page was written by
+.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.
OpenPOWER on IntegriCloud