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
32 .Nd "release building infrastructure"
35 provides a complete build environment suitable for users to make
39 All of the tools necessary to build a release are available from the
42 A complete release can actually be built with only a single command,
43 including the creation of ISO images suitable for burning to CD-ROM,
44 installation floppies, and an FTP install directory.
45 This command is aptly named
46 .Dq Li "make release" .
48 Before attempting to build a release, the user is expected to be
49 familiar with the contents of
51 and should have experience upgrading systems from source.
52 The release build process requires that
54 be populated with the output of
56 .Dq Li "make buildworld"
57 compiled from sources matching the currently running kernel.
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 (memory disk) device driver be present in the kernel
65 (either by being compiled in or available 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 file system.
84 Checks out the specified version of the source code and then rebuilds
85 the entire system in the clean environment with
86 .Dq Li "make buildworld" .
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
93 sysctl set to \-1 (the default).
95 Assumes that the output of a release build has been manually modified,
96 and performs the minimal number of steps to rebuild the release using
97 the intermediate output of the previous
98 .Dq Li "make release" .
100 Generate a new set of boot and fixit floppies.
108 targets to re-generate the floppy images of a previous
109 .Dq Li "make release" .
110 This is most often used to build custom boot floppies.
114 .Dq Li "make release" :
115 .Bl -tag -width ".Cm fetch-distfiles"
121 to build the directory hierarchy for the system.
123 Installs the system into the distribution directories.
125 Makes and installs the
127 kernel as well as any other kernels listed in
134 binaries to live on the installation floppies.
136 Builds synthetic distributions, and cleans up the previously built
139 Creates tarballs of the assembled distribution trees.
141 Makes source distributions.
143 Creates the MFS root file systems.
145 Creates the boot and kernel floppies.
147 Creates the fixit floppy.
150 .Pa ${CHROORDIR}/R/ftp/stage/floppies
153 Sets up a suitable area for FTP installations in
154 .Pa ${CHROOTDIR}/R/ftp .
156 Sets up a suitable area to build CD-ROM images in
157 .Pa ${CHROOTDIR}/R/cdrom .
159 Builds ISO images (installation and
161 file system) from the CD-ROM release area
162 (disabled by default, see
165 .It Cm fetch-distfiles
166 Fetches distfiles needed during the release build that are not already in
167 .Va RELEASEDISTFILES .
169 Builds all of the necessary tools to turn the
171 Documentation Project source documents (SGML, XML) into HTML
172 and text documents that will accompany the release.
173 Also, builds and installs the actual user documentation.
174 This includes the Handbook, FAQ, articles, and so on.
176 Builds the release documentation.
177 This includes the release notes,
178 hardware guide, and installation instructions.
181 Variables that must be specified:
182 .Bl -tag -width ".Va BUILDNAME"
184 The name of the release to be built.
185 This is used to set the
188 .Pa sys/conf/newvers.sh ,
189 which affects the output of
192 The directory to be used as the
194 environment for the entire release build.
195 .\" XXX: I recommend against hardcoding specific numbers like "2.3" here;
196 .\" XXX: perhaps it should be replaced with something to the effect of
197 .\" XXX: "we don't know how much space you'll need, but make sure you have
198 .\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number,
199 .\" XXX: but at least it looks less like a decree and more like an estimate.
200 This file system should have at least 3.2 gigabytes of free space on the
206 This path name is in reference to the real system root,
214 .Bl -tag -width ".Va NO_PREFETCHDISTFILES"
216 Additional arguments for
222 For example, setting this variable to
223 .Dq Li "-D '01/01/2002 00:00:00 GMT'"
225 .Dq Li "make release"
227 .Dq Li "make rerelease"
230 to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively.
232 The list of languages and encodings the SGML-based documentation
234 If not set, the documentation is built for all available languages.
236 The CVS tag to use when checking out the documentation tree.
238 the head of the documentation tree is used by default.
241 specifies a release tag,
242 then the associated release version is used as the default instead.
244 The directory that will be copied to
245 .Pa ${CHROOTDIR}/usr/local .
247 The directory specified by this variable will be copied into
248 .Pa ${CHROOTDIR}/usr/src
249 instead of that directory being populated by a CVS checkout.
252 this will NOT be copied; cvs update will be used instead.
254 The contents of this variable are passed to
256 when building kernels during the release build.
257 For example, setting this variable to
261 to execute up to four processes at a time.
263 Specifies a list of additional kernel configurations to compile and
267 Each kernel is installed into
269 so that it can be booted from the loader via
270 .Dq Li "boot <config>" .
274 that will be applied in the
276 environment before the release build begins.
280 command used to apply
284 A script that will be run in the
286 environment immediately after any local patches are applied.
288 If defined, bootable ISO CD-ROM images will be created from the
289 contents of the CD-ROM stage directory.
291 The label used for the CD-ROM created from the disc1 contents, the
292 default label will be
293 .Dq Li fbsd_miniinst .
295 The name used as part of the ISO file name for the CD-ROM created from
296 the disc1 contents, the default will be
299 The label used for the CD-ROM created from the disc2 contents, the
300 default label will be
303 The name used as part of the ISO file name for the CD-ROM created from
304 the disc2 contents, the default will be
307 If defined, the CD-ROM stage directories will not be created.
309 If defined, the SGML-based documentation from the
311 Documentation Project will not be built.
314 distribution will still be created with the minimal documentation set
318 If defined, no boot and fixit floppy disk images will be created (for those
319 platforms supporting them).
321 If defined, the Ports Collection will be omitted from the release.
323 If defined, readme files will not be created for each individual port
324 in the Ports Collection.
325 The default behavior is for
326 .Dq Li "make release"
328 .Dq Li "make readmes"
330 .Pa ${CHROOTDIR}/usr/ports ,
331 which can be a very time consuming operation.
332 .It Va PORTSRELEASETAG
333 The CVS tag to use when checking out the ports tree.
335 the head of the ports tree is used by default.
338 specifies a release tag,
339 then the associated release version is used as the default instead.
340 .It Va NO_PREFETCHDISTFILES
341 If this variable is defined,
342 then distfiles needed during the release build will not be downloaded prior to
347 .Va NO_PREFETCHDISTFILES
349 the fetching is done after any distfiles are obtained via
350 .Va RELEASEDISTFILES .
351 .It Va RELEASEDISTFILES
352 The directory where the distribution files for ports required by the
353 release build can be found.
354 This may save a significant amount of time over downloading the
355 distfiles through a slow link.
356 .It Va RELEASENOUPDATE
357 If this variable is defined for
358 .Dq Li "make rerelease" ,
359 the source code will not be updated with
360 .Dq Li "cvs update" .
362 The CVS tag corresponding to the release that is to be built.
363 If undefined, the release will be built from the
367 .Dq "-CURRENT snapshot" ) .
369 The target machine processor architecture.
370 This is analogous to the
373 Set this to cross-build for a different architecture.
375 The target hardware platform.
376 This is analogous to the
379 This is necessary to cross-build some target architectures.
380 For example, cross-building for PC98 machines requires
381 .Va TARGET_ARCH Ns = Ns Li i386
383 .Va TARGET Ns = Ns Li pc98 .
386 .Dq Li "make buildworld"
389 which usually points to
392 The contents of this variable are passed to
394 when building world during the release build.
395 For example, setting this variable to
399 to execute up to four processes at a time.
403 .It Pa /etc/make.conf
404 .It Pa /usr/doc/Makefile
405 .It Pa /usr/doc/share/mk/doc.project.mk
406 .It Pa /usr/ports/Mk/bsd.port.mk
407 .It Pa /usr/ports/Mk/bsd.sites.mk
408 .It Pa /usr/share/examples/etc/make.conf
409 .It Pa /usr/src/Makefile
410 .It Pa /usr/src/Makefile.inc1
411 .It Pa /usr/src/release/Makefile
412 .It Pa /usr/src/release/${arch}/drivers.conf
413 .It Pa /usr/src/release/${arch}/boot_crunch.conf
414 .It Pa /usr/src/release/${arch}/fixit_crunch.conf
417 The following sequence of commands was used to build the
420 .Bd -literal -offset indent
422 cvs co -rRELENG_4_9_0_RELEASE src
426 make release CHROOTDIR=/local3/release BUILDNAME=4.9-RELEASE \\
427 CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_9_0_RELEASE
430 After running these commands, a complete system suitable for FTP or
431 CD-ROM distribution is available in the
432 .Pa /local3/release/R
435 The following sequence of commands can be used to build a
436 .Dq "-CURRENT snapshot"
438 locally modified source tree:
439 .Bd -literal -offset indent
441 cvs diff -u > /path/to/local.patch
444 make release CHROOTDIR=/local3/release BUILDNAME=5.0-CURRENT \\
445 CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
464 .%T "FreeBSD Release Engineering"
465 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
468 .%T "FreeBSD Release Engineering of Third Party Packages"
469 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
472 .%T "FreeBSD Developers' Handbook"
473 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
478 used a manual checklist, compiled by
480 to produce a release.
481 Apart from being incomplete, the list put a lot of specific demands on
482 available file systems and was quite torturous to execute.
486 release engineering effort, significant
487 effort was spent getting
488 .Pa src/release/Makefile
489 into a shape where it could at least automate most of the tediousness
490 of building a release in a sterile environment.
492 With its almost 1000 revisions spread over multiple branches, the
495 .Pa src/release/Makefile
496 contains a vivid historical record of some
497 of the hardships release engineers go through.
499 .Pa src/release/Makefile
500 was originally written by
505 .An Poul-Henning Kamp .
506 This manual page was written by
507 .An Murray Stokely Aq murray@FreeBSD.org .
509 Infrastructure changes are occasionally made to the
511 documentation set in such a way that release builds on security
513 To work around this, release builds can be made to checkout the
514 documentation from the last fully supported release of
518 .Dl "make release RELEASETAG=RELENG_4_9 DOCRELEASETAG=RELEASE_4_9_0 ..."