1de26e0adSMurray Stokely.\" Copyright (c) 2002 2de26e0adSMurray Stokely.\" Murray Stokely <murray@FreeBSD.org> 3de26e0adSMurray Stokely.\" 4de26e0adSMurray Stokely.\" Redistribution and use in source and binary forms, with or without 5de26e0adSMurray Stokely.\" modification, are permitted provided that the following conditions 6de26e0adSMurray Stokely.\" are met: 7de26e0adSMurray Stokely.\" 1. Redistributions of source code must retain the above copyright 8de26e0adSMurray Stokely.\" notice, this list of conditions and the following disclaimer. 9de26e0adSMurray Stokely.\" 2. Redistributions in binary form must reproduce the above copyright 10de26e0adSMurray Stokely.\" notice, this list of conditions and the following disclaimer in the 11de26e0adSMurray Stokely.\" documentation and/or other materials provided with the distribution. 12de26e0adSMurray Stokely.\" 13de26e0adSMurray Stokely.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 14de26e0adSMurray Stokely.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15de26e0adSMurray Stokely.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16de26e0adSMurray Stokely.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 17de26e0adSMurray Stokely.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18de26e0adSMurray Stokely.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19de26e0adSMurray Stokely.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20de26e0adSMurray Stokely.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21de26e0adSMurray Stokely.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22de26e0adSMurray Stokely.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23de26e0adSMurray Stokely.\" SUCH DAMAGE. 24de26e0adSMurray Stokely.\" 25de26e0adSMurray Stokely.\" $FreeBSD$ 26de26e0adSMurray Stokely.\" 27de26e0adSMurray Stokely.Dd March 12, 2002 28de26e0adSMurray Stokely.Dt RELEASE 7 29de26e0adSMurray Stokely.Os 30de26e0adSMurray Stokely.Sh NAME 31de26e0adSMurray Stokely.Nm release 32994c71f0SMurray Stokely.Nd release building infrastructure 33de26e0adSMurray Stokely.Sh DESCRIPTION 34de26e0adSMurray Stokely.Fx 35de26e0adSMurray Stokelyprovides a complete build environment suitable for users to make 36de26e0adSMurray Stokelyfull releases of the 37de26e0adSMurray Stokely.Fx 38994c71f0SMurray Stokelyoperating system. 39de26e0adSMurray StokelyAll of the tools necessary to build a release are available from the 40de26e0adSMurray StokelyCVS repository in 41de26e0adSMurray Stokely.Pa src/release . 42de26e0adSMurray StokelyA complete release can actually be built with only a single command, 43de26e0adSMurray Stokelyincluding the creation of ISO images suitable for burning to CDROM, 44de26e0adSMurray Stokelyinstallation floppies, and an FTP install directory. 45de26e0adSMurray StokelyThis command is aptly named 46de26e0adSMurray Stokely.Dq make release . 47de26e0adSMurray Stokely.Pp 48de26e0adSMurray StokelyBefore attempting to build a release, the user is expected to be 49994c71f0SMurray Stokelyfamiliar with the contents of 50de26e0adSMurray Stokely.Xr build 7 , 51de26e0adSMurray Stokelyand should have experience upgrading systems from source with 52de26e0adSMurray Stokely.Dq make world . 53de26e0adSMurray StokelyThe release build process requires that 54de26e0adSMurray Stokely.Pa /usr/obj 55de26e0adSMurray Stokelybe populated with the output of 56de26e0adSMurray Stokely.Dq make buildworld . 57de26e0adSMurray StokelyThis is necessary so that the object files for a complete system can 58de26e0adSMurray Stokelybe installed into a clean 59de26e0adSMurray Stokely.Xr chroot 8 60de26e0adSMurray Stokelyenvironment. 61de26e0adSMurray StokelyThe release procedure also requires that the 62994c71f0SMurray Stokely.Xr md 4 63994c71f0SMurray Stokely(memory disk) device driver be present in the kernel 64994c71f0SMurray Stokely(either by being compiled in or loaded as a module). 65de26e0adSMurray Stokely.Pp 66de26e0adSMurray StokelyThis document does not cover source code management, quality 67de26e0adSMurray Stokelyassurance, or other aspects of the release engineering process. 68de26e0adSMurray Stokely.Sh TARGETS 69de26e0adSMurray StokelyThe release makefile 70994c71f0SMurray Stokely.Pq Pa src/release/Makefile 71de26e0adSMurray Stokelyis fairly abstruse. 72de26e0adSMurray StokelyMost developers will only be concerned with the 73994c71f0SMurray Stokely.Ar release 74de26e0adSMurray Stokelytarget. 75994c71f0SMurray Stokely.\" XXX: Some sort of introduction to this list? All the others have one. 76994c71f0SMurray Stokely.Bl -tag -width rerelease 77de26e0adSMurray Stokely.It Ar release 78de26e0adSMurray StokelyUses 79de26e0adSMurray Stokely.Dq make installworld 80de26e0adSMurray Stokelyto install a clean system into a 81de26e0adSMurray Stokely.Xr chroot 8 82de26e0adSMurray Stokelyenvironment on the filesystem. 83de26e0adSMurray StokelyChecks out the specified version of the source code and then rebuilds 84de26e0adSMurray Stokelythe entire system in the clean environment with 85de26e0adSMurray Stokely.Dq make world . 86de26e0adSMurray StokelyThe detailed steps that follow are then executed to package up the 87de26e0adSMurray Stokelydifferent distributions, build the installation floppy disks, build 88de26e0adSMurray Stokelyrelease documentation, and so on. 89de26e0adSMurray Stokely.It Ar rerelease 90de26e0adSMurray StokelyAssumes that the output of a release build has been manually modified, 91de26e0adSMurray Stokelyand performs the minimal number of steps to rebuild the release using 92de26e0adSMurray Stokelythe intermediate output of the previous 93de26e0adSMurray Stokely.Dq make release . 94de26e0adSMurray Stokely.El 95de26e0adSMurray Stokely.Pp 96de26e0adSMurray StokelyTargets called by 97994c71f0SMurray Stokely.Dq make release : 98994c71f0SMurray Stokely.Bl -tag -width release.9 99de26e0adSMurray Stokely.It Ar release.1 100de26e0adSMurray StokelyCleans out the 101de26e0adSMurray Stokely.Pa ${CHROOTDIR}/R 102de26e0adSMurray Stokelydirectory and uses 103de26e0adSMurray Stokely.Xr mtree 1 104de26e0adSMurray Stokelyto build the directory hierarchy for the system. 105de26e0adSMurray Stokely.It Ar release.2 106de26e0adSMurray StokelyInstalls the system into the distribution directories. 107de26e0adSMurray Stokely.It Ar release.3 108994c71f0SMurray Stokely.\" XXX: This should either be "GENERIC kernel" (singular) or 109994c71f0SMurray Stokely.\" XXX: "GENERIC and <some other> kernels". 110994c71f0SMurray StokelyMakes and installs the 111994c71f0SMurray Stokely.Pa GENERIC 112994c71f0SMurray Stokelykernel. 113de26e0adSMurray Stokely.It Ar release.4 114de26e0adSMurray StokelyUses 115de26e0adSMurray Stokely.Xr crunchgen 1 116de26e0adSMurray Stokelyto build 117de26e0adSMurray Stokely.Sq crunched 118de26e0adSMurray Stokelybinaries to live on the installation floppies. 119de26e0adSMurray Stokely.It Ar release.5 120de26e0adSMurray StokelyBuilds synthetic distributions, and cleans up the previously built 121de26e0adSMurray Stokelydistribution trees. 122de26e0adSMurray Stokely.It Ar release.6 123de26e0adSMurray StokelyCreates tarballs of the assembled distribution trees. 124de26e0adSMurray Stokely.It Ar release.7 125de26e0adSMurray StokelyMakes source distributions. 126de26e0adSMurray Stokely.It Ar release.8 127de26e0adSMurray StokelyCreates the boot and MFS root floppies. 128de26e0adSMurray Stokely.It Ar release.9 129de26e0adSMurray StokelyCreates the fixit floppy. 130de26e0adSMurray Stokely.It Ar ftp.1 131de26e0adSMurray StokelySets up a suitable area for FTP installations. 132de26e0adSMurray Stokely.It Ar cdrom.1 133de26e0adSMurray StokelySets up a suitable area to build CDROM images. 134de26e0adSMurray Stokely.It Ar iso.1 135de26e0adSMurray StokelyBuilds two ISO images (installation and 136de26e0adSMurray Stokely.Sq live 137994c71f0SMurray Stokelyfilesystem) from the CDROM release area 138994c71f0SMurray Stokely(Disabled by default, see 139994c71f0SMurray Stokely.Pa MAKE_ISOS 140994c71f0SMurray Stokelybelow). 141de26e0adSMurray Stokely.It Ar doc.1 142994c71f0SMurray StokelyBuilds all of the necessary tools to turn the 143994c71f0SMurray Stokely.Fx 144994c71f0SMurray StokelyDocumentation Project source documents (SGML, XML) into HTML 145994c71f0SMurray Stokelyand text documents that will accompany the release. 146994c71f0SMurray StokelyAlso, builds and installs the actual user documentation. 147994c71f0SMurray StokelyThis includes the Handbook, FAQ, articles, and so on. 148de26e0adSMurray Stokely.It Ar doc.2 149994c71f0SMurray StokelyBuilds the release documentation. 150994c71f0SMurray StokelyThis includes the release notes, 151de26e0adSMurray Stokelyhardware guide, and installation instructions. 152de26e0adSMurray Stokely.El 153de26e0adSMurray Stokely.Sh ENVIRONMENT 154994c71f0SMurray StokelyVariables that must be specified: 155994c71f0SMurray Stokely.Bl -tag -width RELEASETAG 156de26e0adSMurray Stokely.It Ev CHROOTDIR 157de26e0adSMurray StokelyThe directory to be used as the 158de26e0adSMurray Stokely.Xr chroot 8 159de26e0adSMurray Stokelyenvironment for the entire release build. 160994c71f0SMurray Stokely.\" XXX: I recommend against hardcoding specific numbers like "2.3" here; 161994c71f0SMurray Stokely.\" XXX: perhaps it should be replaced with something to the effect of 162994c71f0SMurray Stokely.\" XXX: "we don't know how much space you'll need, but make sure you have 163994c71f0SMurray Stokely.\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number, 164994c71f0SMurray Stokely.\" XXX: but at least it looks less like a decree and more like an estimate. 165de26e0adSMurray StokelyThis filesystem should have at least 2.3 gigabytes of free space on the 166de26e0adSMurray Stokelyi386 architecture. 167de26e0adSMurray Stokely.It Ev BUILDNAME 168994c71f0SMurray StokelyThe name of the release to be built. 169994c71f0SMurray StokelyThis is used to set the 170994c71f0SMurray Stokely.Dv RELEASE 171de26e0adSMurray Stokelyvalue in 172de26e0adSMurray Stokely.Pa sys/conf/newvers.sh , 173de26e0adSMurray Stokelywhich affects the output of 174de26e0adSMurray Stokely.Xr uname 1 . 175de26e0adSMurray Stokely.It Ev CVSROOT 176994c71f0SMurray StokelyThe location of the 177994c71f0SMurray Stokely.Fx 178994c71f0SMurray StokelyCVS repository. 179de26e0adSMurray Stokely.It Ev RELEASETAG 180994c71f0SMurray StokelyThe CVS tag corresponding to the release that is to be built. 181de26e0adSMurray StokelyIf undefined, the release will be built from the HEAD of the CVS tree 182de26e0adSMurray Stokely(a 183994c71f0SMurray Stokely.Sq -CURRENT snapshot ) . 184de26e0adSMurray Stokely.El 185de26e0adSMurray Stokely.Pp 186de26e0adSMurray StokelyOptional variables: 187994c71f0SMurray Stokely.Bl -tag -width RELEASEDISTFILES 188de26e0adSMurray Stokely.It Ev LOCAL_PATCHES 189de26e0adSMurray StokelyA patch file against 190de26e0adSMurray Stokely.Pa /usr/src 191de26e0adSMurray Stokelythat will be applied in the 192de26e0adSMurray Stokely.Xr chroot 8 193de26e0adSMurray Stokelyenvironment before the release build begins. 194de26e0adSMurray Stokely.It Ev PATCH_FLAGS 195de26e0adSMurray StokelyArguments for the 196de26e0adSMurray Stokely.Xr patch 1 197de26e0adSMurray Stokelycommand used to apply 198994c71f0SMurray Stokely.Ev LOCAL_PATCHES . 199de26e0adSMurray Stokely.It Ev MAKE_ISOS 200de26e0adSMurray StokelyIf defined, bootable ISO CDROM images will be created from the 201de26e0adSMurray Stokelycontents of the CDROM stage directory. 202de26e0adSMurray Stokely.It Ev NODOC 203de26e0adSMurray StokelyIf set to 204de26e0adSMurray Stokely.Dq YES 205994c71f0SMurray Stokelythen the documentation will not be built. 206994c71f0SMurray StokelyDue to the SGML-based 207de26e0adSMurray Stokelytoolchain and multiple languages supported by the 208de26e0adSMurray Stokely.Fx 209994c71f0SMurray StokelyDocumentation Project, this may speed up the release build considerably. 210de26e0adSMurray Stokely.It Ev NOPORTS 211de26e0adSMurray StokelyIf set to 212de26e0adSMurray Stokely.Dq YES 213de26e0adSMurray Stokelythen the ports tree will be omitted from the release. 214de26e0adSMurray Stokely.It Ev RELEASEDISTFILES 215de26e0adSMurray StokelyThe directory where the distribution files for ports required by the 216de26e0adSMurray Stokelyrelease build can be found. 217de26e0adSMurray StokelyThis may save a significant amount of time over downloading the 218de26e0adSMurray Stokelydistfiles through a slow link. 219de26e0adSMurray Stokely.It Ev RELEASENOUPDATE 220de26e0adSMurray StokelyIf this variable is defined for 221de26e0adSMurray Stokely.Dq make rerelease , 222de26e0adSMurray Stokelythe source code will not be updated with 223de26e0adSMurray Stokely.Dq cvs up . 224de26e0adSMurray Stokely.El 225de26e0adSMurray Stokely.Sh FILES 226de26e0adSMurray Stokely.Bl -tag -compact 227de26e0adSMurray Stokely.It Pa /etc/make.conf 228de26e0adSMurray Stokely.It Pa /usr/doc/Makefile 229de26e0adSMurray Stokely.It Pa /usr/doc/share/mk/doc.project.mk 230de26e0adSMurray Stokely.It Pa /usr/ports/Mk/bsd.port.mk 231de26e0adSMurray Stokely.It Pa /usr/ports/Mk/bsd.sites.mk 232de26e0adSMurray Stokely.It Pa /usr/share/examples/etc/make.conf 233de26e0adSMurray Stokely.It Pa /usr/src/Makefile 234de26e0adSMurray Stokely.It Pa /usr/src/Makefile.inc1 235de26e0adSMurray Stokely.It Pa /usr/src/release/Makefile 236de26e0adSMurray Stokely.It Pa /usr/src/release/${arch}/drivers.conf 237de26e0adSMurray Stokely.It Pa /usr/src/release/${arch}/boot_crunch.conf 238de26e0adSMurray Stokely.It Pa /usr/src/release/${arch}/fixit_crunch.conf 239de26e0adSMurray Stokely.El 240de26e0adSMurray Stokely.Sh EXAMPLES 241994c71f0SMurray StokelyThe following sequence of commands was used to build the 242de26e0adSMurray Stokely.Fx 4.5 243de26e0adSMurray Stokelyrelease: 244de26e0adSMurray Stokely.Bd -literal -offset indent 245de26e0adSMurray Stokelycd /usr 246de26e0adSMurray Stokelycvs co -rRELENG_4_5_0_RELEASE src 247de26e0adSMurray Stokelycd src 248de26e0adSMurray Stokelymake buildworld 249de26e0adSMurray Stokelycd release 250de26e0adSMurray Stokelymake release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\ 251de26e0adSMurray Stokely CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_5_0_RELEASE 252de26e0adSMurray Stokely.Ed 253de26e0adSMurray Stokely.Pp 254de26e0adSMurray StokelyAfter running these commands, a complete system suitable for FTP or 255de26e0adSMurray StokelyCDROM distribution is available in the 256994c71f0SMurray Stokely.Pa /local3/release/R 257de26e0adSMurray Stokelydirectory. 258de26e0adSMurray Stokely.Pp 259994c71f0SMurray StokelyThe following sequence of commands can be used to build a 260994c71f0SMurray Stokely.Sq -CURRENT snapshot 261994c71f0SMurray Stokelyof a 262de26e0adSMurray Stokelylocally modified source tree: 263de26e0adSMurray Stokely.Bd -literal -offset indent 264de26e0adSMurray Stokelycd /usr/src 265de26e0adSMurray Stokelycvs diff -u > /path/to/local.patch 266de26e0adSMurray Stokelymake buildworld 267de26e0adSMurray Stokelycd release 268de26e0adSMurray Stokelymake release CHROOTDIR=/local3/release BUILDNAME=5.0-SNAPSHOT \\ 269de26e0adSMurray Stokely CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch 270de26e0adSMurray Stokely.Ed 271de26e0adSMurray Stokely.Sh SEE ALSO 272de26e0adSMurray Stokely.Xr cc 1 , 273de26e0adSMurray Stokely.Xr crunchgen 1 , 274de26e0adSMurray Stokely.Xr install 1 , 275de26e0adSMurray Stokely.Xr make 1 , 276de26e0adSMurray Stokely.Xr mtree 1 , 277de26e0adSMurray Stokely.Xr patch 1 , 278de26e0adSMurray Stokely.Xr uname 1 , 279de26e0adSMurray Stokely.Xr make.conf 5 , 280de26e0adSMurray Stokely.Xr build 7 , 281de26e0adSMurray Stokely.Xr ports 7 , 282de26e0adSMurray Stokely.Xr chroot 8 283994c71f0SMurray Stokely.Rs 284994c71f0SMurray Stokely.%T FreeBSD Release Engineering 285994c71f0SMurray Stokely.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 286994c71f0SMurray Stokely.Re 287994c71f0SMurray Stokely.Rs 288994c71f0SMurray Stokely.%T FreeBSD Release Engineering of Third Party Packages 289994c71f0SMurray Stokely.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 290994c71f0SMurray Stokely.Re 291994c71f0SMurray Stokely.Rs 292994c71f0SMurray Stokely.%T FreeBSD Developers' Handbook 293994c71f0SMurray Stokely.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 294994c71f0SMurray Stokely.Re 295de26e0adSMurray Stokely.Sh HISTORY 296de26e0adSMurray Stokely.Fx 297de26e0adSMurray Stokely1.x 298994c71f0SMurray Stokelyused a manual checklist, compiled by Rod Grimes, to produce a release. 299de26e0adSMurray StokelyApart from being incomplete, the list put a lot of specific demands on 300de26e0adSMurray Stokelyavailable filesystems and was quite torturous to execute. 301de26e0adSMurray Stokely.Pp 302994c71f0SMurray StokelyAs part of the 303994c71f0SMurray Stokely.Fx 2.0 304994c71f0SMurray Stokelyrelease engineering effort, significant 305de26e0adSMurray Stokelyeffort was spent getting 306de26e0adSMurray Stokely.Pa src/release/Makefile 307de26e0adSMurray Stokelyinto a shape where it could at least automate most of the tediousness 308de26e0adSMurray Stokelyof building a release in a sterile environment. 309de26e0adSMurray Stokely.Pp 310994c71f0SMurray StokelyWith its almost 1000 revisions spread over multiple branches, the CVS 311994c71f0SMurray Stokelylog of 312994c71f0SMurray Stokely.Pa src/release/Makefile 313994c71f0SMurray Stokelycontains a vivid historical record of some 314de26e0adSMurray Stokelyof the hardships release engineers go through. 315de26e0adSMurray Stokely.Sh AUTHORS 316de26e0adSMurray Stokely.Pa src/release/Makefile 317994c71f0SMurray Stokelywas originally written by Rod Grimes, Jordan Hubbard, and Poul-Henning Kamp. 318994c71f0SMurray StokelyThis manual page was written by 319de26e0adSMurray Stokely.An Murray Stokely Aq murray@FreeBSD.org . 320