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.4 , 98.Cm release.8 , 99and 100.Cm release.9 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.9" 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 118.\" XXX: We build more than one kernel. We build a stripped down 119.\" kernel for the boot media in addition to a full GENERIC kernel. 120Makes and installs the 121.Pa GENERIC 122kernel. 123.It Cm release.4 124Uses 125.Xr crunchgen 1 126to build 127.Dq crunched 128binaries to live on the installation floppies. 129.It Cm release.5 130Builds synthetic distributions, and cleans up the previously built 131distribution trees. 132.It Cm release.6 133Creates tarballs of the assembled distribution trees. 134.It Cm release.7 135Makes source distributions. 136.It Cm release.8 137Creates the boot and MFS root floppies. 138.It Cm release.9 139Creates the fixit floppy. 140.It Cm ftp.1 141Sets up a suitable area for FTP installations in 142.Pa ${CHROOTDIR}/R/ftp . 143.It Cm cdrom.1 144Sets up a suitable area to build CD-ROM images in 145.Pa ${CHROOTDIR}/R/cdrom . 146.It Cm iso.1 147Builds two ISO images (installation and 148.Dq live 149filesystem) from the CD-ROM release area 150(disabled by default, see 151.Va MAKE_ISOS 152below). 153.It Cm doc.1 154Builds all of the necessary tools to turn the 155.Fx 156Documentation Project source documents (SGML, XML) into HTML 157and text documents that will accompany the release. 158Also, builds and installs the actual user documentation. 159This includes the Handbook, FAQ, articles, and so on. 160.It Cm doc.2 161Builds the release documentation. 162This includes the release notes, 163hardware guide, and installation instructions. 164.El 165.Sh ENVIRONMENT 166Variables that must be specified: 167.Bl -tag -width ".Va RELEASETAG" 168.It Va CHROOTDIR 169The directory to be used as the 170.Xr chroot 8 171environment for the entire release build. 172.\" XXX: I recommend against hardcoding specific numbers like "2.3" here; 173.\" XXX: perhaps it should be replaced with something to the effect of 174.\" XXX: "we don't know how much space you'll need, but make sure you have 175.\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number, 176.\" XXX: but at least it looks less like a decree and more like an estimate. 177This filesystem should have at least 2.3 gigabytes of free space on the 178i386 architecture. 179.It Va BUILDNAME 180The name of the release to be built. 181This is used to set the 182.Va RELEASE 183value in 184.Pa sys/conf/newvers.sh , 185which affects the output of 186.Xr uname 1 . 187.It Va CVSROOT 188The location of the 189.Fx 190CVS repository. 191This path name is referenced to the real system root, 192.Em not 193the root of the 194.Xr chroot 8 195directory tree. 196.It Va RELEASETAG 197The CVS tag corresponding to the release that is to be built. 198If undefined, the release will be built from the 199.Dv HEAD 200of the CVS tree 201(a 202.Dq "-CURRENT snapshot" ) . 203.El 204.Pp 205Optional variables: 206.Bl -tag -width ".Va RELEASEDISTFILES" 207.It Va LOCAL_PATCHES 208A patch file against 209.Pa /usr/src 210that will be applied in the 211.Xr chroot 8 212environment before the release build begins. 213.It Va PATCH_FLAGS 214Arguments for the 215.Xr patch 1 216command used to apply 217.Va LOCAL_PATCHES 218patch file. 219.It Va LOCAL_SCRIPT 220A script that will be run in the 221.Xr chroot 8 222environment immediately after any local patches are applied. 223.It Va MAKE_ISOS 224If defined, bootable ISO CD-ROM images will be created from the 225contents of the CD-ROM stage directory. 226.It Va NODOC 227If set to 228.Dq Li YES , 229the SGML-based documentation from the 230.Fx 231Documentation Project will not be built. 232However, the 233.Dq doc 234distribution will still be created with the minimal documentation set 235provided in 236.Pa src/share/doc . 237.It Va NOPORTS 238If set to 239.Dq Li YES 240then the Ports Collection will be omitted from the release. 241.It Va NOPORTREADMES 242If defined, readme files will not be created for each individual port 243in the Ports Collection. 244The default behavior is for 245.Dq Li "make release" 246to run 247.Dq Li "make readmes" 248from 249.Pa ${CHROOTDIR}/usr/ports , 250which can be a very time consuming operation. 251.It Va RELEASEDISTFILES 252The directory where the distribution files for ports required by the 253release build can be found. 254This may save a significant amount of time over downloading the 255distfiles through a slow link. 256.It Va RELEASENOUPDATE 257If this variable is defined for 258.Dq Li "make rerelease" , 259the source code will not be updated with 260.Dq Li "cvs update" . 261.It Va TARGET_ARCH 262The target machine processor architecture. 263This is analogous to the 264.Dq Nm uname Fl p 265output. 266Set this to cross-build for a different architecture. 267.It Va TARGET 268The target hardware platform. 269This is analogous to the 270.Dq Nm uname Fl m 271output. 272This is necessary to cross-build some target architectures. 273For example, cross-building for PC98 machines requires 274.Va TARGET_ARCH Ns = Ns Li i386 275and 276.Va TARGET Ns = Ns Li pc98 . 277.El 278.Sh FILES 279.Bl -tag -compact 280.It Pa /etc/make.conf 281.It Pa /usr/doc/Makefile 282.It Pa /usr/doc/share/mk/doc.project.mk 283.It Pa /usr/ports/Mk/bsd.port.mk 284.It Pa /usr/ports/Mk/bsd.sites.mk 285.It Pa /usr/share/examples/etc/make.conf 286.It Pa /usr/src/Makefile 287.It Pa /usr/src/Makefile.inc1 288.It Pa /usr/src/release/Makefile 289.It Pa /usr/src/release/${arch}/drivers.conf 290.It Pa /usr/src/release/${arch}/boot_crunch.conf 291.It Pa /usr/src/release/${arch}/fixit_crunch.conf 292.El 293.Sh EXAMPLES 294The following sequence of commands was used to build the 295.Fx 4.5 296release: 297.Bd -literal -offset indent 298cd /usr 299cvs co -rRELENG_4_5_0_RELEASE src 300cd src 301make buildworld 302cd release 303make release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\ 304 CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_5_0_RELEASE 305.Ed 306.Pp 307After running these commands, a complete system suitable for FTP or 308CD-ROM distribution is available in the 309.Pa /local3/release/R 310directory. 311.Pp 312The following sequence of commands can be used to build a 313.Dq "-CURRENT snapshot" 314of a 315locally modified source tree: 316.Bd -literal -offset indent 317cd /usr/src 318cvs diff -u > /path/to/local.patch 319make buildworld 320cd release 321make release CHROOTDIR=/local3/release BUILDNAME=5.0-CURRENT \\ 322 CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch 323.Ed 324.Sh SEE ALSO 325.Xr cc 1 , 326.Xr crunchgen 1 , 327.Xr cvs 1 , 328.Xr install 1 , 329.Xr make 1 , 330.Xr patch 1 , 331.Xr uname 1 , 332.Xr md 4 , 333.Xr drivers.conf 5 , 334.Xr make.conf 5 , 335.Xr build 7 , 336.Xr ports 7 , 337.Xr chroot 8 , 338.Xr mtree 8 339.Rs 340.%T "FreeBSD Release Engineering" 341.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 342.Re 343.Rs 344.%T "FreeBSD Release Engineering of Third Party Packages" 345.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 346.Re 347.Rs 348.%T "FreeBSD Developers' Handbook" 349.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 350.Re 351.Sh HISTORY 352.Fx 3531.x 354used a manual checklist, compiled by 355.An Rod Grimes , 356to produce a release. 357Apart from being incomplete, the list put a lot of specific demands on 358available filesystems and was quite torturous to execute. 359.Pp 360As part of the 361.Fx 2.0 362release engineering effort, significant 363effort was spent getting 364.Pa src/release/Makefile 365into a shape where it could at least automate most of the tediousness 366of building a release in a sterile environment. 367.Pp 368With its almost 1000 revisions spread over multiple branches, the 369.Xr cvs 1 370log of 371.Pa src/release/Makefile 372contains a vivid historical record of some 373of the hardships release engineers go through. 374.Sh AUTHORS 375.Pa src/release/Makefile 376was originally written by 377.An -nosplit 378.An Rod Grimes , 379.An Jordan Hubbard , 380and 381.An Poul-Henning Kamp . 382This manual page was written by 383.An Murray Stokely Aq murray@FreeBSD.org . 384