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 August 17, 2009 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 40CVS repository in 41.Pa src/release . 42A complete release can actually be built with only a single command, 43including the creation of ISO images suitable for burning to CD-ROM, 44installation floppies, and an FTP install directory. 45This command is aptly named 46.Dq Li "make release" . 47.Pp 48Before attempting to build a release, the user is expected to be 49familiar with the contents of 50.Xr build 7 , 51and should have experience upgrading systems from source. 52The release build process requires that 53.Pa /usr/obj 54be populated with the output of 55a native 56.Dq Li "make buildworld" 57compiled from sources matching the currently running kernel. 58This is necessary so that the object files for a complete system can 59be installed into a clean 60.Xr chroot 8 61environment. 62The release procedure also requires that the 63.Xr md 4 64(memory disk) device driver be present in the kernel 65(either by being compiled in or available as a module). 66.Pp 67This document does not cover source code management, quality 68assurance, or other aspects of the release engineering process. 69.Sh TARGETS 70The release makefile 71.Pq Pa src/release/Makefile 72is fairly abstruse. 73Most developers will only be concerned with the 74.Cm release 75target. 76.\" XXX: Some sort of introduction to this list? All the others have one. 77.Bl -tag -width ".Cm package-split" 78.It Cm release 79Uses 80.Dq Li "make installworld" 81to install a clean system into a 82.Xr chroot 8 83environment on the file system. 84Checks out the specified version of the source code and then rebuilds 85the entire system in the clean environment with 86.Dq Li "make buildworld" . 87The detailed steps that follow are then executed to package up the 88different distributions, build the installation floppy disks, build 89release documentation, and so on. 90.Pp 91This target must be built as root with the 92.Va kern.securelevel 93sysctl set to \-1 (the default). 94.It Cm rerelease 95Assumes that the output of a release build has been manually modified, 96and performs the minimal number of steps to rebuild the release using 97the intermediate output of the previous 98.Dq Li "make release" . 99.It Cm floppies 100Generate a new set of boot and fixit floppies. 101This will call the 102.Cm release.4 , 103.Cm release.8 , 104.Cm floppies.1 , 105.Cm floppies.2 , 106and 107.Cm floppies.3 108targets to re-generate the floppy images of a previous 109.Dq Li "make release" . 110This is most often used to build custom boot floppies. 111.It Cm package-split 112Generates the portions of the disc 1 and disc 2 images related to packages. 113It uses the list of desired packages from the 114.Pa src/release/scripts/package-split.py 115script to pull packages out of a package build provided by the ports team 116and organize them appropriately. 117The resulting directory can then be passed to 118.Dq Li "make release" 119via the 120.Va CD_PACKAGE_TREE 121variable to populate the ISO images built by the 122.Cm iso.1 123target with the correct package related bits. 124.El 125.Pp 126Targets called by 127.Dq Li "make release" : 128.Bl -tag -width ".Cm fetch-distfiles" 129.It Cm release.1 130Cleans out the 131.Pa ${CHROOTDIR}/R 132directory and uses 133.Xr mtree 8 134to build the directory hierarchy for the system. 135.It Cm release.2 136Installs the system into the distribution directories. 137.It Cm release.3 138Makes and installs the 139.Pa GENERIC 140kernel as well as any other kernels listed in 141.Va KERNELS . 142.It Cm release.4 143Uses 144.Xr crunchgen 1 145to build 146.Dq crunched 147binaries to live on the installation floppies. 148.It Cm release.5 149Builds synthetic distributions, and cleans up the previously built 150distribution trees. 151.It Cm release.6 152Creates tarballs of the assembled distribution trees. 153.It Cm release.7 154Makes source distributions. 155.It Cm release.8 156Creates the MFS root file systems. 157.It Cm floppies.1 158Creates the boot and kernel floppies. 159.It Cm floppies.2 160Creates the fixit floppy. 161.It Cm floppies.3 162Finalizes the 163.Pa ${CHROOTDIR}/R/ftp/stage/floppies 164staging directory. 165.It Cm ftp.1 166Sets up a suitable area for FTP installations in 167.Pa ${CHROOTDIR}/R/ftp . 168.It Cm cdrom.1 169Create the layout for the live file system CD-ROM image in 170.Pa ${CHROOTDIR}/R/cdrom . 171.It Cm cdrom.2 172Create the layout for the first and second CD-ROM images. 173.It Cm cdrom.3 174Create the layout for the boot-only CD-ROM image and the boot-only UFS 175miniroot image. 176.It Cm iso.1 177Builds ISO images (installation and 178.Dq live 179file system) from the CD-ROM release area 180(disabled by default, see 181.Va MAKE_ISOS 182below). 183.It Cm fetch-distfiles 184Fetches distfiles needed during the release build that are not already in 185.Va RELEASEDISTFILES . 186.It Cm doc.1 187Builds all of the necessary tools to turn the 188.Fx 189Documentation Project source documents (SGML, XML) into HTML 190and text documents that will accompany the release. 191Also, builds and installs the actual user documentation. 192This includes the Handbook, FAQ, articles, and so on. 193.It Cm doc.2 194Builds the release documentation. 195This includes the release notes, 196hardware guide, and installation instructions. 197.El 198.Sh ENVIRONMENT 199Variables that must be specified: 200.Bl -tag -width ".Va CHROOTDIR" 201.It Va CHROOTDIR 202The directory to be used as the 203.Xr chroot 8 204environment for the entire release build. 205.\" XXX: I recommend against hardcoding specific numbers like "2.3" here; 206.\" XXX: perhaps it should be replaced with something to the effect of 207.\" XXX: "we do not know how much space you'll need, but make sure you have 208.\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number, 209.\" XXX: but at least it looks less like a decree and more like an estimate. 210This file system should have at least 3.2 gigabytes of free space on the 211i386 architecture. 212.It Va CVSROOT 213The location of the 214.Fx 215CVS repository. 216This path name is in reference to the real system root, 217.Em not 218the root of the 219.Xr chroot 8 220directory tree. 221.El 222.Pp 223Optional variables: 224.Bl -tag -width ".Va NO_PREFETCHDISTFILES" 225.It Va BUILDNAME 226The name of the release to be built. 227This is used to set the 228.Va RELEASE 229value in 230.Pa sys/conf/newvers.sh , 231which affects the output of 232.Xr uname 1 . 233If not set, a name with the timestamp and the 234.Dq Li -SNAP 235suffix will be generated. 236.It Va CD_PACKAGE_TREE 237A directory containing extra bits for the first and second CD-ROM images. 238The extra files for the first disc should be in 239.Pa ${CD_PACKAGE_TREE}/disc1 240and the extra files for the second disc should be in 241.Pa ${CD_PACKAGE_TREE}/disc2 . 242Typically, this variable will be set to the output directory of an earlier 243invocation of the 244.Cm package-split 245target. 246.It Va CVSARGS 247Additional arguments for 248.Xr cvs 1 249that come before the subcommands such as 250.Dq Li "-qR" . 251.It Va CVSCMDARGS 252Additional arguments for 253.Xr cvs 1 254.Ic checkout 255and 256.Ic update 257commands. 258For example, setting this variable to 259.Dq Li "-D '01/01/2002 00:00:00 GMT'" 260for 261.Dq Li "make release" 262or 263.Dq Li "make rerelease" 264will ask 265.Xr cvs 1 266to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively. 267.It Va DOC_LANG 268The list of languages and encodings the SGML-based documentation 269should be built for. 270If not set, the documentation is built for all available languages. 271.It Va DOCRELEASETAG 272The CVS tag to use when checking out the documentation tree. 273Usually, 274the head of the documentation tree is used by default. 275If 276.Va RELEASETAG 277specifies a release tag, 278then the associated release version is used as the default instead. 279.It Va EXTLOCALDIR 280The directory that will be copied to 281.Pa ${CHROOTDIR}/usr/local . 282.It Va EXTSRCDIR 283The directory specified by this variable will be copied into 284.Pa ${CHROOTDIR}/usr/src 285instead of that directory being populated by a CVS checkout. 286For 287.Dq Li "rerelease" , 288this will NOT be copied; cvs update will be used instead. 289.It Va EXTDOCDIR 290The directory specified by this variable will be copied into 291.Pa ${CHROOTDIR}/usr/doc . 292For 293.Dq Li "rerelease" , 294this will NOT be copied again. 295.It Va EXTPORTSDIR 296The directory specified by this variable will be copied into 297.Pa ${CHROOTDIR}/usr/ports . 298For 299.Dq Li "rerelease" , 300this will do NOTHING. 301.It Va KERNEL_FLAGS 302The contents of this variable are passed to 303.Xr make 1 304when building kernels during the release build. 305For example, setting this variable to 306.Dq Li "-j 4" 307will instruct 308.Xr make 1 309to execute up to four processes at a time. 310.It Va KERNELS 311Specifies a list of additional kernel configurations to compile and 312install into the 313.Dq base 314distribution. 315Each kernel is installed into 316.Pa /boot/<config> 317so that it can be booted from the loader via 318.Dq Li "boot <config>" . 319.It Va LOCAL_PATCHES 320Patch files against 321.Pa /usr/src 322that will be applied in the 323.Xr chroot 8 324environment before the release build begins. 325.It Va PATCH_FLAGS 326Arguments for the 327.Xr patch 1 328command used to apply 329.Va LOCAL_PATCHES 330patch file. 331.It Va LOCAL_SCRIPT 332A script that will be run in the 333.Xr chroot 8 334environment immediately after any local patches are applied. 335.It Va MAKE_DVD 336If defined, build a bootable ISO DVD image in the CD-ROM 337stage directory. 338This option may not be available for all architectures. 339.It Va MAKE_ISOS 340If defined, bootable ISO CD-ROM images will be created from the 341contents of the CD-ROM stage directory. 342.It Va NOCDROM 343If defined, the CD-ROM stage directories will not be created. 344.It Va NODOC 345If defined, the SGML-based documentation from the 346.Fx 347Documentation Project will not be built. 348However, the 349.Dq doc 350distribution will still be created with the minimal documentation set 351provided in 352.Pa src/share/doc . 353.It Va NO_FLOPPIES 354If defined, no boot and fixit floppy disk images will be created (for those 355platforms supporting them). 356.It Va NOPORTS 357If defined, the Ports Collection will be omitted from the release. 358.It Va PORTSRELEASETAG 359The CVS tag to use when checking out the ports tree. 360Usually, 361the head of the ports tree is used by default. 362If 363.Va RELEASETAG 364specifies a release tag, 365then the associated release version is used as the default instead. 366.It Va NO_PREFETCHDISTFILES 367If this variable is defined, 368then distfiles needed during the release build will not be downloaded prior to 369entering the 370.Xr chroot 8 371environment. 372Note that if 373.Va NO_PREFETCHDISTFILES 374is not set, 375the fetching is done after any distfiles are obtained via 376.Va RELEASEDISTFILES . 377.It Va RELEASEDISTFILES 378The directory where the distribution files for ports required by the 379release build can be found. 380This may save a significant amount of time over downloading the 381distfiles through a slow link. 382.It Va RELEASENOUPDATE 383If this variable is defined for 384.Dq Li "make rerelease" , 385the source code will not be updated with 386.Dq Li "cvs update" . 387.It Va RELEASETAG 388The CVS tag corresponding to the release that is to be built. 389If undefined, the release will be built from the 390.Dv HEAD 391of the CVS tree 392(a 393.Dq "-CURRENT snapshot" ) . 394.It Va SEPARATE_LIVEFS 395Store the live file system on its own CD-ROM image rather than placing it on 396the first disc. 397.It Va SVNCMDARGS 398Additional arguments for svn 399.Ic checkout 400and 401.Ic switch 402commands. 403.It Va SVNROOT 404The location of the FreeBSD SVN source repository. 405If this variable is set, 406then the source tree will be extracted using Subversion rather than 407CVS. 408.It Va SVNBRANCH 409The branch to check out from a SVN source repository. 410It is specified as a path such as 411.Pa head 412or 413.Pa stable/7 . 414If this variable is not set, 415then the branch that corresponds to the current value of 416.Va RELEASETAG 417will be used. 418If neither 419.Va SVNBRANCH 420nor 421.Va RELEASETAG 422are set, 423then the 424.Pa head 425branch will be used. 426.It Va TARGET_ARCH 427The target machine processor architecture. 428This is analogous to the 429.Dq Nm uname Fl p 430output. 431Set this to cross-build for a different architecture. 432.It Va TARGET 433The target hardware platform. 434This is analogous to the 435.Dq Nm uname Fl m 436output. 437This is necessary to cross-build some target architectures. 438For example, cross-building for PC98 machines requires 439.Va TARGET_ARCH Ns = Ns Li i386 440and 441.Va TARGET Ns = Ns Li pc98 . 442.It Va WORLDDIR 443The directory where 444.Dq Li "make buildworld" 445was run; defaults to 446.Pa ${.CURDIR}/.. 447which usually points to 448.Pa /usr/src . 449.It Va WORLD_FLAGS 450The contents of this variable are passed to 451.Xr make 1 452when building world during the release build. 453For example, setting this variable to 454.Dq Li "-j 4" 455will instruct 456.Xr make 1 457to execute up to four processes at a time. 458.El 459.Sh FILES 460.Bl -tag -compact 461.It Pa /usr/doc/Makefile 462.It Pa /usr/doc/share/mk/doc.project.mk 463.It Pa /usr/ports/Mk/bsd.port.mk 464.It Pa /usr/ports/Mk/bsd.sites.mk 465.It Pa /usr/share/examples/etc/make.conf 466.It Pa /usr/src/Makefile 467.It Pa /usr/src/Makefile.inc1 468.It Pa /usr/src/release/Makefile 469.It Pa /usr/src/release/${arch}/boot_crunch.conf 470.It Pa /usr/src/release/${arch}/fixit_crunch.conf 471.El 472.Sh EXAMPLES 473The following sequence of commands was used to build the 474.Fx 4.9 475release: 476.Bd -literal -offset indent 477cd /usr 478cvs co -rRELENG_4_9_0_RELEASE src 479cd src 480make buildworld 481cd release 482make release CHROOTDIR=/local3/release BUILDNAME=4.9-RELEASE \\ 483 CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_9_0_RELEASE 484.Ed 485.Pp 486After running these commands, a complete system suitable for FTP or 487CD-ROM distribution is available in the 488.Pa /local3/release/R 489directory. 490.Pp 491The following sequence of commands can be used to build a 492.Dq "-CURRENT snapshot" 493of a 494locally modified source tree: 495.Bd -literal -offset indent 496cd /usr/src 497cvs diff -u > /path/to/local.patch 498make buildworld 499cd release 500make release CHROOTDIR=/local3/release BUILDNAME=6.0-CURRENT \\ 501 CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch 502.Ed 503.Sh SEE ALSO 504.Xr cc 1 , 505.Xr crunchgen 1 , 506.Xr cvs 1 , 507.Xr install 1 , 508.Xr make 1 , 509.Xr patch 1 , 510.Xr svn 1 Pq Pa ports/devel/subversion-freebsd , 511.Xr uname 1 , 512.Xr md 4 , 513.Xr make.conf 5 , 514.Xr build 7 , 515.Xr ports 7 , 516.Xr chroot 8 , 517.Xr mtree 8 , 518.Xr sysctl 8 519.Rs 520.%T "FreeBSD Release Engineering" 521.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 522.Re 523.Rs 524.%T "FreeBSD Release Engineering of Third Party Packages" 525.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 526.Re 527.Rs 528.%T "FreeBSD Developers' Handbook" 529.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 530.Re 531.Sh HISTORY 532.Fx 5331.x 534used a manual checklist, compiled by 535.An Rod Grimes , 536to produce a release. 537Apart from being incomplete, the list put a lot of specific demands on 538available file systems and was quite torturous to execute. 539.Pp 540As part of the 541.Fx 2.0 542release engineering effort, significant 543effort was spent getting 544.Pa src/release/Makefile 545into a shape where it could at least automate most of the tediousness 546of building a release in a sterile environment. 547.Pp 548At near 1000 revisions spread over multiple branches, the 549.Xr cvs 1 550log of 551.Pa src/release/Makefile 552contains a vivid historical record of some 553of the hardships release engineers go through. 554.Sh AUTHORS 555.Pa src/release/Makefile 556was originally written by 557.An -nosplit 558.An Rod Grimes , 559.An Jordan Hubbard , 560and 561.An Poul-Henning Kamp . 562This manual page was written by 563.An Murray Stokely Aq murray@FreeBSD.org . 564.Sh BUGS 565Infrastructure changes are occasionally made to the 566.Fx 567documentation set in such a way that release builds on security 568branches can fail. 569To work around this, release builds can be made to checkout the 570documentation from the last fully supported release of 571.Fx . 572For example: 573.Pp 574.Dl "make release RELEASETAG=RELENG_4_9 DOCRELEASETAG=RELEASE_4_9_0 ..." 575