1 .\" Copyright (c) 2002 Murray Stokely <murray@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
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.3 2004/03/11 12:28:56 hmp Exp $
33 .Nd "release building infrastructure"
36 provides a complete build environment suitable for users to make
40 All of the tools necessary to build a release are available from the
43 A complete release can actually be built with only a single command,
44 including the creation of ISO images suitable for burning to CD-ROM,
45 installation floppies, and an FTP install directory.
46 This command is aptly named
47 .Dq Li "make release" .
49 Before attempting to build a release, the user is expected to be
50 familiar with the contents of
52 and should have experience upgrading systems from source with
54 The release build process requires that
56 be populated with the output of
57 .Dq Li "make buildworld" .
58 This is necessary so that the object files for a complete system can
59 be installed into a clean
62 The release procedure also requires that the
64 (vnode disk) device driver be present in the kernel
65 (either by being compiled in or loaded as a module).
67 This document does not cover source code management, quality
68 assurance, or other aspects of the release engineering process.
71 .Pq Pa src/release/Makefile
73 Most developers will only be concerned with the
76 .\" XXX: Some sort of introduction to this list? All the others have one.
77 .Bl -tag -width ".Cm rerelease"
80 .Dq Li "make installworld"
81 to install a clean system into a
83 environment on the filesystem.
84 Checks out the specified version of the source code and then rebuilds
85 the entire system in the clean environment with
87 The detailed steps that follow are then executed to package up the
88 different distributions, build the installation floppy disks, build
89 release documentation, and so on.
91 This target must be built as root with the
96 Assumes that the output of a release build has been manually modified,
97 and performs the minimal number of steps to rebuild the release using
98 the intermediate output of the previous
99 .Dq Li "make release" .
101 Generate a new set of boot floppies.
107 targets to re-generate the floppy images of a previous
108 .Dq Li "make release" .
109 This is most often used to build custom boot floppies.
113 .Dq Li "make release" :
114 .Bl -tag -width ".Cm release.10"
120 to build the directory hierarchy for the system.
122 Installs the system into the distribution directories.
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.
133 Makes and installs the
141 binaries to live on the installation floppies.
143 Builds synthetic distributions, and cleans up the previously built
146 Creates tarballs of the assembled distribution trees.
148 Makes source distributions.
150 Creates the boot and MFS root floppies.
152 Creates the fixit floppy.
154 Sets up a suitable area for FTP installations in
155 .Pa ${CHROOTDIR}/R/ftp .
157 Sets up a suitable area to build CD-ROM images in
158 .Pa ${CHROOTDIR}/R/cdrom .
160 Builds two ISO images (installation and
162 filesystem) from the CD-ROM release area
163 (disabled by default, see
167 Builds all of the necessary tools to turn the
169 Documentation Project source documents (SGML, XML) into HTML
170 and text documents that will accompany the release.
171 Also, builds and installs the actual user documentation.
172 This includes the Handbook, FAQ, articles, and so on.
174 Builds the release documentation.
175 This includes the release notes,
176 hardware guide, and installation instructions.
179 Variables that must be specified:
180 .Bl -tag -width ".Va RELEASETAG"
182 The directory to be used as the
184 environment 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.
190 This filesystem should have at least 2.3 gigabytes of free space on the
193 The name of the release to be built.
194 This is used to set the
197 .Pa sys/conf/newvers.sh ,
198 which affects the output of
204 This path name is referenced to the real system root,
210 The CVS tag corresponding to the release that is to be built.
211 If undefined, the release will be built from the
215 .Dq "-CURRENT snapshot" ) .
219 .Bl -tag -width ".Va RELEASEDISTFILES"
221 Additional arguments for
227 For example, setting this variable to
228 .Dq Li "-D '01/01/2002 00:00:00 GMT'"
230 .Dq Li "make release"
232 .Dq Li "make rerelease"
235 to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively.
239 that will be applied in the
241 environment before the release build begins.
245 command used to apply
249 A script that will be run in the
251 environment immediately after any local patches are applied.
253 If defined, bootable ISO CD-ROM images will be created from the
254 contents of the CD-ROM stage directory.
258 the SGML-based documentation from the
260 Documentation Project will not be built.
263 distribution will still be created with the minimal documentation set
269 then the Ports Collection will be omitted from the release.
271 If defined, readme files will not be created for each individual port
272 in the Ports Collection.
273 The default behavior is for
274 .Dq Li "make release"
276 .Dq Li "make readmes"
278 .Pa ${CHROOTDIR}/usr/ports ,
279 which can be a very time consuming operation.
280 .It Va RELEASEDISTFILES
281 The directory where the distribution files for ports required by the
282 release build can be found.
283 This may save a significant amount of time over downloading the
284 distfiles through a slow link.
285 .It Va RELEASENOUPDATE
286 If this variable is defined for
287 .Dq Li "make rerelease" ,
288 the source code will not be updated with
289 .Dq Li "cvs update" .
291 The target machine processor architecture.
292 This is analogous to the
295 Set this to cross-build for a different architecture.
297 The target hardware platform.
298 This is analogous to the
301 This is necessary to cross-build some target architectures.
302 For example, cross-building for PC98 machines requires
303 .Va TARGET_ARCH Ns = Ns Li i386
305 .Va TARGET Ns = Ns Li pc98 .
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
323 The following sequence of commands was used to build the
326 .Bd -literal -offset indent
328 cvs co -rRELENG_4_5_0_RELEASE src
332 make release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\
333 CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_5_0_RELEASE
336 After running these commands, a complete system suitable for FTP or
337 CD-ROM distribution is available in the
338 .Pa /local3/release/R
341 The following sequence of commands can be used to build a
342 .Dq "-CURRENT snapshot"
344 locally modified source tree:
345 .Bd -literal -offset indent
347 cvs diff -u > /path/to/local.patch
350 make release CHROOTDIR=/local3/release BUILDNAME=5.0-CURRENT \\
351 CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
370 .%T "FreeBSD Release Engineering"
371 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
374 .%T "FreeBSD Release Engineering of Third Party Packages"
375 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
378 .%T "FreeBSD Developers' Handbook"
379 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
384 used a manual checklist, compiled by
386 to produce a release.
387 Apart from being incomplete, the list put a lot of specific demands on
388 available filesystems and was quite torturous to execute.
392 release engineering effort, significant
393 effort was spent getting
394 .Pa src/release/Makefile
395 into a shape where it could at least automate most of the tediousness
396 of building a release in a sterile environment.
398 With its almost 1000 revisions spread over multiple branches, the
401 .Pa src/release/Makefile
402 contains a vivid historical record of some
403 of the hardships release engineers go through.
405 .Pa src/release/Makefile
406 was originally written by
411 .An Poul-Henning Kamp .
412 This manual page was written by
413 .An Murray Stokely Aq murray@FreeBSD.org .
415 Infrastructure changes are occassionally made to the FreeBSD
416 documentation set in such a way that release builds on security
418 To work around this, release builds can be made to checkout the
419 documentation from the last fully supported release of FreeBSD.
421 .Bd -literal -offset indent
422 make release RELEASETAG=RELENG_4_5 DOCRELEASETAG=RELEASE_4_5_0 ...