diff options
Diffstat (limited to 'share/man/man7/release.7')
| -rw-r--r-- | share/man/man7/release.7 | 574 |
1 files changed, 574 insertions, 0 deletions
diff --git a/share/man/man7/release.7 b/share/man/man7/release.7 new file mode 100644 index 0000000..8e512c2 --- /dev/null +++ b/share/man/man7/release.7 @@ -0,0 +1,574 @@ +.\" 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 +.\" 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 August 17, 2009 +.Dt RELEASE 7 +.Os +.Sh NAME +.Nm 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. +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 CD-ROM, +installation floppies, and an FTP install directory. +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. +The release build process requires that +.Pa /usr/obj +be populated with the output of +a native +.Dq Li "make buildworld" +compiled from sources matching the currently running kernel. +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 md 4 +(memory disk) device driver be present in the kernel +(either by being compiled in or available as a module). +.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 +.Cm release +target. +.\" XXX: Some sort of introduction to this list? All the others have one. +.Bl -tag -width ".Cm package-split" +.It Cm release +Uses +.Dq Li "make installworld" +to install a clean system into a +.Xr chroot 8 +environment on the file system. +Checks out the specified version of the source code and then rebuilds +the entire system in the clean environment with +.Dq Li "make buildworld" . +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 (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 and fixit floppies. +This will call the +.Cm release.4 , +.Cm release.8 , +.Cm floppies.1 , +.Cm floppies.2 , +and +.Cm floppies.3 +targets to re-generate the floppy images of a previous +.Dq Li "make release" . +This is most often used to build custom boot floppies. +.It Cm package-split +Generates the portions of the disc 1 and disc 2 images related to packages. +It uses the list of desired packages from the +.Pa src/release/scripts/package-split.py +script to pull packages out of a package build provided by the ports team +and organize them appropriately. +The resulting directory can then be passed to +.Dq Li "make release" +via the +.Va CD_PACKAGE_TREE +variable to populate the ISO images built by the +.Cm iso.1 +target with the correct package related bits. +.El +.Pp +Targets called by +.Dq Li "make release" : +.Bl -tag -width ".Cm fetch-distfiles" +.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 +Makes and installs the +.Pa GENERIC +kernel as well as any other kernels listed in +.Va KERNELS . +.It Cm release.4 +Uses +.Xr crunchgen 1 +to build +.Dq crunched +binaries to live on the installation floppies. +.It Cm release.5 +Builds synthetic distributions, and cleans up the previously built +distribution trees. +.It Cm release.6 +Creates tarballs of the assembled distribution trees. +.It Cm release.7 +Makes source distributions. +.It Cm release.8 +Creates the MFS root file systems. +.It Cm floppies.1 +Creates the boot and kernel floppies. +.It Cm floppies.2 +Creates the fixit floppy. +.It Cm floppies.3 +Finalizes the +.Pa ${CHROOTDIR}/R/ftp/stage/floppies +staging directory. +.It Cm ftp.1 +Sets up a suitable area for FTP installations in +.Pa ${CHROOTDIR}/R/ftp . +.It Cm cdrom.1 +Create the layout for the live file system CD-ROM image in +.Pa ${CHROOTDIR}/R/cdrom . +.It Cm cdrom.2 +Create the layout for the first and second CD-ROM images. +.It Cm cdrom.3 +Create the layout for the boot-only CD-ROM image and the boot-only UFS +miniroot image. +.It Cm iso.1 +Builds ISO images (installation and +.Dq live +file system) from the CD-ROM release area +(disabled by default, see +.Va MAKE_ISOS +below). +.It Cm fetch-distfiles +Fetches distfiles needed during the release build that are not already in +.Va RELEASEDISTFILES . +.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 CHROOTDIR" +.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 do not 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 file system should have at least 3.2 gigabytes of free space on the +i386 architecture. +.It Va CVSROOT +The location of the +.Fx +CVS repository. +This path name is in reference to the real system root, +.Em not +the root of the +.Xr chroot 8 +directory tree. +.El +.Pp +Optional variables: +.Bl -tag -width ".Va NO_PREFETCHDISTFILES" +.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 . +If not set, a name with the timestamp and the +.Dq Li -SNAP +suffix will be generated. +.It Va CD_PACKAGE_TREE +A directory containing extra bits for the first and second CD-ROM images. +The extra files for the first disc should be in +.Pa ${CD_PACKAGE_TREE}/disc1 +and the extra files for the second disc should be in +.Pa ${CD_PACKAGE_TREE}/disc2 . +Typically, this variable will be set to the output directory of an earlier +invocation of the +.Cm package-split +target. +.It Va CVSARGS +Additional arguments for +.Xr cvs 1 +that come before the subcommands such as +.Dq Li "-qR" . +.It Va CVSCMDARGS +Additional arguments for +.Xr cvs 1 +.Ic checkout +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 DOC_LANG +The list of languages and encodings the SGML-based documentation +should be built for. +If not set, the documentation is built for all available languages. +.It Va DOCRELEASETAG +The CVS tag to use when checking out the documentation tree. +Usually, +the head of the documentation tree is used by default. +If +.Va RELEASETAG +specifies a release tag, +then the associated release version is used as the default instead. +.It Va EXTLOCALDIR +The directory that will be copied to +.Pa ${CHROOTDIR}/usr/local . +.It Va EXTSRCDIR +The directory specified by this variable will be copied into +.Pa ${CHROOTDIR}/usr/src +instead of that directory being populated by a CVS checkout. +For +.Dq Li "rerelease" , +this will NOT be copied; cvs update will be used instead. +.It Va EXTDOCDIR +The directory specified by this variable will be copied into +.Pa ${CHROOTDIR}/usr/doc . +For +.Dq Li "rerelease" , +this will NOT be copied again. +.It Va EXTPORTSDIR +The directory specified by this variable will be copied into +.Pa ${CHROOTDIR}/usr/ports . +For +.Dq Li "rerelease" , +this will do NOTHING. +.It Va KERNEL_FLAGS +The contents of this variable are passed to +.Xr make 1 +when building kernels during the release build. +For example, setting this variable to +.Dq Li "-j 4" +will instruct +.Xr make 1 +to execute up to four processes at a time. +.It Va KERNELS +Specifies a list of additional kernel configurations to compile and +install into the +.Dq base +distribution. +Each kernel is installed into +.Pa /boot/<config> +so that it can be booted from the loader via +.Dq Li "boot <config>" . +.It Va LOCAL_PATCHES +Patch files 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_DVD +If defined, build a bootable ISO DVD image in the CD-ROM +stage directory. +This option may not be available for all architectures. +.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 NOCDROM +If defined, the CD-ROM stage directories will not be created. +.It Va NODOC +If defined, 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 NO_FLOPPIES +If defined, no boot and fixit floppy disk images will be created (for those +platforms supporting them). +.It Va NOPORTS +If defined, the Ports Collection will be omitted from the release. +.It Va PORTSRELEASETAG +The CVS tag to use when checking out the ports tree. +Usually, +the head of the ports tree is used by default. +If +.Va RELEASETAG +specifies a release tag, +then the associated release version is used as the default instead. +.It Va NO_PREFETCHDISTFILES +If this variable is defined, +then distfiles needed during the release build will not be downloaded prior to +entering the +.Xr chroot 8 +environment. +Note that if +.Va NO_PREFETCHDISTFILES +is not set, +the fetching is done after any distfiles are obtained via +.Va RELEASEDISTFILES . +.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 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 Va SEPARATE_LIVEFS +Store the live file system on its own CD-ROM image rather than placing it on +the first disc. +.It Va SVNCMDARGS +Additional arguments for svn +.Ic checkout +and +.Ic switch +commands. +.It Va SVNROOT +The location of the FreeBSD SVN source repository. +If this variable is set, +then the source tree will be extracted using Subversion rather than +CVS. +.It Va SVNBRANCH +The branch to check out from a SVN source repository. +It is specified as a path such as +.Pa head +or +.Pa stable/7 . +If this variable is not set, +then the branch that corresponds to the current value of +.Va RELEASETAG +will be used. +If neither +.Va SVNBRANCH +nor +.Va RELEASETAG +are set, +then the +.Pa head +branch will be used. +.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 +and +.Va TARGET Ns = Ns Li pc98 . +.It Va WORLDDIR +The directory where +.Dq Li "make buildworld" +was run; defaults to +.Pa ${.CURDIR}/.. +which usually points to +.Pa /usr/src . +.It Va WORLD_FLAGS +The contents of this variable are passed to +.Xr make 1 +when building world during the release build. +For example, setting this variable to +.Dq Li "-j 4" +will instruct +.Xr make 1 +to execute up to four processes at a time. +.El +.Sh FILES +.Bl -tag -compact +.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 +.El +.Sh EXAMPLES +The following sequence of commands was used to build the +.Fx 4.9 +release: +.Bd -literal -offset indent +cd /usr +cvs co -rRELENG_4_9_0_RELEASE src +cd src +make buildworld +cd release +make release CHROOTDIR=/local3/release BUILDNAME=4.9-RELEASE \\ + CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_9_0_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 +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=6.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 svn 1 Pq Pa ports/devel/subversion-freebsd , +.Xr uname 1 , +.Xr md 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" +.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ +.Re +.Rs +.%T "FreeBSD Release Engineering of Third Party Packages" +.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ +.Re +.Rs +.%T "FreeBSD Developers' Handbook" +.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ +.Re +.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 file systems 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 +At near 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 +.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 . +.Sh BUGS +Infrastructure changes are occasionally made to the +.Fx +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 +.Fx . +For example: +.Pp +.Dl "make release RELEASETAG=RELENG_4_9 DOCRELEASETAG=RELEASE_4_9_0 ..." |
