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.4 2005/08/05 10:13:43 swildner 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.Dx 36provides a complete build environment suitable for users to make 37full releases of the 38.Dx 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.Dx 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}/boot_crunch.conf 319.It Pa /usr/src/release/${arch}/fixit_crunch.conf 320.El 321.Sh EXAMPLES 322The following sequence of commands was used to build the 323.Fx 4.5 324release: 325.Bd -literal -offset indent 326cd /usr 327cvs co -rRELENG_4_5_0_RELEASE src 328cd src 329make buildworld 330cd release 331make release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\ 332 CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_5_0_RELEASE 333.Ed 334.Pp 335After running these commands, a complete system suitable for FTP or 336CD-ROM distribution is available in the 337.Pa /local3/release/R 338directory. 339.Pp 340The following sequence of commands can be used to build a 341.Dq "-CURRENT snapshot" 342of a 343locally modified source tree: 344.Bd -literal -offset indent 345cd /usr/src 346cvs diff -u > /path/to/local.patch 347make buildworld 348cd release 349make release CHROOTDIR=/local3/release BUILDNAME=5.0-CURRENT \\ 350 CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch 351.Ed 352.Sh SEE ALSO 353.Xr cc 1 , 354.Xr crunchgen 1 , 355.Xr cvs 1 , 356.Xr install 1 , 357.Xr make 1 , 358.Xr patch 1 , 359.Xr uname 1 , 360.Xr vn 4 , 361.Xr make.conf 5 , 362.Xr build 7 , 363.Xr ports 7 , 364.Xr chroot 8 , 365.Xr mtree 8 , 366.Xr sysctl 8 367.Rs 368.%T "FreeBSD Release Engineering" 369.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 370.Re 371.Rs 372.%T "FreeBSD Release Engineering of Third Party Packages" 373.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 374.Re 375.Rs 376.%T "FreeBSD Developers' Handbook" 377.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 378.Re 379.Sh HISTORY 380.Fx 3811.x 382used a manual checklist, compiled by 383.An Rod Grimes , 384to produce a release. 385Apart from being incomplete, the list put a lot of specific demands on 386available filesystems and was quite torturous to execute. 387.Pp 388As part of the 389.Fx 2.0 390release engineering effort, significant 391effort was spent getting 392.Pa src/release/Makefile 393into a shape where it could at least automate most of the tediousness 394of building a release in a sterile environment. 395.Pp 396With its almost 1000 revisions spread over multiple branches, the 397.Xr cvs 1 398log of 399.Pa src/release/Makefile 400contains a vivid historical record of some 401of the hardships release engineers go through. 402.Sh AUTHORS 403.Pa src/release/Makefile 404was originally written by 405.An -nosplit 406.An Rod Grimes , 407.An Jordan Hubbard , 408and 409.An Poul-Henning Kamp . 410This manual page was written by 411.An Murray Stokely Aq murray@FreeBSD.org . 412.Sh BUGS 413Infrastructure changes are occassionally made to the FreeBSD 414documentation set in such a way that release builds on security 415branches can fail. 416To work around this, release builds can be made to checkout the 417documentation from the last fully supported release of FreeBSD. 418For example: 419.Bd -literal -offset indent 420make release RELEASETAG=RELENG_4_5 DOCRELEASETAG=RELEASE_4_5_0 ... 421.Ed 422