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

* Simplify the synopsis.

Browse Source 
* Remove trailing whitespace at EOL.
* Various grammar cleanups.
* Note that MAKE_ISOS is disabled by default.
* Use more descriptive mdoc markup.
* Use proper references for the online FDP documents.

Submitted by:	dd
This commit is contained in:
Murray Stokely 2002-03-13 09:54:31 +00:00
parent 49b144f286
commit 994c71f0c8
1 changed files with 88 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -29,24 +29,24 @@
.Os
.Sh NAME
.Nm release
.Nd information on the process used to build a complete system 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.
operating system.
All of the tools necessary to build a release are available from the
CVS repository in
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.
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
familiar with the contents of
.Xr build 7 ,
and should have experience upgrading systems from source with
.Dq make world .
@ -55,24 +55,25 @@ The release build process requires that
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
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.
.Xr md 4
(memory disk) device driver be present in the kernel
(either by being compiled in or loaded as a module).
.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)
.Pq Pa src/release/Makefile
is fairly abstruse.
Most developers will only be concerned with the
.Pa release
.Ar release
target.
.Bl -tag -width configure
.\" XXX: Some sort of introduction to this list? All the others have one.
.Bl -tag -width rerelease
.It Ar release
Uses
.Dq make installworld
@ -81,7 +82,7 @@ to install a clean system into a
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 .
.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.
@ -93,10 +94,10 @@ the intermediate output of the previous
.El
.Pp
Targets called by
.Dq make release .
.Bl -tag -width configure
.Dq make release :
.Bl -tag -width release.9
.It Ar release.1
Cleans out the
Cleans out the
.Pa ${CHROOTDIR}/R
directory and uses
.Xr mtree 1
@ -104,11 +105,15 @@ 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).
.\" XXX: This should either be "GENERIC kernel" (singular) or
.\" XXX: "GENERIC and <some other> kernels".
Makes and installs the
.Pa GENERIC
kernel.
.It Ar release.4
Uses
.Xr crunchgen 1
to build
to build
.Sq crunched
binaries to live on the installation floppies.
.It Ar release.5
@ -127,50 +132,61 @@ 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
Builds two ISO images (installation and
.Sq live
filesystem) from the CDROM release area.
filesystem) from the CDROM release area
(Disabled by default, see
.Pa MAKE_ISOS
below).
.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.
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 Ar doc.2
Builds the release documentation. This includes the release notes,
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
Variables that must be specified:
.Bl -tag -width RELEASETAG
.It Ev 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 don't 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 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
The name of the release to be built.
This is used to set the
.Dv 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.
The location of the
.Fx
CVS repository.
.It Ev RELEASETAG
The CVS tag corresponding to the release you would like to build.
The CVS tag corresponding to the release that is to be built.
If undefined, the release will be built from the HEAD of the CVS tree
(a
.Sq -CURRENT snapshot
).
.Sq -CURRENT snapshot ) .
.El
.Pp
Optional variables:
.Bl -tag -width configure
.Bl -tag -width RELEASEDISTFILES
.It Ev LOCAL_PATCHES
A patch file against
A patch file against
.Pa /usr/src
that will be applied in the
.Xr chroot 8
@ -179,18 +195,18 @@ environment before the release build begins.
Arguments for the
.Xr patch 1
command used to apply
.Pa LOCAL_PATCHES .
.Ev 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
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.
Documentation Project, this may speed up the release build considerably.
.It Ev NOPORTS
If set to
.Dq YES
@ -222,9 +238,9 @@ the source code will not be updated with
.It Pa /usr/src/release/${arch}/fixit_crunch.conf
.El
.Sh EXAMPLES
The following commands were used to build the
The following sequence of commands was used to build the
.Fx 4.5
release :
release:
.Bd -literal -offset indent
cd /usr
cvs co -rRELENG_4_5_0_RELEASE src
@ -237,11 +253,13 @@ make release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\
.Pp
After running these commands, a complete system suitable for FTP or
CDROM distribution is available in the
.Pa /local3/release/R/
.Pa /local3/release/R
directory.
.Pp
The following commands can be used to build a -CURRENT snapshot of a
locally modified source tree :
The following sequence of commands can be used to build a
.Sq -CURRENT snapshot
of a
locally modified source tree:
.Bd -literal -offset indent
cd /usr/src
cvs diff -u > /path/to/local.patch
@ -262,38 +280,40 @@ make release CHROOTDIR=/local3/release BUILDNAME=5.0-SNAPSHOT \\
.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
.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
.Pp
.Fx
1.x
used a manual checklist, compiled by Rod Grimes to produce a release.
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.
available filesystems and was quite torturous to execute.
.Pp
As part of the FreeBSD 2.0 release engineering effort, significant
effort was spent getting
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 cvs
log of src/release/Makefile contains a vivid historical record of some
With its almost 1000 revisions spread over multiple branches, the CVS
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 Rod Grimes, Jordan Hubbard, and Poul-Henning
Kamp.
This man page was written by
was originally written by Rod Grimes, Jordan Hubbard, and Poul-Henning Kamp.
This manual page was written by
.An Murray Stokely Aq murray@FreeBSD.org .