diff --git a/share/man/man7/release.7 b/share/man/man7/release.7 index 0362e1d8d16d..ccfa851323b8 100644 --- a/share/man/man7/release.7 +++ b/share/man/man7/release.7 @@ -1,5 +1,5 @@ -.\" Copyright (c) 2002 -.\" Murray Stokely <murray@FreeBSD.org> +.\" 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 @@ -29,7 +29,7 @@ .Os .Sh NAME .Nm release -.Nd release building infrastructure +.Nd "release building infrastructure" .Sh DESCRIPTION .Fx provides a complete build environment suitable for users to make @@ -43,17 +43,17 @@ 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 . +.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 with -.Dq make world . +.Dq Li "make world" . The release build process requires that .Pa /usr/obj be populated with the output of -.Dq make buildworld . +.Dq Li "make buildworld" . This is necessary so that the object files for a complete system can be installed into a clean .Xr chroot 8 @@ -70,89 +70,89 @@ The release makefile .Pq Pa src/release/Makefile is fairly abstruse. Most developers will only be concerned with the -.Ar release +.Cm release target. .\" XXX: Some sort of introduction to this list? All the others have one. -.Bl -tag -width rerelease -.It Ar release +.Bl -tag -width ".Cm rerelease" +.It Cm release Uses -.Dq make installworld +.Dq Li "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 . +.Dq Li "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 +.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 make release . +.Dq Li "make release" . .El .Pp Targets called by -.Dq make release : -.Bl -tag -width release.9 -.It Ar release.1 +.Dq Li "make release" : +.Bl -tag -width ".Cm release.9" +.It Cm release.1 Cleans out the .Pa ${CHROOTDIR}/R directory and uses -.Xr mtree 1 +.Xr mtree 8 to build the directory hierarchy for the system. -.It Ar release.2 +.It Cm release.2 Installs the system into the distribution directories. -.It Ar release.3 +.It Cm release.3 .\" 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 +.It Cm release.4 Uses .Xr crunchgen 1 to build -.Sq crunched +.Dq crunched binaries to live on the installation floppies. -.It Ar release.5 +.It Cm release.5 Builds synthetic distributions, and cleans up the previously built distribution trees. -.It Ar release.6 +.It Cm release.6 Creates tarballs of the assembled distribution trees. -.It Ar release.7 +.It Cm release.7 Makes source distributions. -.It Ar release.8 +.It Cm release.8 Creates the boot and MFS root floppies. -.It Ar release.9 +.It Cm release.9 Creates the fixit floppy. -.It Ar ftp.1 +.It Cm ftp.1 Sets up a suitable area for FTP installations. -.It Ar cdrom.1 +.It Cm cdrom.1 Sets up a suitable area to build CDROM images. -.It Ar iso.1 +.It Cm iso.1 Builds two ISO images (installation and -.Sq live +.Dq live filesystem) from the CDROM release area (Disabled by default, see .Pa MAKE_ISOS below). -.It Ar doc.1 +.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 Ar doc.2 +.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 RELEASETAG +.Bl -tag -width ".Va RELEASETAG" .It Ev CHROOTDIR The directory to be used as the .Xr chroot 8 @@ -178,13 +178,15 @@ The location of the CVS repository. .It Ev RELEASETAG 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 +If undefined, the release will be built from the +.Dv HEAD +of the CVS tree (a -.Sq -CURRENT snapshot ) . +.Dq -CURRENT snapshot ) . .El .Pp Optional variables: -.Bl -tag -width RELEASEDISTFILES +.Bl -tag -width ".Ev RELEASEDISTFILES" .It Ev LOCAL_PATCHES A patch file against .Pa /usr/src @@ -195,13 +197,14 @@ environment before the release build begins. Arguments for the .Xr patch 1 command used to apply -.Ev LOCAL_PATCHES . +.Ev LOCAL_PATCHES +patch file. .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 +.Dq Li YES then the documentation will not be built. Due to the SGML-based toolchain and multiple languages supported by the @@ -209,7 +212,7 @@ toolchain and multiple languages supported by the Documentation Project, this may speed up the release build considerably. .It Ev NOPORTS If set to -.Dq YES +.Dq Li 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 @@ -218,9 +221,9 @@ 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 , +.Dq Li "make rerelease" , the source code will not be updated with -.Dq cvs up . +.Dq Li "cvs update" . .El .Sh FILES .Bl -tag -compact @@ -257,7 +260,7 @@ CDROM distribution is available in the directory. .Pp The following sequence of commands can be used to build a -.Sq -CURRENT snapshot +.Dq -CURRENT snapshot of a locally modified source tree: .Bd -literal -offset indent @@ -266,20 +269,22 @@ 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 + 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 mtree 1 , .Xr patch 1 , .Xr uname 1 , +.Xr md 4 , .Xr make.conf 5 , .Xr build 7 , .Xr ports 7 , -.Xr chroot 8 +.Xr chroot 8 , +.Xr mtree 8 .Rs .%T FreeBSD Release Engineering .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ @@ -307,13 +312,19 @@ effort was spent getting 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 +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 Rod Grimes, Jordan Hubbard, and Poul-Henning Kamp. +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 .