1.\" Copyright (c) 2002 Murray Stokely <murray@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd January 14, 2012 28.Dt RELEASE 7 29.Os 30.Sh NAME 31.Nm release 32.Nd "release building infrastructure" 33.Sh DESCRIPTION 34.Fx 35provides a complete build environment suitable for users to make 36full releases of the 37.Fx 38operating system. 39All of the tools necessary to build a release are available from the 40.Fx 41source code repository in 42.Pa src/release . 43A complete release can actually be built with only a single command, 44including the creation of ISO images suitable for burning to CD-ROM, 45memory stick images, and an FTP install directory. 46This command is aptly named 47.Dq Li "make release" . 48.Pp 49For some users, it may be desirable to provide an absolutely clean 50build environment, with no local modifications to the source tree or to 51.Xr make.conf 5 , 52and with clean checkouts of specific versions of the doc, src, and ports 53trees. For this purpose, a script 54.Pq Pa src/release/generate-release.sh 55is provided to automate these checkouts and then execute 56.Dq Li "make release" 57in a clean 58.Xr chroot 8 . 59.Pp 60Before attempting to build a release, the user is expected to be 61familiar with the contents of 62.Xr build 7 , 63and should have experience upgrading systems from source. 64.Pp 65The release build process requires that 66.Pa /usr/obj 67be populated with the output of 68.Dq Li "make buildworld" 69and 70.Dq Li "make buildkernel" . 71This is necessary to provide the object files for the release or, when 72using 73.Pa generate-release.sh , 74so that the object files for a complete system can be installed into a clean 75.Xr chroot 8 76environment. In this second case, the built world must be capable of running 77on the build system (i.e. it must be for the same architecture and be 78compatible with the installed kernel). 79The release procedure on some architectures may also require that the 80.Xr md 4 81(memory disk) device driver be present in the kernel 82(either by being compiled in or available as a module). 83.Pp 84This document does not cover source code management, quality 85assurance, or other aspects of the release engineering process. 86.Sh CLEAN RELEASE GENERATION 87Official releases of FreeBSD are produced in a totally clean environment to 88ensure consistency between the versions of the src, ports, and doc trees 89and to avoid contamination from the host system (e.g. local patches, changes 90to 91.Xr make.conf 5 , 92etc.). This is accomplished using the wrapper script 93.Pa src/release/generate-release.sh . 94.Pp 95.Ic generate-release.sh 96svn-branch scratch-dir 97.Pp 98.Ic generate-release.sh 99calls 100.Dq Li "make installworld" 101to generate a 102.Xr chroot 8 103environment in 104.Ar scratch-dir . 105It then checks out the src tree specified by 106.Ar svn-branch 107using 108.Xr svn 1 109and (optionally) the ports and documentation trees using 110.Xr csup 1 111or 112.Xr cvs 1 . 113Once the various source trees have been obtained, it executes 114.Dq Li "make release" 115within the 116.Xr chroot 8 117environment and places the result in 118.Pa $scratch-dir/R . 119Note that because this uses a chroot, it cannot be used to cross-build 120.Fx 121release media. 122.Pp 123Environment variables: 124.Bl -tag -width ".Cm MAKE_FLAGS" 125.It Ev CVSUP_HOST 126The CVSUP server to use for the doc and ports trees. One of 127.Ev CVSUP_HOST 128or 129.Ev CVSROOT 130must be specified for ports and documentation to be included in the release. 131.It Ev CVSROOT 132The location of the 133.Fx 134CVS repository to use for the doc and ports trees. One of 135.Ev CVSUP_HOST 136or 137.Ev CVSROOT 138must be specified for ports and documentation to be included in the release. 139.It Ev CVS_TAG 140If the variable 141.Ev CVS_TAG 142is set, that tag will be used for CVS checkouts (doc and ports), otherwise 143.Ic generate-release.sh 144will use HEAD. 145.It Ev MAKE_FLAGS 146This environment variable can be set to pass flags (e.g. -j) to 147.Xr make 1 148when invoked by the script. 149.It Ev SVNROOT 150The location of the FreeBSD SVN source repository. Defaults to 151.Pa svn://svn.freebsd.org/base . 152.It Ev RELSTRING 153Optional base name for generated media images (e.g. FreeBSD-9.0-RC2-amd64). 154Defaults to the output of 155.Ic `uname -s`-`uname -r`-`uname -p` 156within the chroot. 157.El 158.Sh MAKEFILE TARGETS 159The release makefile 160.Pq Pa src/release/Makefile 161is fairly abstruse. 162Most developers will only be concerned with the 163.Cm release 164and 165.Cm install 166targets. 167.\" XXX: Some sort of introduction to this list? All the others have one. 168.Bl -tag -width ".Cm packagesystem" 169.It Cm release 170Meta-target to build all release media and distributions applicable to this 171platform. 172.It Cm install 173Copy all produced release media to 174.Pa ${DESTDIR} . 175.It Cm cdrom 176Builds installation CD-ROM images. On some systems, this may require that 177.Xr mkisofs 8 178be installed 179.Pq Pa sysutils/cdrtools 180and possibly that the 181.Xr md 4 182(memory disk) device driver be present in the kernel 183(either by being compiled in or available as a module). This target 184produces files called 185.Pa release.iso 186and 187.Pa bootonly.iso 188as its output. 189.It Cm memstick 190Builds an installation memory stick image named 191.Pa memstick . 192Not applicable on all platforms. Requires that the 193.Xr md 4 194(memory disk) device driver be present in the kernel 195(either by being compiled in or available as a module). 196.It Cm ftp 197Creates a directory named 198.Pa ftp 199containing the distribution files used in network installations 200and suitable for upload to an FTP mirror. 201.El 202.Pp 203Major subtargets called by targets above: 204.Bl -tag -width ".Cm packagesystem" 205.It Cm packagesystem 206Generates all the distribution archives (e.g. base, kernel, ports, doc) 207applicable on this platform. 208.It Cm system 209Builds a bootable installation system containing all the distribution files 210packaged by the 211.Cm packagesystem 212target, and suitable for imaging by the 213.Cm cdrom 214and 215.Cm memstick 216targets. 217.It Cm reldoc 218Builds the release documentation. 219This includes the release notes, 220hardware guide, and installation instructions. Other documentation (e.g. 221the Handbook) is built during the 222.Cm base.txz 223target invoked by 224.Cm packagesystem. 225.El 226.Sh ENVIRONMENT 227Optional variables: 228.Bl -tag -width ".Va TARGET_ARCH" 229.It Va WORLDDIR 230Location of a directory containing the src tree. By default, the directory 231above the one containing the makefile 232.Pq Pa src . 233.It Va PORTSDIR 234Location of a directory containing the ports tree. By default, 235.Pa /usr/ports . 236If it is unset or cannot be found, ports will not be included in the release. 237.It Va DOCDIR 238Location of a directory containing the doc tree. By default, 239.Pa /usr/doc . 240If it is unset or cannot be found, most documentation will not be included in 241the release; see 242.Ev NODOC 243below. 244.It Va NOPORTS 245If defined, the Ports Collection will be omitted from the release. 246.It Va NOSRC 247If set, do not include system source code in the release. 248.It Va NODOC 249If defined, the SGML-based documentation from the 250.Fx 251Documentation Project will not be built. 252However, the 253.Dq doc 254distribution will still be created with the minimal documentation set 255provided in 256.Pa src/share/doc . 257.It Va TARGET 258The target hardware platform. 259This is analogous to the 260.Dq Nm uname Fl m 261output. 262This is necessary to cross-build some target architectures. 263For example, cross-building for PC98 machines requires 264.Va TARGET_ARCH Ns = Ns Li i386 265and 266.Va TARGET Ns = Ns Li pc98 . 267If not set, 268.Va TARGET 269defaults to the current hardware platform. 270.It Va TARGET_ARCH 271The target machine processor architecture. 272This is analogous to the 273.Dq Nm uname Fl p 274output. 275Set this to cross-build for a different architecture. 276If not set, 277.Va TARGET_ARCH 278defaults to the current machine architecture, unless 279.Va TARGET 280is also set, in which case it defaults to the appropriate 281value for that platform. 282Typically, one only needs to set 283.Va TARGET . 284.El 285.Sh FILES 286.Bl -tag -compact 287.It Pa /usr/doc/Makefile 288.It Pa /usr/doc/share/mk/doc.project.mk 289.It Pa /usr/ports/Mk/bsd.port.mk 290.It Pa /usr/ports/Mk/bsd.sites.mk 291.It Pa /usr/share/examples/etc/make.conf 292.It Pa /usr/src/Makefile 293.It Pa /usr/src/Makefile.inc1 294.It Pa /usr/src/release/Makefile 295.It Pa /usr/src/release/generate-release.sh 296.El 297.Sh EXAMPLES 298The following sequence of commands can be used to build a 299.Dq "-CURRENT snapshot": 300.Bd -literal -offset indent 301cd /usr 302svn co svn://svn.freebsd.org/base/head src 303cd src 304make buildworld buildkernel 305cd release 306make release 307make install DESTDIR=/var/freebsd-snapshot 308.Ed 309.Pp 310After running these commands, all produced distribution files (tarballs 311for FTP, CD-ROM images, etc.) are available in the 312.Pa /var/freebsd-snapshot 313directory. 314.Pp 315The following sequence of commands can be used to build a 316.Dq "-CURRENT snapshot" 317in a clean environment, including ports and documentation: 318.Bd -literal -offset indent 319cd /usr/src/release 320export CVSUP_HOST=cvsupN.freebsd.org 321sh generate-release.sh head /local3/release 322.Ed 323.Pp 324After running these commands, all prepared release files are available in the 325.Pa /local3/release/R 326directory. 327.Sh SEE ALSO 328.Xr cc 1 , 329.Xr cvs 1 , 330.Xr install 1 , 331.Xr make 1 , 332.Xr svn 1 Pq Pa ports/devel/subversion-freebsd , 333.Xr uname 1 , 334.Xr md 4 , 335.Xr make.conf 5 , 336.Xr build 7 , 337.Xr ports 7 , 338.Xr chroot 8 , 339.Xr mtree 8 , 340.Xr sysctl 8 341.Rs 342.%T "FreeBSD Release Engineering" 343.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 344.Re 345.Rs 346.%T "FreeBSD Release Engineering of Third Party Packages" 347.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 348.Re 349.Rs 350.%T "FreeBSD Developers' Handbook" 351.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 352.Re 353.Sh HISTORY 354.Fx 3551.x 356used a manual checklist, compiled by 357.An Rod Grimes , 358to produce a release. 359Apart from being incomplete, the list put a lot of specific demands on 360available file systems and was quite torturous to execute. 361.Pp 362As part of the 363.Fx 2.0 364release engineering effort, significant 365effort was spent getting 366.Pa src/release/Makefile 367into a shape where it could at least automate most of the tediousness 368of building a release in a sterile environment. 369.Pp 370For the 371.Fx 9.0 372release, 373.Pa src/release/Makefile 374was overhauled and the wrapper script 375.Pa src/release/generate-release.sh 376introduced to support the introduction of a new installer. 377.Pp 378At near 1000 revisions spread over multiple branches, the 379.Xr cvs 1 380log of 381.Pa src/release/Makefile 382contains a vivid historical record of some 383of the hardships release engineers go through. 384.Sh AUTHORS 385.Pa src/release/Makefile 386was originally written by 387.An -nosplit 388.An Rod Grimes , 389.An Jordan Hubbard , 390and 391.An Poul-Henning Kamp . 392This manual page was written by 393.An Murray Stokely Aq murray@FreeBSD.org . 394