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 RELEASETAG" 175.It Va CHROOTDIR 176The directory to be used as the 177.Xr chroot 8 178environment for the entire release build. 179.\" XXX: I recommend against hardcoding specific numbers like "2.3" here; 180.\" XXX: perhaps it should be replaced with something to the effect of 181.\" XXX: "we don't know how much space you'll need, but make sure you have 182.\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number, 183.\" XXX: but at least it looks less like a decree and more like an estimate. 184This filesystem should have at least 2.3 gigabytes of free space on the 185i386 architecture. 186.It Va BUILDNAME 187The name of the release to be built. 188This is used to set the 189.Va RELEASE 190value in 191.Pa sys/conf/newvers.sh , 192which affects the output of 193.Xr uname 1 . 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.It Va RELEASETAG 204The CVS tag corresponding to the release that is to be built. 205If undefined, the release will be built from the 206.Dv HEAD 207of the CVS tree 208(a 209.Dq "-CURRENT snapshot" ) . 210.El 211.Pp 212Optional variables: 213.Bl -tag -width ".Va RELEASEDISTFILES" 214.It Va CVSCMDARGS 215Additional arguments for 216.Xr cvs 1 217.Ic checkout 218and 219.Ic update 220commands. 221For example, setting this variable to 222.Dq Li "-D '01/01/2002 00:00:00 GMT'" 223for 224.Dq Li "make release" 225or 226.Dq Li "make rerelease" 227will ask 228.Xr cvs 1 229to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively. 230.It Va LOCAL_PATCHES 231A patch file against 232.Pa /usr/src 233that will be applied in the 234.Xr chroot 8 235environment before the release build begins. 236.It Va PATCH_FLAGS 237Arguments for the 238.Xr patch 1 239command used to apply 240.Va LOCAL_PATCHES 241patch file. 242.It Va LOCAL_SCRIPT 243A script that will be run in the 244.Xr chroot 8 245environment immediately after any local patches are applied. 246.It Va MAKE_ISOS 247If defined, bootable ISO CD-ROM images will be created from the 248contents of the CD-ROM stage directory. 249.It Va NODOC 250If set to 251.Dq Li YES , 252the SGML-based documentation from the 253.Fx 254Documentation Project will not be built. 255However, the 256.Dq doc 257distribution will still be created with the minimal documentation set 258provided in 259.Pa src/share/doc . 260.It Va NOPORTS 261If set to 262.Dq Li YES 263then the Ports Collection will be omitted from the release. 264.It Va NOPORTREADMES 265If defined, readme files will not be created for each individual port 266in the Ports Collection. 267The default behavior is for 268.Dq Li "make release" 269to run 270.Dq Li "make readmes" 271from 272.Pa ${CHROOTDIR}/usr/ports , 273which can be a very time consuming operation. 274.It Va RELEASEDISTFILES 275The directory where the distribution files for ports required by the 276release build can be found. 277This may save a significant amount of time over downloading the 278distfiles through a slow link. 279.It Va RELEASENOUPDATE 280If this variable is defined for 281.Dq Li "make rerelease" , 282the source code will not be updated with 283.Dq Li "cvs update" . 284.It Va TARGET_ARCH 285The target machine processor architecture. 286This is analogous to the 287.Dq Nm uname Fl p 288output. 289Set this to cross-build for a different architecture. 290.It Va TARGET 291The target hardware platform. 292This is analogous to the 293.Dq Nm uname Fl m 294output. 295This is necessary to cross-build some target architectures. 296For example, cross-building for PC98 machines requires 297.Va TARGET_ARCH Ns = Ns Li i386 298and 299.Va TARGET Ns = Ns Li pc98 . 300.El 301.Sh FILES 302.Bl -tag -compact 303.It Pa /etc/make.conf 304.It Pa /usr/doc/Makefile 305.It Pa /usr/doc/share/mk/doc.project.mk 306.It Pa /usr/ports/Mk/bsd.port.mk 307.It Pa /usr/ports/Mk/bsd.sites.mk 308.It Pa /usr/share/examples/etc/make.conf 309.It Pa /usr/src/Makefile 310.It Pa /usr/src/Makefile.inc1 311.It Pa /usr/src/release/Makefile 312.It Pa /usr/src/release/${arch}/drivers.conf 313.It Pa /usr/src/release/${arch}/boot_crunch.conf 314.It Pa /usr/src/release/${arch}/fixit_crunch.conf 315.El 316.Sh EXAMPLES 317The following sequence of commands was used to build the 318.Fx 4.5 319release: 320.Bd -literal -offset indent 321cd /usr 322cvs co -rRELENG_4_5_0_RELEASE src 323cd src 324make buildworld 325cd release 326make release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\ 327 CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_5_0_RELEASE 328.Ed 329.Pp 330After running these commands, a complete system suitable for FTP or 331CD-ROM distribution is available in the 332.Pa /local3/release/R 333directory. 334.Pp 335The following sequence of commands can be used to build a 336.Dq "-CURRENT snapshot" 337of a 338locally modified source tree: 339.Bd -literal -offset indent 340cd /usr/src 341cvs diff -u > /path/to/local.patch 342make buildworld 343cd release 344make release CHROOTDIR=/local3/release BUILDNAME=5.0-CURRENT \\ 345 CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch 346.Ed 347.Sh SEE ALSO 348.Xr cc 1 , 349.Xr crunchgen 1 , 350.Xr cvs 1 , 351.Xr install 1 , 352.Xr make 1 , 353.Xr patch 1 , 354.Xr uname 1 , 355.Xr md 4 , 356.Xr drivers.conf 5 , 357.Xr make.conf 5 , 358.Xr build 7 , 359.Xr ports 7 , 360.Xr chroot 8 , 361.Xr mtree 8 362.Rs 363.%T "FreeBSD Release Engineering" 364.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 365.Re 366.Rs 367.%T "FreeBSD Release Engineering of Third Party Packages" 368.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 369.Re 370.Rs 371.%T "FreeBSD Developers' Handbook" 372.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 373.Re 374.Sh HISTORY 375.Fx 3761.x 377used a manual checklist, compiled by 378.An Rod Grimes , 379to produce a release. 380Apart from being incomplete, the list put a lot of specific demands on 381available filesystems and was quite torturous to execute. 382.Pp 383As part of the 384.Fx 2.0 385release engineering effort, significant 386effort was spent getting 387.Pa src/release/Makefile 388into a shape where it could at least automate most of the tediousness 389of building a release in a sterile environment. 390.Pp 391With its almost 1000 revisions spread over multiple branches, the 392.Xr cvs 1 393log of 394.Pa src/release/Makefile 395contains a vivid historical record of some 396of the hardships release engineers go through. 397.Sh AUTHORS 398.Pa src/release/Makefile 399was originally written by 400.An -nosplit 401.An Rod Grimes , 402.An Jordan Hubbard , 403and 404.An Poul-Henning Kamp . 405This manual page was written by 406.An Murray Stokely Aq murray@FreeBSD.org . 407