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