--- src/share/man/man7/release.7 2005/08/05 10:13:43 1.4 +++ src/share/man/man7/release.7 2006/03/10 10:42:41 1.5 @@ -1,31 +1,37 @@ -.\" Copyright (c) 2002 Murray Stokely -.\" All rights reserved. .\" +.\" Copyright (c) 2006 The DragonFly Project. All rights reserved. +.\" .\" 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 +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" 3. Neither the name of The DragonFly Project nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific, prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``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 +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS 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: src/share/man/man7/release.7,v 1.3.2.6 2003/04/12 20:42:30 murray Exp $ .\" $DragonFly$ .\" -.Dd March 12, 2002 +.Dd March 10, 2006 .Dt RELEASE 7 .Os .Sh NAME @@ -37,385 +43,117 @@ provides a complete build environment su full releases of the .Dx operating system. -All of the tools necessary to build a release are available from the +All of the tools necessary to build releases 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 CD-ROM, -installation floppies, and an FTP install directory. +.Pa src/nrelease . +A complete release (that is, a live CD) can actually be built with +only a single command. This command is aptly named -.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 Li "make world" . -The release build process requires that -.Pa /usr/obj -be populated with the output of -.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 -environment. -The release procedure also requires that the -.Xr vn 4 -(vnode disk) device driver be present in the kernel -(either by being compiled in or loaded as a module). +.Dq Li "make release" +(or +.Dq Li "make installer_release" , +see below). .Pp This document does not cover source code management, quality assurance, or other aspects of the release engineering process. .Sh TARGETS -The release makefile -.Pq Pa src/release/Makefile -is fairly abstruse. -Most developers will only be concerned with the +The release Makefile +.Pq Pa src/nrelease/Makefile +defines a number of targets which are roughly modeled after the +targets used for building the system. +.Bl -tag -width ".Cm realquickrel" +.It Cm release +Builds a vanilla live CD. +.It Cm quickrel +Same as .Cm release +but uses the +.Cm quickworld target. -.\" XXX: Some sort of introduction to this list? All the others have one. -.Bl -tag -width ".Cm rerelease" -.It Cm release -Uses -.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 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. -.Pp -This target must be built as root with the -.Va kern.securelevel -sysctl set to -1 -.Pq "the default". -.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 Li "make release" . -.It Cm floppies -Generate a new set of boot floppies. -This will call the -.Cm release.5 , -.Cm release.9 , -and -.Cm release.10 -targets to re-generate the floppy images of a previous -.Dq Li "make release" . -This is most often used to build custom boot floppies. -.El -.Pp -Targets called by -.Dq Li "make release" : -.Bl -tag -width ".Cm release.10" -.It Cm release.1 -Cleans out the -.Pa ${CHROOTDIR}/R -directory and uses -.Xr mtree 8 -to build the directory hierarchy for the system. -.It Cm release.2 -Installs the system into the distribution directories. -.It Cm release.3 -Builds and installs -.Dq crypto , -.Dq krb4 -and -.Dq krb5 -distributions. -.It Cm release.4 -.\" XXX: We build more than one kernel. We build a stripped down -.\" kernel for the boot media in addition to a full GENERIC kernel. -Makes and installs the -.Pa GENERIC -kernel. -.It Cm release.5 -Uses -.Xr crunchgen 1 -to build -.Dq crunched -binaries to live on the installation floppies. -.It Cm release.6 -Builds synthetic distributions, and cleans up the previously built -distribution trees. -.It Cm release.7 -Creates tarballs of the assembled distribution trees. -.It Cm release.8 -Makes source distributions. -.It Cm release.9 -Creates the boot and MFS root floppies. -.It Cm release.10 -Creates the fixit floppy. -.It Cm ftp.1 -Sets up a suitable area for FTP installations in -.Pa ${CHROOTDIR}/R/ftp . -.It Cm cdrom.1 -Sets up a suitable area to build CD-ROM images in -.Pa ${CHROOTDIR}/R/cdrom . -.It Cm iso.1 -Builds two ISO images (installation and -.Dq live -filesystem) from the CD-ROM release area -(disabled by default, see -.Va MAKE_ISOS -below). -.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 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 ".Va RELEASETAG" -.It Va 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 Va BUILDNAME -The name of the release to be built. -This is used to set the -.Va RELEASE -value in -.Pa sys/conf/newvers.sh , -which affects the output of -.Xr uname 1 . -.It Va CVSROOT -The location of the -.Dx -CVS repository. -This path name is referenced to the real system root, -.Em not -the root of the -.Xr chroot 8 -directory tree. -.It Va RELEASETAG -The CVS tag corresponding to the release that is to be built. -If undefined, the release will be built from the -.Dv HEAD -of the CVS tree -(a -.Dq "-CURRENT snapshot" ) . +.It Cm realquickrel +Same as +.Cm release +but uses the +.Cm realquickworld +target. +.It Cm clean +Removes the ISO root directory and object files. +.It Cm realclean +Same as +.Cm clean +but also removes external packages. .El .Pp -Optional variables: -.Bl -tag -width ".Va RELEASEDISTFILES" -.It Va CVSCMDARGS -Additional arguments for -.Xr cvs 1 -.Ic checkout +The +.Cm quickrel and -.Ic update -commands. -For example, setting this variable to -.Dq Li "-D '01/01/2002 00:00:00 GMT'" -for -.Dq Li "make release" -or -.Dq Li "make rerelease" -will ask -.Xr cvs 1 -to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively. -.It Va 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 Va PATCH_FLAGS -Arguments for the -.Xr patch 1 -command used to apply -.Va LOCAL_PATCHES -patch file. -.It Va LOCAL_SCRIPT -A script that will be run in the -.Xr chroot 8 -environment immediately after any local patches are applied. -.It Va MAKE_ISOS -If defined, bootable ISO CD-ROM images will be created from the -contents of the CD-ROM stage directory. -.It Va NODOC -If set to -.Dq Li YES , -the SGML-based documentation from the -.Fx -Documentation Project will not be built. -However, the -.Dq doc -distribution will still be created with the minimal documentation set -provided in -.Pa src/share/doc . -.It Va NOPORTS -If set to -.Dq Li YES -then the Ports Collection will be omitted from the release. -.It Va NOPORTREADMES -If defined, readme files will not be created for each individual port -in the Ports Collection. -The default behavior is for +.Cm realquickrel +targets will only work if a full .Dq Li "make release" -to run -.Dq Li "make readmes" -from -.Pa ${CHROOTDIR}/usr/ports , -which can be a very time consuming operation. -.It Va 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 Va RELEASENOUPDATE -If this variable is defined for -.Dq Li "make rerelease" , -the source code will not be updated with -.Dq Li "cvs update" . -.It Va TARGET_ARCH -The target machine processor architecture. -This is analogous to the -.Dq Nm uname Fl p -output. -Set this to cross-build for a different architecture. -.It Va TARGET -The target hardware platform. -This is analogous to the -.Dq Nm uname Fl m -output. -This is necessary to cross-build some target architectures. -For example, cross-building for PC98 machines requires -.Va TARGET_ARCH Ns = Ns Li i386 +has been done before. +For a description of the corresponding build targets, see +.Xr build 7 . +.Pp +The +.Cm release , +.Cm quickrel and -.Va TARGET Ns = Ns Li pc98 . -.El +.Cm realquickrel +targets all have corresponding targets with +.Dq Li installer_ +prefixed (e.g., +.Cm installer_release ) +which cause the BSD installer from +.Pa http://www.bsdinstaller.org +to be added to the resulting ISO image. +.Pp +During the process of rolling a release a check is performed to find +out if a number of external packages to be put on the CD exist on +your system. +If they cannot be found, the release process will stop and give +proper commands for downloading and setting up these packges. .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}/boot_crunch.conf -.It Pa /usr/src/release/${arch}/fixit_crunch.conf +.It Pa src/Makefile +.It Pa src/Makefile.inc1 +.It Pa src/nrelease/Makefile .El .Sh EXAMPLES -The following sequence of commands was used to build the -.Fx 4.5 -release: +The following sequence of commands is used to build a standard +.Dx 1.4 +installation CD image (assuming that a local CVS repository is +available): .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 +cvs co -rDragonFly_RELEASE_1_4 src +cd src/nrelease +make installer_release .Ed .Pp -After running these commands, a complete system suitable for FTP or -CD-ROM distribution is available in the -.Pa /local3/release/R +After running these commands, the image will be available in the +.Pa src/release directory. -.Pp -The following sequence of commands can be used to build a -.Dq "-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-CURRENT \\ - 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 patch 1 , -.Xr uname 1 , -.Xr vn 4 , .Xr make.conf 5 , -.Xr build 7 , -.Xr ports 7 , -.Xr chroot 8 , -.Xr mtree 8 , -.Xr sysctl 8 -.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 +.Xr build 7 .Sh HISTORY -.Fx -1.x -used a manual checklist, compiled by -.An 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 -.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 -.Xr cvs 1 -log of -.Pa src/release/Makefile -contains a vivid historical record of some -of the hardships release engineers go through. +.Pa src/nrelease +was added in +.Dx 1.0 +to implement the idea of a +.Dq "live CD" . .Sh AUTHORS -.Pa src/release/Makefile -was originally written by .An -nosplit -.An Rod Grimes , -.An Jordan Hubbard , -and -.An Poul-Henning Kamp . +The +.Nm +infrastructure was written by +.An Matthew Dillon . This manual page was written by -.An Murray Stokely Aq murray@FreeBSD.org . +.An Sascha Wildner . .Sh BUGS -Infrastructure changes are occassionally made to the FreeBSD -documentation set in such a way that release builds on security -branches can fail. -To work around this, release builds can be made to checkout the -documentation from the last fully supported release of FreeBSD. -For example: -.Bd -literal -offset indent -make release RELEASETAG=RELENG_4_5 DOCRELEASETAG=RELEASE_4_5_0 ... -.Ed +There are more targets and variables in +.Pa src/nrelease/Makefile +that should be documented.