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