diff options
| -rw-r--r-- | share/man/man7/release.7 | 301 |
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. |
