541 lines
16 KiB
Groff
541 lines
16 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 12, 2006
|
|
.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
|
|
CVS 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,
|
|
installation floppies, and an FTP install directory.
|
|
This command is aptly named
|
|
.Dq Li "make release" .
|
|
.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.
|
|
The release build process requires that
|
|
.Pa /usr/obj
|
|
be populated with the output of
|
|
a native
|
|
.Dq Li "make buildworld"
|
|
compiled from sources matching the currently running kernel.
|
|
This is necessary so that the object files for a complete system can
|
|
be installed into a clean
|
|
.Xr chroot 8
|
|
environment.
|
|
The release procedure also 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).
|
|
.Pp
|
|
This document does not cover source code management, quality
|
|
assurance, or other aspects of the release engineering process.
|
|
.Sh TARGETS
|
|
The release makefile
|
|
.Pq Pa src/release/Makefile
|
|
is fairly abstruse.
|
|
Most developers will only be concerned with the
|
|
.Cm release
|
|
target.
|
|
.\" XXX: Some sort of introduction to this list? All the others have one.
|
|
.Bl -tag -width ".Cm package-split"
|
|
.It Cm release
|
|
Uses
|
|
.Dq Li "make installworld"
|
|
to install a clean system into a
|
|
.Xr chroot 8
|
|
environment on the file system.
|
|
Checks out the specified version of the source code and then rebuilds
|
|
the entire system in the clean environment with
|
|
.Dq Li "make buildworld" .
|
|
The detailed steps that follow are then executed to package up the
|
|
different distributions, build the installation floppy disks, build
|
|
release documentation, and so on.
|
|
.Pp
|
|
This target must be built as root with the
|
|
.Va kern.securelevel
|
|
sysctl set to \-1 (the default).
|
|
.It Cm rerelease
|
|
Assumes that the output of a release build has been manually modified,
|
|
and performs the minimal number of steps to rebuild the release using
|
|
the intermediate output of the previous
|
|
.Dq Li "make release" .
|
|
.It Cm floppies
|
|
Generate a new set of boot and fixit floppies.
|
|
This will call the
|
|
.Cm release.4 ,
|
|
.Cm release.8 ,
|
|
.Cm floppies.1 ,
|
|
.Cm floppies.2 ,
|
|
and
|
|
.Cm floppies.3
|
|
targets to re-generate the floppy images of a previous
|
|
.Dq Li "make release" .
|
|
This is most often used to build custom boot floppies.
|
|
.It Cm package-split
|
|
Generates the portions of the disc 1 and disc 2 images related to packages.
|
|
It uses the list of desired packages from the
|
|
.Pa src/release/scripts/package-split.py
|
|
script to pull packages out of a package build provided by the ports team
|
|
and organize them appropriately.
|
|
The resulting directory can then be passed to
|
|
.Dq Li "make release"
|
|
via the
|
|
.Va CD_PACKAGE_TREE
|
|
variable to populate the ISO images built by the
|
|
.Cm iso.1
|
|
target with the correct package related bits.
|
|
.El
|
|
.Pp
|
|
Targets called by
|
|
.Dq Li "make release" :
|
|
.Bl -tag -width ".Cm fetch-distfiles"
|
|
.It Cm release.1
|
|
Cleans out the
|
|
.Pa ${CHROOTDIR}/R
|
|
directory and uses
|
|
.Xr mtree 8
|
|
to build the directory hierarchy for the system.
|
|
.It Cm release.2
|
|
Installs the system into the distribution directories.
|
|
.It Cm release.3
|
|
Makes and installs the
|
|
.Pa GENERIC
|
|
kernel as well as any other kernels listed in
|
|
.Va KERNELS .
|
|
.It Cm release.4
|
|
Uses
|
|
.Xr crunchgen 1
|
|
to build
|
|
.Dq crunched
|
|
binaries to live on the installation floppies.
|
|
.It Cm release.5
|
|
Builds synthetic distributions, and cleans up the previously built
|
|
distribution trees.
|
|
.It Cm release.6
|
|
Creates tarballs of the assembled distribution trees.
|
|
.It Cm release.7
|
|
Makes source distributions.
|
|
.It Cm release.8
|
|
Creates the MFS root file systems.
|
|
.It Cm floppies.1
|
|
Creates the boot and kernel floppies.
|
|
.It Cm floppies.2
|
|
Creates the fixit floppy.
|
|
.It Cm floppies.3
|
|
Finalizes the
|
|
.Pa ${CHROOTDIR}/R/ftp/stage/floppies
|
|
staging directory.
|
|
.It Cm ftp.1
|
|
Sets up a suitable area for FTP installations in
|
|
.Pa ${CHROOTDIR}/R/ftp .
|
|
.It Cm cdrom.1
|
|
Create the layout for the live file system CD-ROM image in
|
|
.Pa ${CHROOTDIR}/R/cdrom .
|
|
.It Cm cdrom.2
|
|
Create the layout for the first and second CD-ROM images.
|
|
.It Cm cdrom.3
|
|
Create the layout for the boot-only CD-ROM image and the boot-only UFS
|
|
miniroot image.
|
|
.It Cm iso.1
|
|
Builds ISO images (installation and
|
|
.Dq live
|
|
file system) from the CD-ROM release area
|
|
(disabled by default, see
|
|
.Va MAKE_ISOS
|
|
below).
|
|
.It Cm fetch-distfiles
|
|
Fetches distfiles needed during the release build that are not already in
|
|
.Va RELEASEDISTFILES .
|
|
.It Cm doc.1
|
|
Builds all of the necessary tools to turn the
|
|
.Fx
|
|
Documentation Project source documents (SGML, XML) into HTML
|
|
and text documents that will accompany the release.
|
|
Also, builds and installs the actual user documentation.
|
|
This includes the Handbook, FAQ, articles, and so on.
|
|
.It Cm doc.2
|
|
Builds the release documentation.
|
|
This includes the release notes,
|
|
hardware guide, and installation instructions.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
Variables that must be specified:
|
|
.Bl -tag -width ".Va CHROOTDIR"
|
|
.It Va CHROOTDIR
|
|
The directory to be used as the
|
|
.Xr chroot 8
|
|
environment for the entire release build.
|
|
.\" XXX: I recommend against hardcoding specific numbers like "2.3" here;
|
|
.\" XXX: perhaps it should be replaced with something to the effect of
|
|
.\" XXX: "we do not know how much space you'll need, but make sure you have
|
|
.\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number,
|
|
.\" XXX: but at least it looks less like a decree and more like an estimate.
|
|
This file system should have at least 3.2 gigabytes of free space on the
|
|
i386 architecture.
|
|
.It Va CVSROOT
|
|
The location of the
|
|
.Fx
|
|
CVS repository.
|
|
This path name is in reference to the real system root,
|
|
.Em not
|
|
the root of the
|
|
.Xr chroot 8
|
|
directory tree.
|
|
.El
|
|
.Pp
|
|
Optional variables:
|
|
.Bl -tag -width ".Va NO_PREFETCHDISTFILES"
|
|
.It Va BUILDNAME
|
|
The name of the release to be built.
|
|
This is used to set the
|
|
.Va RELEASE
|
|
value in
|
|
.Pa sys/conf/newvers.sh ,
|
|
which affects the output of
|
|
.Xr uname 1 .
|
|
If not set, a name with the timestamp and the
|
|
.Dq Li -SNAP
|
|
suffix will be generated.
|
|
.It Va CD_PACKAGE_TREE
|
|
A directory containing extra bits for the first and second CD-ROM images.
|
|
The extra files for the first disc should be in
|
|
.Pa ${CD_PACKAGE_TREE}/disc1
|
|
and the extra files for the second disc should be in
|
|
.Pa ${CD_PACKAGE_TREE}/disc2 .
|
|
Typically, this variable will be set to the output directory of an earlier
|
|
invocation of the
|
|
.Cm package-split
|
|
target.
|
|
.It Va CVSARGS
|
|
Additional arguments for
|
|
.Xr cvs 1
|
|
that come before the subcommands such as
|
|
.Dq Li "-qR" .
|
|
.It Va CVSCMDARGS
|
|
Additional arguments for
|
|
.Xr cvs 1
|
|
.Ic checkout
|
|
and
|
|
.Ic update
|
|
commands.
|
|
For example, setting this variable to
|
|
.Dq Li "-D '01/01/2002 00:00:00 GMT'"
|
|
for
|
|
.Dq Li "make release"
|
|
or
|
|
.Dq Li "make rerelease"
|
|
will ask
|
|
.Xr cvs 1
|
|
to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively.
|
|
.It Va DOC_LANG
|
|
The list of languages and encodings the SGML-based documentation
|
|
should be built for.
|
|
If not set, the documentation is built for all available languages.
|
|
.It Va DOCRELEASETAG
|
|
The CVS tag to use when checking out the documentation tree.
|
|
Usually,
|
|
the head of the documentation tree is used by default.
|
|
If
|
|
.Va RELEASETAG
|
|
specifies a release tag,
|
|
then the associated release version is used as the default instead.
|
|
.It Va EXTLOCALDIR
|
|
The directory that will be copied to
|
|
.Pa ${CHROOTDIR}/usr/local .
|
|
.It Va EXTSRCDIR
|
|
The directory specified by this variable will be copied into
|
|
.Pa ${CHROOTDIR}/usr/src
|
|
instead of that directory being populated by a CVS checkout.
|
|
For
|
|
.Dq Li "rerelease" ,
|
|
this will NOT be copied; cvs update will be used instead.
|
|
.It Va EXTDOCDIR
|
|
The directory specified by this variable will be copied into
|
|
.Pa ${CHROOTDIR}/usr/doc .
|
|
For
|
|
.Dq Li "rerelease" ,
|
|
this will NOT be copied again.
|
|
.It Va EXTPORTSDIR
|
|
The directory specified by this variable will be copied into
|
|
.Pa ${CHROOTDIR}/usr/ports .
|
|
For
|
|
.Dq Li "rerelease" ,
|
|
this will do NOTHING.
|
|
.It Va KERNEL_FLAGS
|
|
The contents of this variable are passed to
|
|
.Xr make 1
|
|
when building kernels during the release build.
|
|
For example, setting this variable to
|
|
.Dq Li "-j 4"
|
|
will instruct
|
|
.Xr make 1
|
|
to execute up to four processes at a time.
|
|
.It Va KERNELS
|
|
Specifies a list of additional kernel configurations to compile and
|
|
install into the
|
|
.Dq base
|
|
distribution.
|
|
Each kernel is installed into
|
|
.Pa /boot/<config>
|
|
so that it can be booted from the loader via
|
|
.Dq Li "boot <config>" .
|
|
.It Va LOCAL_PATCHES
|
|
Patch files against
|
|
.Pa /usr/src
|
|
that will be applied in the
|
|
.Xr chroot 8
|
|
environment before the release build begins.
|
|
.It Va PATCH_FLAGS
|
|
Arguments for the
|
|
.Xr patch 1
|
|
command used to apply
|
|
.Va LOCAL_PATCHES
|
|
patch file.
|
|
.It Va LOCAL_SCRIPT
|
|
A script that will be run in the
|
|
.Xr chroot 8
|
|
environment immediately after any local patches are applied.
|
|
.It Va MAKE_ISOS
|
|
If defined, bootable ISO CD-ROM images will be created from the
|
|
contents of the CD-ROM stage directory.
|
|
.It Va NOCDROM
|
|
If defined, the CD-ROM stage directories will not be created.
|
|
.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 NO_FLOPPIES
|
|
If defined, no boot and fixit floppy disk images will be created (for those
|
|
platforms supporting them).
|
|
.It Va NOPORTS
|
|
If defined, the Ports Collection will be omitted from the release.
|
|
.It Va PORTSRELEASETAG
|
|
The CVS tag to use when checking out the ports tree.
|
|
Usually,
|
|
the head of the ports tree is used by default.
|
|
If
|
|
.Va RELEASETAG
|
|
specifies a release tag,
|
|
then the associated release version is used as the default instead.
|
|
.It Va NO_PREFETCHDISTFILES
|
|
If this variable is defined,
|
|
then distfiles needed during the release build will not be downloaded prior to
|
|
entering the
|
|
.Xr chroot 8
|
|
environment.
|
|
Note that if
|
|
.Va NO_PREFETCHDISTFILES
|
|
is not set,
|
|
the fetching is done after any distfiles are obtained via
|
|
.Va RELEASEDISTFILES .
|
|
.It Va RELEASEDISTFILES
|
|
The directory where the distribution files for ports required by the
|
|
release build can be found.
|
|
This may save a significant amount of time over downloading the
|
|
distfiles through a slow link.
|
|
.It Va RELEASENOUPDATE
|
|
If this variable is defined for
|
|
.Dq Li "make rerelease" ,
|
|
the source code will not be updated with
|
|
.Dq Li "cvs update" .
|
|
.It Va RELEASETAG
|
|
The CVS tag corresponding to the release that is to be built.
|
|
If undefined, the release will be built from the
|
|
.Dv HEAD
|
|
of the CVS tree
|
|
(a
|
|
.Dq "-CURRENT snapshot" ) .
|
|
.It Va SEPARATE_LIVEFS
|
|
Store the live file system on its own CD-ROM image rather than placing it on
|
|
the first disc.
|
|
.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.
|
|
.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 .
|
|
.It Va WORLDDIR
|
|
The directory where
|
|
.Dq Li "make buildworld"
|
|
was run; defaults to
|
|
.Pa ${.CURDIR}/..
|
|
which usually points to
|
|
.Pa /usr/src .
|
|
.It Va WORLD_FLAGS
|
|
The contents of this variable are passed to
|
|
.Xr make 1
|
|
when building world during the release build.
|
|
For example, setting this variable to
|
|
.Dq Li "-j 4"
|
|
will instruct
|
|
.Xr make 1
|
|
to execute up to four processes at a time.
|
|
.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/${arch}/boot_crunch.conf
|
|
.It Pa /usr/src/release/${arch}/fixit_crunch.conf
|
|
.El
|
|
.Sh EXAMPLES
|
|
The following sequence of commands was used to build the
|
|
.Fx 4.9
|
|
release:
|
|
.Bd -literal -offset indent
|
|
cd /usr
|
|
cvs co -rRELENG_4_9_0_RELEASE src
|
|
cd src
|
|
make buildworld
|
|
cd release
|
|
make release CHROOTDIR=/local3/release BUILDNAME=4.9-RELEASE \\
|
|
CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_9_0_RELEASE
|
|
.Ed
|
|
.Pp
|
|
After running these commands, a complete system suitable for FTP or
|
|
CD-ROM distribution is available in the
|
|
.Pa /local3/release/R
|
|
directory.
|
|
.Pp
|
|
The following sequence of commands can be used to build a
|
|
.Dq "-CURRENT snapshot"
|
|
of a
|
|
locally modified source tree:
|
|
.Bd -literal -offset indent
|
|
cd /usr/src
|
|
cvs diff -u > /path/to/local.patch
|
|
make buildworld
|
|
cd release
|
|
make release CHROOTDIR=/local3/release BUILDNAME=6.0-CURRENT \\
|
|
CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr cc 1 ,
|
|
.Xr crunchgen 1 ,
|
|
.Xr cvs 1 ,
|
|
.Xr install 1 ,
|
|
.Xr make 1 ,
|
|
.Xr patch 1 ,
|
|
.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"
|
|
.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
|
|
.Re
|
|
.Rs
|
|
.%T "FreeBSD Release Engineering of Third Party Packages"
|
|
.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
|
|
.Re
|
|
.Rs
|
|
.%T "FreeBSD Developers' Handbook"
|
|
.%O 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
|
|
With its almost 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 .
|
|
.Sh BUGS
|
|
Infrastructure changes are occasionally made to the
|
|
.Fx
|
|
documentation set in such a way that release builds on security
|
|
branches can fail.
|
|
To work around this, release builds can be made to checkout the
|
|
documentation from the last fully supported release of
|
|
.Fx .
|
|
For example:
|
|
.Pp
|
|
.Dl "make release RELEASETAG=RELENG_4_9 DOCRELEASETAG=RELEASE_4_9_0 ..."
|