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