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