* Simplify the synopsis.
* 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
parent
49b144f286
commit
994c71f0c8
@ -29,13 +29,13 @@
|
||||
.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
|
||||
.Pa src/release .
|
||||
@ -46,7 +46,7 @@ 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 .
|
||||
@ -59,20 +59,21 @@ 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
|
||||
@ -93,8 +94,8 @@ 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
|
||||
.Pa ${CHROOTDIR}/R
|
||||
@ -104,7 +105,11 @@ 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
|
||||
@ -129,46 +134,57 @@ 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.
|
||||
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
|
||||
.Pa /usr/src
|
||||
@ -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,7 +238,7 @@ 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:
|
||||
.Bd -literal -offset indent
|
||||
@ -237,10 +253,12 @@ 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
|
||||
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
|
||||
@ -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.
|
||||
.Pp
|
||||
As part of the FreeBSD 2.0 release engineering effort, significant
|
||||
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 .
|
||||
|
||||
Loading…
Reference in New Issue
Block a user