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: src/share/man/man7/release.7,v 1.3.2.6 2003/04/12 20:42:30 murray Exp $ 26.\" $DragonFly: src/share/man/man7/release.7,v 1.2 2003/06/17 04:37:00 dillon Exp $ 27.\" 28.Dd March 12, 2002 29.Dt RELEASE 7 30.Os 31.Sh NAME 32.Nm release 33.Nd "release building infrastructure" 34.Sh DESCRIPTION 35.Fx 36provides a complete build environment suitable for users to make 37full releases of the 38.Fx 39operating system. 40All of the tools necessary to build a release are available from the 41CVS repository in 42.Pa src/release . 43A complete release can actually be built with only a single command, 44including the creation of ISO images suitable for burning to CD-ROM, 45installation floppies, and an FTP install directory. 46This command is aptly named 47.Dq Li "make release" . 48.Pp 49Before attempting to build a release, the user is expected to be 50familiar with the contents of 51.Xr build 7 , 52and should have experience upgrading systems from source with 53.Dq Li "make world" . 54The release build process requires that 55.Pa /usr/obj 56be populated with the output of 57.Dq Li "make buildworld" . 58This is necessary so that the object files for a complete system can 59be installed into a clean 60.Xr chroot 8 61environment. 62The release procedure also requires that the 63.Xr vn 4 64(vnode disk) device driver be present in the kernel 65(either by being compiled in or loaded as a module). 66.Pp 67This document does not cover source code management, quality 68assurance, or other aspects of the release engineering process. 69.Sh TARGETS 70The release makefile 71.Pq Pa src/release/Makefile 72is fairly abstruse. 73Most developers will only be concerned with the 74.Cm release 75target. 76.\" XXX: Some sort of introduction to this list? All the others have one. 77.Bl -tag -width ".Cm rerelease" 78.It Cm release 79Uses 80.Dq Li "make installworld" 81to install a clean system into a 82.Xr chroot 8 83environment on the filesystem. 84Checks out the specified version of the source code and then rebuilds 85the entire system in the clean environment with 86.Dq Li "make world" . 87The detailed steps that follow are then executed to package up the 88different distributions, build the installation floppy disks, build 89release documentation, and so on. 90.Pp 91This target must be built as root with the 92.Va kern.securelevel 93sysctl set to -1 94.Pq "the default". 95.It Cm rerelease 96Assumes that the output of a release build has been manually modified, 97and performs the minimal number of steps to rebuild the release using 98the intermediate output of the previous 99.Dq Li "make release" . 100.It Cm floppies 101Generate a new set of boot floppies. 102This will call the 103.Cm release.5 , 104.Cm release.9 , 105and 106.Cm release.10 107targets to re-generate the floppy images of a previous 108.Dq Li "make release" . 109This is most often used to build custom boot floppies. 110.El 111.Pp 112Targets called by 113.Dq Li "make release" : 114.Bl -tag -width ".Cm release.10" 115.It Cm release.1 116Cleans out the 117.Pa ${CHROOTDIR}/R 118directory and uses 119.Xr mtree 8 120to build the directory hierarchy for the system. 121.It Cm release.2 122Installs the system into the distribution directories. 123.It Cm release.3 124Builds and installs 125.Dq crypto , 126.Dq krb4 127and 128.Dq krb5 129distributions. 130.It Cm release.4 131.\" XXX: We build more than one kernel. We build a stripped down 132.\" kernel for the boot media in addition to a full GENERIC kernel. 133Makes and installs the 134.Pa GENERIC 135kernel. 136.It Cm release.5 137Uses 138.Xr crunchgen 1 139to build 140.Dq crunched 141binaries to live on the installation floppies. 142.It Cm release.6 143Builds synthetic distributions, and cleans up the previously built 144distribution trees. 145.It Cm release.7 146Creates tarballs of the assembled distribution trees. 147.It Cm release.8 148Makes source distributions. 149.It Cm release.9 150Creates the boot and MFS root floppies. 151.It Cm release.10 152Creates the fixit floppy. 153.It Cm ftp.1 154Sets up a suitable area for FTP installations in 155.Pa ${CHROOTDIR}/R/ftp . 156.It Cm cdrom.1 157Sets up a suitable area to build CD-ROM images in 158.Pa ${CHROOTDIR}/R/cdrom . 159.It Cm iso.1 160Builds two ISO images (installation and 161.Dq live 162filesystem) from the CD-ROM release area 163(disabled by default, see 164.Va MAKE_ISOS 165below). 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 RELEASETAG" 181.It Va CHROOTDIR 182The directory to be used as the 183.Xr chroot 8 184environment for the entire release build. 185.\" XXX: I recommend against hardcoding specific numbers like "2.3" here; 186.\" XXX: perhaps it should be replaced with something to the effect of 187.\" XXX: "we don't know how much space you'll need, but make sure you have 188.\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number, 189.\" XXX: but at least it looks less like a decree and more like an estimate. 190This filesystem should have at least 2.3 gigabytes of free space on the 191i386 architecture. 192.It Va BUILDNAME 193The name of the release to be built. 194This is used to set the 195.Va RELEASE 196value in 197.Pa sys/conf/newvers.sh , 198which affects the output of 199.Xr uname 1 . 200.It Va CVSROOT 201The location of the 202.Fx 203CVS repository. 204This path name is referenced to the real system root, 205.Em not 206the root of the 207.Xr chroot 8 208directory tree. 209.It Va RELEASETAG 210The CVS tag corresponding to the release that is to be built. 211If undefined, the release will be built from the 212.Dv HEAD 213of the CVS tree 214(a 215.Dq "-CURRENT snapshot" ) . 216.El 217.Pp 218Optional variables: 219.Bl -tag -width ".Va RELEASEDISTFILES" 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 LOCAL_PATCHES 237A patch file against 238.Pa /usr/src 239that will be applied in the 240.Xr chroot 8 241environment before the release build begins. 242.It Va PATCH_FLAGS 243Arguments for the 244.Xr patch 1 245command used to apply 246.Va LOCAL_PATCHES 247patch file. 248.It Va LOCAL_SCRIPT 249A script that will be run in the 250.Xr chroot 8 251environment immediately after any local patches are applied. 252.It Va MAKE_ISOS 253If defined, bootable ISO CD-ROM images will be created from the 254contents of the CD-ROM stage directory. 255.It Va NODOC 256If set to 257.Dq Li YES , 258the SGML-based documentation from the 259.Fx 260Documentation Project will not be built. 261However, the 262.Dq doc 263distribution will still be created with the minimal documentation set 264provided in 265.Pa src/share/doc . 266.It Va NOPORTS 267If set to 268.Dq Li YES 269then the Ports Collection will be omitted from the release. 270.It Va NOPORTREADMES 271If defined, readme files will not be created for each individual port 272in the Ports Collection. 273The default behavior is for 274.Dq Li "make release" 275to run 276.Dq Li "make readmes" 277from 278.Pa ${CHROOTDIR}/usr/ports , 279which can be a very time consuming operation. 280.It Va RELEASEDISTFILES 281The directory where the distribution files for ports required by the 282release build can be found. 283This may save a significant amount of time over downloading the 284distfiles through a slow link. 285.It Va RELEASENOUPDATE 286If this variable is defined for 287.Dq Li "make rerelease" , 288the source code will not be updated with 289.Dq Li "cvs update" . 290.It Va TARGET_ARCH 291The target machine processor architecture. 292This is analogous to the 293.Dq Nm uname Fl p 294output. 295Set this to cross-build for a different architecture. 296.It Va TARGET 297The target hardware platform. 298This is analogous to the 299.Dq Nm uname Fl m 300output. 301This is necessary to cross-build some target architectures. 302For example, cross-building for PC98 machines requires 303.Va TARGET_ARCH Ns = Ns Li i386 304and 305.Va TARGET Ns = Ns Li pc98 . 306.El 307.Sh FILES 308.Bl -tag -compact 309.It Pa /etc/make.conf 310.It Pa /usr/doc/Makefile 311.It Pa /usr/doc/share/mk/doc.project.mk 312.It Pa /usr/ports/Mk/bsd.port.mk 313.It Pa /usr/ports/Mk/bsd.sites.mk 314.It Pa /usr/share/examples/etc/make.conf 315.It Pa /usr/src/Makefile 316.It Pa /usr/src/Makefile.inc1 317.It Pa /usr/src/release/Makefile 318.It Pa /usr/src/release/${arch}/drivers.conf 319.It Pa /usr/src/release/${arch}/boot_crunch.conf 320.It Pa /usr/src/release/${arch}/fixit_crunch.conf 321.El 322.Sh EXAMPLES 323The following sequence of commands was used to build the 324.Fx 4.5 325release: 326.Bd -literal -offset indent 327cd /usr 328cvs co -rRELENG_4_5_0_RELEASE src 329cd src 330make buildworld 331cd release 332make release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\ 333 CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_5_0_RELEASE 334.Ed 335.Pp 336After running these commands, a complete system suitable for FTP or 337CD-ROM distribution is available in the 338.Pa /local3/release/R 339directory. 340.Pp 341The following sequence of commands can be used to build a 342.Dq "-CURRENT snapshot" 343of a 344locally modified source tree: 345.Bd -literal -offset indent 346cd /usr/src 347cvs diff -u > /path/to/local.patch 348make buildworld 349cd release 350make release CHROOTDIR=/local3/release BUILDNAME=5.0-CURRENT \\ 351 CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch 352.Ed 353.Sh SEE ALSO 354.Xr cc 1 , 355.Xr crunchgen 1 , 356.Xr cvs 1 , 357.Xr install 1 , 358.Xr make 1 , 359.Xr patch 1 , 360.Xr uname 1 , 361.Xr vn 4 , 362.Xr drivers.conf 5 , 363.Xr make.conf 5 , 364.Xr build 7 , 365.Xr ports 7 , 366.Xr chroot 8 , 367.Xr mtree 8 , 368.Xr sysctl 8 369.Rs 370.%T "FreeBSD Release Engineering" 371.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 372.Re 373.Rs 374.%T "FreeBSD Release Engineering of Third Party Packages" 375.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 376.Re 377.Rs 378.%T "FreeBSD Developers' Handbook" 379.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 380.Re 381.Sh HISTORY 382.Fx 3831.x 384used a manual checklist, compiled by 385.An Rod Grimes , 386to produce a release. 387Apart from being incomplete, the list put a lot of specific demands on 388available filesystems and was quite torturous to execute. 389.Pp 390As part of the 391.Fx 2.0 392release engineering effort, significant 393effort was spent getting 394.Pa src/release/Makefile 395into a shape where it could at least automate most of the tediousness 396of building a release in a sterile environment. 397.Pp 398With its almost 1000 revisions spread over multiple branches, the 399.Xr cvs 1 400log of 401.Pa src/release/Makefile 402contains a vivid historical record of some 403of the hardships release engineers go through. 404.Sh AUTHORS 405.Pa src/release/Makefile 406was originally written by 407.An -nosplit 408.An Rod Grimes , 409.An Jordan Hubbard , 410and 411.An Poul-Henning Kamp . 412This manual page was written by 413.An Murray Stokely Aq murray@FreeBSD.org . 414.Sh BUGS 415Infrastructure changes are occassionally made to the FreeBSD 416documentation set in such a way that release builds on security 417branches can fail. 418To work around this, release builds can be made to checkout the 419documentation from the last fully supported release of FreeBSD. 420For example: 421.Bd -literal -offset indent 422make release RELEASETAG=RELENG_4_5 DOCRELEASETAG=RELEASE_4_5_0 ... 423.Ed 424