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