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 November 18, 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. 54For this purpose, a script 55.Pq Pa src/release/release.sh 56is provided to automate these checkouts and then execute 57.Dq Li "make release" 58in a clean 59.Xr chroot 8 . 60.Pp 61Before attempting to build a release, the user is expected to be 62familiar with the contents of 63.Xr build 7 , 64and should have experience upgrading systems from source. 65.Pp 66The release build process requires that 67.Pa /usr/obj 68be populated with the output of 69.Dq Li "make buildworld" 70and 71.Dq Li "make buildkernel" . 72This is necessary to provide the object files for the release or, when 73using 74.Pa release.sh , 75so that the object files for a complete system can be installed into a clean 76.Xr chroot 8 77environment. 78.Pp 79If the target release build is for a different architecture or machine type, 80the 81.Va TARGET 82and 83.Va TARGET_ARCH 84variables must be used. 85See the supported 86.Fa release.conf 87variables for more information. 88.Pp 89The release procedure on some architectures may also require that the 90.Xr md 4 91(memory disk) device driver be present in the kernel 92.Pq either by being compiled in or available as a module . 93.Pp 94This document does not cover source code management, quality 95assurance, or other aspects of the release engineering process. 96.Sh CLEAN RELEASE GENERATION 97Official releases of 98.Fx 99are produced in a totally clean environment to 100ensure consistency between the versions of the src, ports, and doc trees 101and to avoid contamination from the host system 102.Po such as local patches, changes 103to 104.Xr make.conf 5 , 105etc. 106.Pc . 107This is accomplished using the wrapper script 108.Pa src/release/release.sh . 109.Pp 110.Ic release.sh 111.Op Fl c Ar release.conf 112.Pp 113.Ic release.sh 114checks out the 115.Li src/ , 116.Li ports/ , 117and 118.Li doc/ 119trees to 120.Va CHROOTDIR , 121then calls 122.Dq Li "make buildworld" 123and 124.Dq Li "make installworld" 125to generate a 126.Xr chroot 8 127environment. 128Next, 129.Dq Li "make release" 130is run within the 131.Xr chroot 8 132environment and places the result in 133.Pa $CHROOTDIR/R . 134.Pp 135The optional 136.Fa release.conf 137configuration file supports the following variables: 138.Bl -tag -width Ev 139.It Va CHROOTDIR 140The directory within which the release will be built. 141.It Va SVNROOT 142The 143.Xr svn 1 144host used to check out the various trees. 145Defaults to 146.Pa svn://svn.FreeeBSD.org . 147.It Va SRCBRANCH 148The 149.Li src/ 150branch to use. 151Defaults to 152.Va head/@rHEAD . 153.It Va DOCBRANCH 154The 155.Li doc/ 156branch to use. 157Defaults to 158.Va head/@rHEAD . 159.It Va PORTBRANCH 160The 161.Li ports/ 162branch to use. 163Defaults to 164.Va head/@rHEAD . 165.It Va TARGET 166The target machine type for cross-building a release. 167.It Va TARGET_ARCH 168The target machine architecture for cross-building a release. 169.Pp 170For the supported list of 171.Va TARGET 172and 173.Va TARGET_ARCH 174combinations, consult the output of 175.Dq make targets 176as documented in 177.Xr build 7 . 178.It Va KERNEL 179The target kernel configuration to use. 180Defaults to 181.Va GENERIC . 182Multiple 183.Va KERNEL 184entries may be specified. 185.It Va MAKE_CONF 186The 187.Xr make.conf 5 188to use for the release build. 189Defaults to 190.Fa /dev/null 191to prevent polluting the release with local system changes. 192.It Va SRC_CONF 193The 194.Xr src.conf 5 195to use for the release build. 196Defaults to 197.Fa /dev/null 198to prevent polluting the release with local system changes. 199.It Va MAKE_FLAGS 200Additional flags to pass to 201.Xr make 1 . 202.It Va WORLD_FLAGS 203Additional flags to pass to 204.Xr make 1 205during the 206.Dq buildworld 207phase. 208Defaults to setting the number of 209.Xr make 1 210jobs 211.Pq Ar -j 212to the number of CPUs available on a SMP-capable system. 213.It Va KERNEL_FLAGS 214Additional flags to pass to 215.Xr make 1 216during the 217.Dq buildkernel 218phase. 219Defaults to setting the number of 220.Xr make 1 221jobs 222.Pq Ar -j 223to half the number of CPUs available on a SMP-capable system. 224.It Va NODOC 225Set to a non-empty value to skip the 226.Li doc/ 227tree checkout. 228When set, 229.Va NODOC 230will prevent the 231.Fa doc.txz 232distribution package from being created. 233.It Va NODVD 234Set to a non-empty value to skip the 235.Cm dvdrom 236target. 237.It Va NOPORTS 238Set to a non-empty value to skip the 239.Li ports/ 240tree checkout. 241When set, 242.Va NOPORTS 243will prevent the 244.Fa ports.txz 245distribution package from being created. 246Setting this also sets 247.Va NODOC . 248.El 249.Sh MAKEFILE TARGETS 250The release makefile 251.Pq Pa src/release/Makefile 252is fairly abstruse. 253Most developers will only be concerned with the 254.Cm release 255and 256.Cm install 257targets. 258.\" XXX: Some sort of introduction to this list? All the others have one. 259.Bl -tag -width ".Cm packagesystem" 260.It Cm release 261Meta-target to build all release media and distributions applicable to this 262platform. 263.It Cm install 264Copy all produced release media to 265.Pa ${DESTDIR} . 266.It Cm cdrom 267Builds installation CD-ROM images. 268This may require the 269.Xr md 4 270(memory disk) device driver be present in the kernel 271(either by being compiled in or available as a module). 272This target produces files called 273.Pa disc1.iso 274and 275.Pa bootonly.iso 276as its output. 277.It Cm dvdrom 278Builds installation DVD-ROM images. 279This may require the 280.Xr md 4 281(memory disk) device driver be present in the kernel 282(either by being compiled in or available as a module). 283This target produces the 284.Pa dvd1.iso 285file as its output. 286.It Cm memstick 287Builds an installation memory stick image named 288.Pa memstick.img . 289Not applicable on all platforms. 290Requires that the 291.Xr md 4 292.Pq memory disk 293device driver be present in the kernel 294.Pq either by being compiled in or available as a module . 295.It Cm mini-memstick 296Similar to 297.Cm memstick , 298with the exception that the installation distribution sets 299are not included. 300.It Cm ftp 301Creates a directory named 302.Pa ftp 303containing the distribution files used in network installations 304and suitable for upload to an FTP mirror. 305.El 306.Pp 307Major subtargets called by targets above: 308.Bl -tag -width ".Cm packagesystem" 309.It Cm packagesystem 310Generates all the distribution archives 311.Pq base, kernel, ports, doc 312applicable on this platform. 313.It Cm system 314Builds a bootable installation system containing all the distribution files 315packaged by the 316.Cm packagesystem 317target, and suitable for imaging by the 318.Cm cdrom , 319.Cm dvdrom 320and 321.Cm memstick 322targets. 323.It Cm reldoc 324Builds the release documentation. 325This includes the release notes, 326hardware guide, and installation instructions. 327Other documentation, such as the Handbook, 328is built during the 329.Cm base.txz 330target invoked by 331.Cm packagesystem . 332.El 333.Sh ENVIRONMENT 334Optional variables: 335.Bl -tag -width ".Ev TARGET_ARCH" 336.It Ev OSRELEASE 337Optional base name for generated media images 338.Pq e.g., FreeBSD-9.0-RC2-amd64 . 339Defaults to the output of 340.Ic `uname -s`-`uname -r`-`uname -p` 341within the chroot. 342.It Ev WORLDDIR 343Location of a directory containing the src tree. 344By default, the directory 345above the one containing the makefile 346.Pq Pa src . 347.It Ev PORTSDIR 348Location of a directory containing the ports tree. 349By default, 350.Pa /usr/ports . 351If it is unset or cannot be found, ports will not be included in the release. 352.It Ev DOCDIR 353Location of a directory containing the doc tree. 354By default, 355.Pa /usr/doc . 356If it is unset or cannot be found, most documentation will not be included in 357the release; see 358.Ev NODOC 359below. 360.It Ev NOPORTS 361If defined, the Ports Collection will be omitted from the release. 362.It Ev NOSRC 363If set, do not include system source code in the release. 364.It Ev NODOC 365If defined, the XML-based documentation from the 366.Fx 367Documentation Project will not be built. 368However, the 369.Dq doc 370distribution will still be created with the minimal documentation set 371provided in 372.Pa src/share/doc . 373.It Ev TARGET 374The target hardware platform. 375This is analogous to the 376.Dq Nm uname Fl m 377output. 378This is necessary to cross-build some target architectures. 379For example, cross-building for PC98 machines requires 380.Ev TARGET_ARCH Ns = Ns Li i386 381and 382.Ev TARGET Ns = Ns Li pc98 . 383If not set, 384.Ev TARGET 385defaults to the current hardware platform. 386.It Ev TARGET_ARCH 387The target machine processor architecture. 388This is analogous to the 389.Dq Nm uname Fl p 390output. 391Set this to cross-build for a different architecture. 392If not set, 393.Ev TARGET_ARCH 394defaults to the current machine architecture, unless 395.Ev TARGET 396is also set, in which case it defaults to the appropriate 397value for that platform. 398Typically, one only needs to set 399.Ev TARGET . 400.El 401.Sh FILES 402.Bl -tag -compact -width Pa 403.It Pa /usr/doc/Makefile 404.It Pa /usr/doc/share/mk/doc.project.mk 405.It Pa /usr/ports/Mk/bsd.port.mk 406.It Pa /usr/ports/Mk/bsd.sites.mk 407.It Pa /usr/share/examples/etc/make.conf 408.It Pa /usr/src/Makefile 409.It Pa /usr/src/Makefile.inc1 410.It Pa /usr/src/release/Makefile 411.It Pa /usr/src/release/release.sh 412.It Pa /usr/src/release/release.conf.sample 413.El 414.Sh EXAMPLES 415The following sequence of commands can be used to build a 416.Dq "-CURRENT snapshot": 417.Bd -literal -offset indent 418cd /usr 419svn co svn://svn.freebsd.org/base/head src 420cd src 421make buildworld buildkernel 422cd release 423make release 424make install DESTDIR=/var/freebsd-snapshot 425.Ed 426.Pp 427After running these commands, all produced distribution files (tarballs 428for FTP, CD-ROM images, etc.) are available in the 429.Pa /var/freebsd-snapshot 430directory. 431.Pp 432The following sequence of commands can be used to build a 433.Dq "-CURRENT snapshot" 434in a clean environment, including ports and documentation: 435.Bd -literal -offset indent 436cd /usr/src/release 437sh release.sh 438.Ed 439.Pp 440Optionally, a configuration file can be used customize the release build, 441such as the subversion revision to use, the branch of the subversion tree for 442.Li src/ , 443.Li ports/ , 444and 445.Li doc/ . 446.Bd -literal -offset indent 447cd /usr/src/release 448sh release.sh -c $HOME/release.conf 449.Ed 450.Pp 451After running these commands, all prepared release files are available in the 452.Pa /scratch 453directory. 454The target directory can be changed by specifying the 455.Va CHROOTDIR 456variable in 457.Li release.conf . 458.Sh SEE ALSO 459.Xr cc 1 , 460.Xr install 1 , 461.Xr make 1 , 462.Xr svn 1 Pq Pa ports/devel/subversion , 463.Xr uname 1 , 464.Xr md 4 , 465.Xr make.conf 5 , 466.Xr build 7 , 467.Xr ports 7 , 468.Xr chroot 8 , 469.Xr mtree 8 , 470.Xr sysctl 8 471.Rs 472.%T "FreeBSD Release Engineering" 473.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 474.Re 475.Rs 476.%T "FreeBSD Release Engineering of Third Party Packages" 477.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 478.Re 479.Rs 480.%T "FreeBSD Developers' Handbook" 481.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 482.Re 483.Sh HISTORY 484.Fx 4851.x 486used a manual checklist, compiled by 487.An Rod Grimes , 488to produce a release. 489Apart from being incomplete, the list put a lot of specific demands on 490available file systems and was quite torturous to execute. 491.Pp 492As part of the 493.Fx 2.0 494release engineering effort, significant 495effort was spent getting 496.Pa src/release/Makefile 497into a shape where it could at least automate most of the tediousness 498of building a release in a sterile environment. 499.Pp 500For the 501.Fx 9.0 502release, 503.Pa src/release/Makefile 504was overhauled and the wrapper script 505.Pa src/release/generate-release.sh 506introduced to support the introduction of a new installer. 507.Pp 508For the 509.Fx 9.2 510release, 511.Pa src/release/release.sh 512was introduced to support per-build configuration files. 513.Pa src/release/release.sh 514is heavily based on the 515.Pa src/release/generate-release.sh 516script. 517.Pp 518At near 1000 revisions spread over multiple branches, the 519.Xr svn 1 520log of 521.Pa src/release/Makefile 522contains a vivid historical record of some 523of the hardships release engineers go through. 524.Sh AUTHORS 525.Pa src/release/Makefile 526was originally written by 527.An -nosplit 528.An Rod Grimes , 529.An Jordan Hubbard , 530and 531.An Poul-Henning Kamp . 532.Pp 533This manual page was originally written by 534.An Murray Stokely Aq murray@FreeBSD.org . 535.Pp 536It was updated by 537.An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org 538to include the 539.Fa generate-release.sh 540script used for the 541.Fx 9.0 542release cycle. 543.Pp 544It was later updated by 545.An Glen Barber Aq gjb@FreeBSD.org 546to include the 547.Fa release.sh 548script used for the 549.Fx 9.2 550release cycle. 551