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

Add a makefile to document the release building process.

Browse Source 
Specifically, this documents the available targets and relevant
environment variables for "make release".  LOCAL_PATCHES,
RELEASEDISTFILES, RELEASENOUPDATE, etc.. are covered.

A future commit should add more information about drivers.conf,
boot_crunch.conf, and other less well-known aspects of the release
build.

Reviewed and history section added by:	phk
This commit is contained in:
Murray Stokely 2002-03-13 06:33:26 +00:00
parent 9ad1d32f3d
commit de26e0ad7a
2 changed files with 301 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
share/man/man7/Makefile
View File

@ -3,8 +3,8 @@
#MISSING: eqnchar.7 ms.7 term.7
MAN= ascii.7 build.7 clocks.7 environ.7 ffs.7 hier.7 hostname.7 intro.7 \
mailaddr.7 operator.7 ports.7 security.7 tuning.7 firewall.7 \
sec-doc.7 sprog.7 style.perl.7
mailaddr.7 operator.7 ports.7 release.7 security.7 tuning.7 \
firewall.7 sec-doc.7 sprog.7 style.perl.7
MLINKS= intro.7 miscellaneous.7
.include <bsd.prog.mk>

299
share/man/man7/release.7 Normal file
View File

@ -0,0 +1,299 @@
.\" 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 .