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