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