d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

- Update the wrapper script to 'release.sh', as used by the FreeBSD

Browse Source 
Release Engineering Team as of 9.2-RELEASE.

- Document that a cross-build release is possible by setting the
  TARGET and TARGET_ARCH variables.

- Include an example of using release.sh with and without the
  optional configuration file.

- Document the supported release.sh configuration file variables.

- Update the 'cdrom' target output file to disc1.iso.

- Update the 'memstick' target output file to memstick.img.

- Add attributions for the last major updates to this manual page.

- Fix some mdoc(7) style nits:
  - Sentences should begin on a new line
  - Use .Pq to enclose full lines in parenthesis
This commit is contained in:
Glen Barber 2013-08-11 18:57:27 +00:00
parent a790431ec0
commit ebe2785690
1 changed files with 234 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

309
share/man/man7/release.7
View File

@ -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
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/ .
.It Va DOCBRANCH
The
.Li doc/
branch to use.
Defaults to
.Va head/ .
.It Va PORTBRANCH
The
.Li ports/
branch to use.
Defaults to
.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
.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
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
during the
.Dq buildworld
phase.
Defaults to setting the number of
.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.
Defaults to
.Pa svn://svn.freebsd.org .
.It Ev SVNROOTSRC
The URL of the FreeBSD SVN source repository.
Defaults to
.Pa ${SVNROOTBASE}/base .
.It Ev SVNROOTDOC
The URL of the FreeBSD SVN doc repository.
Defaults to
.Pa ${SVNROOTBASE}/doc .
.It Ev SVNROOTPORTS
The URL of the FreeBSD SVN ports repository.
Defaults to
.Pa ${SVNROOTBASE}/ports .
.It Ev BRANCHDOC
The branch name of the FreeBSD SVN doc repository.
Defaults to
.Pa head .
.It Ev BRANCHPORTS
The branch name of the FreeBSD SVN ports repository.
Defaults to
.Pa head .
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.