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 referenced 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 DOCRELEASETAG 224The CVS tag to use when checking out the documentation tree. 225Usually, 226the head of the documentation tree is used by default. 227If 228.Va RELEASETAG 229specifies a release tag, 230then the associated release version is used as the default instead. 231.It Va KERNEL_FLAGS 232The contents of this variable are passed to 233.Xr make 1 234when building kernels during the release build. 235For example, setting this variable to 236.Dq Li "-j 4" 237will instruct 238.Xr make 1 239to execute up to four processes at a time. 240.It Va LOCAL_PATCHES 241A patch file against 242.Pa /usr/src 243that will be applied in the 244.Xr chroot 8 245environment before the release build begins. 246.It Va PATCH_FLAGS 247Arguments for the 248.Xr patch 1 249command used to apply 250.Va LOCAL_PATCHES 251patch file. 252.It Va LOCAL_SCRIPT 253A script that will be run in the 254.Xr chroot 8 255environment immediately after any local patches are applied. 256.It Va MAKE_ISOS 257If defined, bootable ISO CD-ROM images will be created from the 258contents of the CD-ROM stage directory. 259.It Va NODOC 260If set to 261.Dq Li YES , 262the SGML-based documentation from the 263.Fx 264Documentation Project will not be built. 265However, the 266.Dq doc 267distribution will still be created with the minimal documentation set 268provided in 269.Pa src/share/doc . 270.It Va NOPORTS 271If set to 272.Dq Li YES 273then the Ports Collection will be omitted from the release. 274.It Va NOPORTREADMES 275If defined, readme files will not be created for each individual port 276in the Ports Collection. 277The default behavior is for 278.Dq Li "make release" 279to run 280.Dq Li "make readmes" 281from 282.Pa ${CHROOTDIR}/usr/ports , 283which can be a very time consuming operation. 284.It Va PORTSRELEASETAG 285The CVS tag to use when checking out the ports tree. 286Usually, 287the head of the ports tree is used by default. 288If 289.Va RELEASETAG 290specifies a release tag, 291then the associated release version is used as the default instead. 292.It Va PREFETCHDISTFILES 293If this variable is defined, 294then distfiles needed during the release build will be downloaded prior to 295entering the 296.Xr chroot 8 297environment. 298Note that this is done after any distfiles are obtained via 299.Va RELEASEDISTFILES . 300.It Va RELEASEDISTFILES 301The directory where the distribution files for ports required by the 302release build can be found. 303This may save a significant amount of time over downloading the 304distfiles through a slow link. 305.It Va RELEASENOUPDATE 306If this variable is defined for 307.Dq Li "make rerelease" , 308the source code will not be updated with 309.Dq Li "cvs update" . 310.It Va RELEASETAG 311The CVS tag corresponding to the release that is to be built. 312If undefined, the release will be built from the 313.Dv HEAD 314of the CVS tree 315(a 316.Dq "-CURRENT snapshot" ) . 317.It Va TARGET_ARCH 318The target machine processor architecture. 319This is analogous to the 320.Dq Nm uname Fl p 321output. 322Set this to cross-build for a different architecture. 323.It Va TARGET 324The target hardware platform. 325This is analogous to the 326.Dq Nm uname Fl m 327output. 328This is necessary to cross-build some target architectures. 329For example, cross-building for PC98 machines requires 330.Va TARGET_ARCH Ns = Ns Li i386 331and 332.Va TARGET Ns = Ns Li pc98 . 333.It Va WORLD_FLAGS 334The contents of this variable are passed to 335.Xr make 1 336when building world during the release build. 337For example, setting this variable to 338.Dq Li "-j 4" 339will instruct 340.Xr make 1 341to execute up to four processes at a time. 342.El 343.Sh FILES 344.Bl -tag -compact 345.It Pa /etc/make.conf 346.It Pa /usr/doc/Makefile 347.It Pa /usr/doc/share/mk/doc.project.mk 348.It Pa /usr/ports/Mk/bsd.port.mk 349.It Pa /usr/ports/Mk/bsd.sites.mk 350.It Pa /usr/share/examples/etc/make.conf 351.It Pa /usr/src/Makefile 352.It Pa /usr/src/Makefile.inc1 353.It Pa /usr/src/release/Makefile 354.It Pa /usr/src/release/${arch}/drivers.conf 355.It Pa /usr/src/release/${arch}/boot_crunch.conf 356.It Pa /usr/src/release/${arch}/fixit_crunch.conf 357.El 358.Sh EXAMPLES 359The following sequence of commands was used to build the 360.Fx 4.5 361release: 362.Bd -literal -offset indent 363cd /usr 364cvs co -rRELENG_4_5_0_RELEASE src 365cd src 366make buildworld 367cd release 368make release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\ 369 CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_5_0_RELEASE 370.Ed 371.Pp 372After running these commands, a complete system suitable for FTP or 373CD-ROM distribution is available in the 374.Pa /local3/release/R 375directory. 376.Pp 377The following sequence of commands can be used to build a 378.Dq "-CURRENT snapshot" 379of a 380locally modified source tree: 381.Bd -literal -offset indent 382cd /usr/src 383cvs diff -u > /path/to/local.patch 384make buildworld 385cd release 386make release CHROOTDIR=/local3/release BUILDNAME=5.0-CURRENT \\ 387 CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch 388.Ed 389.Sh SEE ALSO 390.Xr cc 1 , 391.Xr crunchgen 1 , 392.Xr cvs 1 , 393.Xr install 1 , 394.Xr make 1 , 395.Xr patch 1 , 396.Xr uname 1 , 397.Xr md 4 , 398.Xr drivers.conf 5 , 399.Xr make.conf 5 , 400.Xr build 7 , 401.Xr ports 7 , 402.Xr chroot 8 , 403.Xr mtree 8 404.Rs 405.%T "FreeBSD Release Engineering" 406.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 407.Re 408.Rs 409.%T "FreeBSD Release Engineering of Third Party Packages" 410.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 411.Re 412.Rs 413.%T "FreeBSD Developers' Handbook" 414.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 415.Re 416.Sh HISTORY 417.Fx 4181.x 419used a manual checklist, compiled by 420.An Rod Grimes , 421to produce a release. 422Apart from being incomplete, the list put a lot of specific demands on 423available filesystems and was quite torturous to execute. 424.Pp 425As part of the 426.Fx 2.0 427release engineering effort, significant 428effort was spent getting 429.Pa src/release/Makefile 430into a shape where it could at least automate most of the tediousness 431of building a release in a sterile environment. 432.Pp 433With its almost 1000 revisions spread over multiple branches, the 434.Xr cvs 1 435log of 436.Pa src/release/Makefile 437contains a vivid historical record of some 438of the hardships release engineers go through. 439.Sh AUTHORS 440.Pa src/release/Makefile 441was originally written by 442.An -nosplit 443.An Rod Grimes , 444.An Jordan Hubbard , 445and 446.An Poul-Henning Kamp . 447This manual page was written by 448.An Murray Stokely Aq murray@FreeBSD.org . 449