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 September 16, 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 . 109Once the various source trees have been obtained, it executes 110.Dq Li "make release" 111within the 112.Xr chroot 8 113environment and places the result in 114.Pa $scratch-dir/R . 115Note that because this uses a chroot, it cannot be used to cross-build 116.Fx 117release media. 118.Pp 119Environment variables: 120.Bl -tag -width ".Cm MAKE_FLAGS" 121.It Ev MAKE_FLAGS 122This environment variable can be set to pass flags (e.g. -j) to 123.Xr make 1 124when invoked by the script. 125.It Ev SVNROOT 126The location of the FreeBSD SVN source, doc, and ports repositories. 127Defaults to 128.Pa svn://svn.freebsd.org/base 129for the source tree, 130.Pa svn://svn.freebsd.org/ports/head 131for the Ports Collection, and 132.Pa svn://svn.freebsd.org/doc/head 133for the Documentation Project source. 134.It Ev RELSTRING 135Optional base name for generated media images (e.g. FreeBSD-9.0-RC2-amd64). 136Defaults to the output of 137.Ic `uname -s`-`uname -r`-`uname -p` 138within the chroot. 139.El 140.Sh MAKEFILE TARGETS 141The release makefile 142.Pq Pa src/release/Makefile 143is fairly abstruse. 144Most developers will only be concerned with the 145.Cm release 146and 147.Cm install 148targets. 149.\" XXX: Some sort of introduction to this list? All the others have one. 150.Bl -tag -width ".Cm packagesystem" 151.It Cm release 152Meta-target to build all release media and distributions applicable to this 153platform. 154.It Cm install 155Copy all produced release media to 156.Pa ${DESTDIR} . 157.It Cm cdrom 158Builds installation CD-ROM images. On some systems, this may require that 159.Xr mkisofs 8 160be installed 161.Pq Pa sysutils/cdrtools 162and possibly that the 163.Xr md 4 164(memory disk) device driver be present in the kernel 165(either by being compiled in or available as a module). This target 166produces files called 167.Pa release.iso 168and 169.Pa bootonly.iso 170as its output. 171.It Cm memstick 172Builds an installation memory stick image named 173.Pa memstick . 174Not applicable on all platforms. Requires that the 175.Xr md 4 176(memory disk) device driver be present in the kernel 177(either by being compiled in or available as a module). 178.It Cm ftp 179Creates a directory named 180.Pa ftp 181containing the distribution files used in network installations 182and suitable for upload to an FTP mirror. 183.El 184.Pp 185Major subtargets called by targets above: 186.Bl -tag -width ".Cm packagesystem" 187.It Cm packagesystem 188Generates all the distribution archives (e.g. base, kernel, ports, doc) 189applicable on this platform. 190.It Cm system 191Builds a bootable installation system containing all the distribution files 192packaged by the 193.Cm packagesystem 194target, and suitable for imaging by the 195.Cm cdrom 196and 197.Cm memstick 198targets. 199.It Cm reldoc 200Builds the release documentation. 201This includes the release notes, 202hardware guide, and installation instructions. Other documentation (e.g. 203the Handbook) is built during the 204.Cm base.txz 205target invoked by 206.Cm packagesystem . 207.El 208.Sh ENVIRONMENT 209Optional variables: 210.Bl -tag -width ".Va TARGET_ARCH" 211.It Va WORLDDIR 212Location of a directory containing the src tree. By default, the directory 213above the one containing the makefile 214.Pq Pa src . 215.It Va PORTSDIR 216Location of a directory containing the ports tree. By default, 217.Pa /usr/ports . 218If it is unset or cannot be found, ports will not be included in the release. 219.It Va DOCDIR 220Location of a directory containing the doc tree. By default, 221.Pa /usr/doc . 222If it is unset or cannot be found, most documentation will not be included in 223the release; see 224.Ev NODOC 225below. 226.It Va NOPORTS 227If defined, the Ports Collection will be omitted from the release. 228.It Va NOSRC 229If set, do not include system source code in the release. 230.It Va NODOC 231If defined, the XML-based documentation from the 232.Fx 233Documentation Project will not be built. 234However, the 235.Dq doc 236distribution will still be created with the minimal documentation set 237provided in 238.Pa src/share/doc . 239.It Va TARGET 240The target hardware platform. 241This is analogous to the 242.Dq Nm uname Fl m 243output. 244This is necessary to cross-build some target architectures. 245For example, cross-building for PC98 machines requires 246.Va TARGET_ARCH Ns = Ns Li i386 247and 248.Va TARGET Ns = Ns Li pc98 . 249If not set, 250.Va TARGET 251defaults to the current hardware platform. 252.It Va TARGET_ARCH 253The target machine processor architecture. 254This is analogous to the 255.Dq Nm uname Fl p 256output. 257Set this to cross-build for a different architecture. 258If not set, 259.Va TARGET_ARCH 260defaults to the current machine architecture, unless 261.Va TARGET 262is also set, in which case it defaults to the appropriate 263value for that platform. 264Typically, one only needs to set 265.Va TARGET . 266.El 267.Sh FILES 268.Bl -tag -compact -width Pa 269.It Pa /usr/doc/Makefile 270.It Pa /usr/doc/share/mk/doc.project.mk 271.It Pa /usr/ports/Mk/bsd.port.mk 272.It Pa /usr/ports/Mk/bsd.sites.mk 273.It Pa /usr/share/examples/etc/make.conf 274.It Pa /usr/src/Makefile 275.It Pa /usr/src/Makefile.inc1 276.It Pa /usr/src/release/Makefile 277.It Pa /usr/src/release/generate-release.sh 278.El 279.Sh EXAMPLES 280The following sequence of commands can be used to build a 281.Dq "-CURRENT snapshot": 282.Bd -literal -offset indent 283cd /usr 284svn co svn://svn.freebsd.org/base/head src 285cd src 286make buildworld buildkernel 287cd release 288make release 289make install DESTDIR=/var/freebsd-snapshot 290.Ed 291.Pp 292After running these commands, all produced distribution files (tarballs 293for FTP, CD-ROM images, etc.) are available in the 294.Pa /var/freebsd-snapshot 295directory. 296.Pp 297The following sequence of commands can be used to build a 298.Dq "-CURRENT snapshot" 299in a clean environment, including ports and documentation: 300.Bd -literal -offset indent 301cd /usr/src/release 302export SVNROOT=svn://svn.freebsd.org/base 303sh generate-release.sh head /local3/release 304.Ed 305.Pp 306After running these commands, all prepared release files are available in the 307.Pa /local3/release/R 308directory. 309.Sh SEE ALSO 310.Xr cc 1 , 311.Xr install 1 , 312.Xr make 1 , 313.Xr svn 1 Pq Pa ports/devel/subversion-freebsd , 314.Xr uname 1 , 315.Xr md 4 , 316.Xr make.conf 5 , 317.Xr build 7 , 318.Xr ports 7 , 319.Xr chroot 8 , 320.Xr mtree 8 , 321.Xr sysctl 8 322.Rs 323.%T "FreeBSD Release Engineering" 324.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 325.Re 326.Rs 327.%T "FreeBSD Release Engineering of Third Party Packages" 328.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 329.Re 330.Rs 331.%T "FreeBSD Developers' Handbook" 332.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 333.Re 334.Sh HISTORY 335.Fx 3361.x 337used a manual checklist, compiled by 338.An Rod Grimes , 339to produce a release. 340Apart from being incomplete, the list put a lot of specific demands on 341available file systems and was quite torturous to execute. 342.Pp 343As part of the 344.Fx 2.0 345release engineering effort, significant 346effort was spent getting 347.Pa src/release/Makefile 348into a shape where it could at least automate most of the tediousness 349of building a release in a sterile environment. 350.Pp 351For the 352.Fx 9.0 353release, 354.Pa src/release/Makefile 355was overhauled and the wrapper script 356.Pa src/release/generate-release.sh 357introduced to support the introduction of a new installer. 358.Pp 359At near 1000 revisions spread over multiple branches, the 360.Xr svn 1 361log of 362.Pa src/release/Makefile 363contains a vivid historical record of some 364of the hardships release engineers go through. 365.Sh AUTHORS 366.Pa src/release/Makefile 367was originally written by 368.An -nosplit 369.An Rod Grimes , 370.An Jordan Hubbard , 371and 372.An Poul-Henning Kamp . 373This manual page was written by 374.An Murray Stokely Aq murray@FreeBSD.org . 375