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 and fixit 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 MFS root file systems. 148.It Cm release.10 149Creates the boot, MFS root, and fixit floppies. 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.El 210.Pp 211Optional variables: 212.Bl -tag -width ".Va NO_PREFETCHDISTFILES" 213.It Va CVSCMDARGS 214Additional arguments for 215.Xr cvs 1 216.Ic checkout 217and 218.Ic update 219commands. 220For example, setting this variable to 221.Dq Li "-D '01/01/2002 00:00:00 GMT'" 222for 223.Dq Li "make release" 224or 225.Dq Li "make rerelease" 226will ask 227.Xr cvs 1 228to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively. 229.It Va DOC_LANG 230The list of languages and encodings the SGML-based documentation 231should be built for. 232If not set, the documentation is built for all available languages. 233.It Va DOCRELEASETAG 234The CVS tag to use when checking out the documentation tree. 235Usually, 236the head of the documentation tree is used by default. 237If 238.Va RELEASETAG 239specifies a release tag, 240then the associated release version is used as the default instead. 241.It Va EXTLOCALDIR 242The directory that will be copied to 243.Pa ${CHROOTDIR}/usr/local . 244.It Va KERNEL_FLAGS 245The contents of this variable are passed to 246.Xr make 1 247when building kernels during the release build. 248For example, setting this variable to 249.Dq Li "-j 4" 250will instruct 251.Xr make 1 252to execute up to four processes at a time. 253.It Va KERNELS 254Specifies a list of additional kernel configurations to compile and 255install into the 256.Dq base 257distribution. 258Each kernel is installed into 259.Pa /boot/<config> 260so that it can be booted from the loader via 261.Dq Li "boot <config>" . 262.It Va LOCAL_PATCHES 263A patch file against 264.Pa /usr/src 265that will be applied in the 266.Xr chroot 8 267environment before the release build begins. 268.It Va PATCH_FLAGS 269Arguments for the 270.Xr patch 1 271command used to apply 272.Va LOCAL_PATCHES 273patch file. 274.It Va LOCAL_SCRIPT 275A script that will be run in the 276.Xr chroot 8 277environment immediately after any local patches are applied. 278.It Va MAKE_ISOS 279If defined, bootable ISO CD-ROM images will be created from the 280contents of the CD-ROM stage directory. 281.It Va NOCDROM 282If defined, the CD-ROM stage directories will not be created. 283.It Va NODOC 284If defined, the SGML-based documentation from the 285.Fx 286Documentation Project will not be built. 287However, the 288.Dq doc 289distribution will still be created with the minimal documentation set 290provided in 291.Pa src/share/doc . 292.It Va NO_FLOPPIES 293If defined, no boot and fixit floppy disk images will be created. 294.It Va NOPORTS 295If defined, the Ports Collection will be omitted from the release. 296.It Va NOPORTREADMES 297If defined, readme files will not be created for each individual port 298in the Ports Collection. 299The default behavior is for 300.Dq Li "make release" 301to run 302.Dq Li "make readmes" 303from 304.Pa ${CHROOTDIR}/usr/ports , 305which can be a very time consuming operation. 306.It Va PORTSRELEASETAG 307The CVS tag to use when checking out the ports tree. 308Usually, 309the head of the ports tree is used by default. 310If 311.Va RELEASETAG 312specifies a release tag, 313then the associated release version is used as the default instead. 314.It Va NO_PREFETCHDISTFILES 315If this variable is defined, 316then distfiles needed during the release build will not be downloaded prior to 317entering the 318.Xr chroot 8 319environment. 320Note that if 321.Va NO_PREFETCHDISTFILES 322is not set, 323the fetching is done after any distfiles are obtained via 324.Va RELEASEDISTFILES . 325.It Va RELEASEDISTFILES 326The directory where the distribution files for ports required by the 327release build can be found. 328This may save a significant amount of time over downloading the 329distfiles through a slow link. 330.It Va RELEASENOUPDATE 331If this variable is defined for 332.Dq Li "make rerelease" , 333the source code will not be updated with 334.Dq Li "cvs update" . 335.It Va RELEASETAG 336The CVS tag corresponding to the release that is to be built. 337If undefined, the release will be built from the 338.Dv HEAD 339of the CVS tree 340(a 341.Dq "-CURRENT snapshot" ) . 342.It Va TARGET_ARCH 343The target machine processor architecture. 344This is analogous to the 345.Dq Nm uname Fl p 346output. 347Set this to cross-build for a different architecture. 348.It Va TARGET 349The target hardware platform. 350This is analogous to the 351.Dq Nm uname Fl m 352output. 353This is necessary to cross-build some target architectures. 354For example, cross-building for PC98 machines requires 355.Va TARGET_ARCH Ns = Ns Li i386 356and 357.Va TARGET Ns = Ns Li pc98 . 358.It Va WORLDDIR 359The directory where 360.Dq Li "make buildworld" 361was run; defaults to 362.Pa ${.CURDIR}/.. 363which usually points to 364.Pa /usr/src . 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