300 lines
9.0 KiB
Groff
300 lines
9.0 KiB
Groff
|
.\" Copyright (c) 2002
|
||
|
|
.\" Murray Stokely <murray@FreeBSD.org>
|
||
|
|
.\"
|
||
|
|
.\" 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 March 12, 2002
|
||
|
|
.Dt RELEASE 7
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm release
|
||
|
|
.Nd information on the process used to build a complete system release
|
||
|
|
.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 CDROM,
|
||
|
|
installation floppies, and an FTP install directory.
|
||
|
|
This command is aptly named
|
||
|
|
.Dq make release .
|
||
|
|
.Pp
|
||
|
|
Before attempting to build a release, the user is expected to be
|
||
|
|
experienced with the contents of
|
||
|
|
.Xr build 7 ,
|
||
|
|
and should have experience upgrading systems from source with
|
||
|
|
.Dq make world .
|
||
|
|
The release build process requires that
|
||
|
|
.Pa /usr/obj
|
||
|
|
be populated with the output of
|
||
|
|
.Dq make buildworld .
|
||
|
|
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
|
||
|
|
.Pa md
|
||
|
|
(memory disk) device driver be present in the kernel.
|
||
|
|
.Pp
|
||
|
|
This document does not cover source code management, quality
|
||
|
|
assurance, or other aspects of the release engineering process.
|
||
|
|
.Sh TARGETS
|
||
|
|
.Pp
|
||
|
|
The release makefile
|
||
|
|
.Pa (src/release/makefile)
|
||
|
|
is fairly abstruse.
|
||
|
|
Most developers will only be concerned with the
|
||
|
|
.Pa release
|
||
|
|
target.
|
||
|
|
.Bl -tag -width configure
|
||
|
|
.It Ar release
|
||
|
|
Uses
|
||
|
|
.Dq make installworld
|
||
|
|
to install a clean system into a
|
||
|
|
.Xr chroot 8
|
||
|
|
environment on the filesystem.
|
||
|
|
Checks out the specified version of the source code and then rebuilds
|
||
|
|
the entire system in the clean environment with
|
||
|
|
.Dq make world .
|
||
|
|
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.
|
||
|
|
.It Ar 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 make release .
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
Targets called by
|
||
|
|
.Dq make release .
|
||
|
|
.Bl -tag -width configure
|
||
|
|
.It Ar release.1
|
||
|
|
Cleans out the
|
||
|
|
.Pa ${CHROOTDIR}/R
|
||
|
|
directory and uses
|
||
|
|
.Xr mtree 1
|
||
|
|
to build the directory hierarchy for the system.
|
||
|
|
.It Ar release.2
|
||
|
|
Installs the system into the distribution directories.
|
||
|
|
.It Ar release.3
|
||
|
|
Makes and installs the GENERIC kernel(s).
|
||
|
|
.It Ar release.4
|
||
|
|
Uses
|
||
|
|
.Xr crunchgen 1
|
||
|
|
to build
|
||
|
|
.Sq crunched
|
||
|
|
binaries to live on the installation floppies.
|
||
|
|
.It Ar release.5
|
||
|
|
Builds synthetic distributions, and cleans up the previously built
|
||
|
|
distribution trees.
|
||
|
|
.It Ar release.6
|
||
|
|
Creates tarballs of the assembled distribution trees.
|
||
|
|
.It Ar release.7
|
||
|
|
Makes source distributions.
|
||
|
|
.It Ar release.8
|
||
|
|
Creates the boot and MFS root floppies.
|
||
|
|
.It Ar release.9
|
||
|
|
Creates the fixit floppy.
|
||
|
|
.It Ar ftp.1
|
||
|
|
Sets up a suitable area for FTP installations.
|
||
|
|
.It Ar cdrom.1
|
||
|
|
Sets up a suitable area to build CDROM images.
|
||
|
|
.It Ar iso.1
|
||
|
|
Builds two ISO images (installation and
|
||
|
|
.Sq live
|
||
|
|
filesystem) from the CDROM release area.
|
||
|
|
.It Ar doc.1
|
||
|
|
Builds all of the necessary tools to turn the FreeBSD 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 Ar doc.2
|
||
|
|
Builds the release documentation. This includes the release notes,
|
||
|
|
hardware guide, and installation instructions.
|
||
|
|
.El
|
||
|
|
.Sh ENVIRONMENT
|
||
|
|
.Pp
|
||
|
|
Variables that you must specify:
|
||
|
|
.Bl -tag -width configure
|
||
|
|
.It Ev CHROOTDIR
|
||
|
|
The directory to be used as the
|
||
|
|
.Xr chroot 8
|
||
|
|
environment for the entire release build.
|
||
|
|
This filesystem should have at least 2.3 gigabytes of free space on the
|
||
|
|
i386 architecture.
|
||
|
|
.It Ev BUILDNAME
|
||
|
|
The name of the release to be built. This is used to set the
|
||
|
|
.Pa RELEASE
|
||
|
|
value in
|
||
|
|
.Pa sys/conf/newvers.sh ,
|
||
|
|
which affects the output of
|
||
|
|
.Xr uname 1 .
|
||
|
|
.It Ev CVSROOT
|
||
|
|
The location of a CVS Repository.
|
||
|
|
.It Ev RELEASETAG
|
||
|
|
The CVS tag corresponding to the release you would like to build.
|
||
|
|
If undefined, the release will be built from the HEAD of the CVS tree
|
||
|
|
(a
|
||
|
|
.Sq -CURRENT snapshot
|
||
|
|
).
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
Optional variables:
|
||
|
|
.Bl -tag -width configure
|
||
|
|
.It Ev LOCAL_PATCHES
|
||
|
|
A patch file against
|
||
|
|
.Pa /usr/src
|
||
|
|
that will be applied in the
|
||
|
|
.Xr chroot 8
|
||
|
|
environment before the release build begins.
|
||
|
|
.It Ev PATCH_FLAGS
|
||
|
|
Arguments for the
|
||
|
|
.Xr patch 1
|
||
|
|
command used to apply
|
||
|
|
.Pa LOCAL_PATCHES .
|
||
|
|
.It Ev MAKE_ISOS
|
||
|
|
If defined, bootable ISO CDROM images will be created from the
|
||
|
|
contents of the CDROM stage directory.
|
||
|
|
.It Ev NODOC
|
||
|
|
If set to
|
||
|
|
.Dq YES
|
||
|
|
then the documentation will not be built. Due to the SGML based
|
||
|
|
toolchain and multiple languages supported by the
|
||
|
|
.Fx
|
||
|
|
Documentation Project, this may speed up the release build time
|
||
|
|
considerably.
|
||
|
|
.It Ev NOPORTS
|
||
|
|
If set to
|
||
|
|
.Dq YES
|
||
|
|
then the ports tree will be omitted from the release.
|
||
|
|
.It Ev 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 Ev RELEASENOUPDATE
|
||
|
|
If this variable is defined for
|
||
|
|
.Dq make rerelease ,
|
||
|
|
the source code will not be updated with
|
||
|
|
.Dq cvs up .
|
||
|
|
.El
|
||
|
|
.Sh FILES
|
||
|
|
.Bl -tag -compact
|
||
|
|
.It Pa /etc/make.conf
|
||
|
|
.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}/drivers.conf
|
||
|
|
.It Pa /usr/src/release/${arch}/boot_crunch.conf
|
||
|
|
.It Pa /usr/src/release/${arch}/fixit_crunch.conf
|
||
|
|
.El
|
||
|
|
.Sh EXAMPLES
|
||
|
|
The following commands were used to build the
|
||
|
|
.Fx 4.5
|
||
|
|
release :
|
||
|
|
.Bd -literal -offset indent
|
||
|
|
cd /usr
|
||
|
|
cvs co -rRELENG_4_5_0_RELEASE src
|
||
|
|
cd src
|
||
|
|
make buildworld
|
||
|
|
cd release
|
||
|
|
make release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\
|
||
|
|
CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_5_0_RELEASE
|
||
|
|
.Ed
|
||
|
|
.Pp
|
||
|
|
After running these commands, a complete system suitable for FTP or
|
||
|
|
CDROM distribution is available in the
|
||
|
|
.Pa /local3/release/R/
|
||
|
|
directory.
|
||
|
|
.Pp
|
||
|
|
The following commands can be used to build a -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=5.0-SNAPSHOT \\
|
||
|
|
CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
|
||
|
|
.Ed
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr cc 1 ,
|
||
|
|
.Xr crunchgen 1 ,
|
||
|
|
.Xr install 1 ,
|
||
|
|
.Xr make 1 ,
|
||
|
|
.Xr mtree 1 ,
|
||
|
|
.Xr patch 1 ,
|
||
|
|
.Xr uname 1 ,
|
||
|
|
.Xr make.conf 5 ,
|
||
|
|
.Xr build 7 ,
|
||
|
|
.Xr ports 7 ,
|
||
|
|
.Xr chroot 8
|
||
|
|
.Pp
|
||
|
|
.Fx
|
||
|
|
Release Engineering
|
||
|
|
http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng
|
||
|
|
.Pp
|
||
|
|
.Fx
|
||
|
|
Release Engineering of Third Party Packages
|
||
|
|
http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages
|
||
|
|
.Pp
|
||
|
|
.Fx
|
||
|
|
Developer's Handbook
|
||
|
|
http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook
|
||
|
|
.Sh HISTORY
|
||
|
|
.Pp
|
||
|
|
.Fx
|
||
|
|
1.x
|
||
|
|
used a manual checklist, compiled by Rod Grimes to produce a release.
|
||
|
|
Apart from being incomplete, the list put a lot of specific demands on
|
||
|
|
available filesystems and was quite torturous to execute.
|
||
|
|
.Pp
|
||
|
|
As part of the FreeBSD 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 cvs
|
||
|
|
log of 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 Rod Grimes, Jordan Hubbard, and Poul-Henning
|
||
|
|
Kamp.
|
||
|
|
This man page was written by
|
||
|
|
.An Murray Stokely Aq murray@FreeBSD.org .
|