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 package-split"
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.
112 Generates the portions of the disc 1 and disc 2 images related to packages.
113 It uses the list of desired packages from the
114 .Pa src/release/scripts/package-split.py
115 script to pull packages out of a package build provided by the ports team
116 and organize them appropriately.
117 The resulting directory can then be passed to
118 .Dq Li "make release"
121 variable to populate the ISO images built by the
123 target with the correct package related bits.
127 .Dq Li "make release" :
128 .Bl -tag -width ".Cm fetch-distfiles"
134 to build the directory hierarchy for the system.
136 Installs the system into the distribution directories.
138 Makes and installs the
140 kernel as well as any other kernels listed in
147 binaries to live on the installation floppies.
149 Builds synthetic distributions, and cleans up the previously built
152 Creates tarballs of the assembled distribution trees.
154 Makes source distributions.
156 Creates the MFS root file systems.
158 Creates the boot and kernel floppies.
160 Creates the fixit floppy.
163 .Pa ${CHROOTDIR}/R/ftp/stage/floppies
166 Sets up a suitable area for FTP installations in
167 .Pa ${CHROOTDIR}/R/ftp .
169 Create the layout for the live file system CD-ROM image in
170 .Pa ${CHROOTDIR}/R/cdrom .
172 Create the layout for the first and second CD-ROM images.
174 Create the layout for the boot-only CD-ROM image and the boot-only UFS
177 Builds ISO images (installation and
179 file system) from the CD-ROM release area
180 (disabled by default, see
183 .It Cm fetch-distfiles
184 Fetches distfiles needed during the release build that are not already in
185 .Va RELEASEDISTFILES .
187 Builds all of the necessary tools to turn the
189 Documentation Project source documents (SGML, XML) into HTML
190 and text documents that will accompany the release.
191 Also, builds and installs the actual user documentation.
192 This includes the Handbook, FAQ, articles, and so on.
194 Builds the release documentation.
195 This includes the release notes,
196 hardware guide, and installation instructions.
199 Variables that must be specified:
200 .Bl -tag -width ".Va CHROOTDIR"
202 The directory to be used as the
204 environment for the entire release build.
205 .\" XXX: I recommend against hardcoding specific numbers like "2.3" here;
206 .\" XXX: perhaps it should be replaced with something to the effect of
207 .\" XXX: "we do not know how much space you'll need, but make sure you have
208 .\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number,
209 .\" XXX: but at least it looks less like a decree and more like an estimate.
210 This file system should have at least 3.2 gigabytes of free space on the
216 This path name is in reference to the real system root,
224 .Bl -tag -width ".Va NO_PREFETCHDISTFILES"
226 The name of the release to be built.
227 This is used to set the
230 .Pa sys/conf/newvers.sh ,
231 which affects the output of
233 If not set, a name with the timestamp and the
235 suffix will be generated.
236 .It Va CD_PACKAGE_TREE
237 A directory containing extra bits for the first and second CD-ROM images.
238 The extra files for the first disc should be in
239 .Pa ${CD_PACKAGE_TREE}/disc1
240 and the extra files for the second disc should be in
241 .Pa ${CD_PACKAGE_TREE}/disc2 .
242 Typically, this variable will be set to the output directory of an earlier
247 Additional arguments for
249 that come before the subcommands such as
252 Additional arguments for
258 For example, setting this variable to
259 .Dq Li "-D '01/01/2002 00:00:00 GMT'"
261 .Dq Li "make release"
263 .Dq Li "make rerelease"
266 to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively.
268 The list of languages and encodings the SGML-based documentation
270 If not set, the documentation is built for all available languages.
272 The CVS tag to use when checking out the documentation tree.
274 the head of the documentation tree is used by default.
277 specifies a release tag,
278 then the associated release version is used as the default instead.
280 The directory that will be copied to
281 .Pa ${CHROOTDIR}/usr/local .
283 The directory specified by this variable will be copied into
284 .Pa ${CHROOTDIR}/usr/src
285 instead of that directory being populated by a CVS checkout.
288 this will NOT be copied; cvs update will be used instead.
290 The directory specified by this variable will be copied into
291 .Pa ${CHROOTDIR}/usr/doc .
294 this will NOT be copied again.
296 The directory specified by this variable will be copied into
297 .Pa ${CHROOTDIR}/usr/ports .
300 this will do NOTHING.
302 The contents of this variable are passed to
304 when building kernels during the release build.
305 For example, setting this variable to
309 to execute up to four processes at a time.
311 Specifies a list of additional kernel configurations to compile and
315 Each kernel is installed into
317 so that it can be booted from the loader via
318 .Dq Li "boot <config>" .
322 that will be applied in the
324 environment before the release build begins.
328 command used to apply
332 A script that will be run in the
334 environment immediately after any local patches are applied.
336 If defined, build a bootable ISO DVD image in the CD-ROM
338 This option may not be available for all architectures.
340 If defined, bootable ISO CD-ROM images will be created from the
341 contents of the CD-ROM stage directory.
343 If defined, the CD-ROM stage directories will not be created.
345 If defined, the SGML-based documentation from the
347 Documentation Project will not be built.
350 distribution will still be created with the minimal documentation set
354 If defined, no boot and fixit floppy disk images will be created (for those
355 platforms supporting them).
357 If defined, the Ports Collection will be omitted from the release.
358 .It Va PORTSRELEASETAG
359 The CVS tag to use when checking out the ports tree.
361 the head of the ports tree is used by default.
364 specifies a release tag,
365 then the associated release version is used as the default instead.
366 .It Va NO_PREFETCHDISTFILES
367 If this variable is defined,
368 then distfiles needed during the release build will not be downloaded prior to
373 .Va NO_PREFETCHDISTFILES
375 the fetching is done after any distfiles are obtained via
376 .Va RELEASEDISTFILES .
377 .It Va RELEASEDISTFILES
378 The directory where the distribution files for ports required by the
379 release build can be found.
380 This may save a significant amount of time over downloading the
381 distfiles through a slow link.
382 .It Va RELEASENOUPDATE
383 If this variable is defined for
384 .Dq Li "make rerelease" ,
385 the source code will not be updated with
386 .Dq Li "cvs update" .
388 The CVS tag corresponding to the release that is to be built.
389 If undefined, the release will be built from the
393 .Dq "-CURRENT snapshot" ) .
394 .It Va SEPARATE_LIVEFS
395 Store the live file system on its own CD-ROM image rather than placing it on
398 Additional arguments for svn
404 The location of the FreeBSD SVN source repository.
405 If this variable is set,
406 then the source tree will be extracted using Subversion rather than
409 The branch to check out from a SVN source repository.
410 It is specified as a path such as
414 If this variable is not set,
415 then the branch that corresponds to the current value of
427 The target machine processor architecture.
428 This is analogous to the
431 Set this to cross-build for a different architecture.
433 The target hardware platform.
434 This is analogous to the
437 This is necessary to cross-build some target architectures.
438 For example, cross-building for PC98 machines requires
439 .Va TARGET_ARCH Ns = Ns Li i386
441 .Va TARGET Ns = Ns Li pc98 .
444 .Dq Li "make buildworld"
447 which usually points to
450 The contents of this variable are passed to
452 when building world during the release build.
453 For example, setting this variable to
457 to execute up to four processes at a time.
461 .It Pa /usr/doc/Makefile
462 .It Pa /usr/doc/share/mk/doc.project.mk
463 .It Pa /usr/ports/Mk/bsd.port.mk
464 .It Pa /usr/ports/Mk/bsd.sites.mk
465 .It Pa /usr/share/examples/etc/make.conf
466 .It Pa /usr/src/Makefile
467 .It Pa /usr/src/Makefile.inc1
468 .It Pa /usr/src/release/Makefile
469 .It Pa /usr/src/release/${arch}/boot_crunch.conf
470 .It Pa /usr/src/release/${arch}/fixit_crunch.conf
473 The following sequence of commands was used to build the
476 .Bd -literal -offset indent
478 cvs co -rRELENG_4_9_0_RELEASE src
482 make release CHROOTDIR=/local3/release BUILDNAME=4.9-RELEASE \\
483 CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_9_0_RELEASE
486 After running these commands, a complete system suitable for FTP or
487 CD-ROM distribution is available in the
488 .Pa /local3/release/R
491 The following sequence of commands can be used to build a
492 .Dq "-CURRENT snapshot"
494 locally modified source tree:
495 .Bd -literal -offset indent
497 cvs diff -u > /path/to/local.patch
500 make release CHROOTDIR=/local3/release BUILDNAME=6.0-CURRENT \\
501 CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
510 .Xr svn 1 Pq Pa ports/devel/subversion-freebsd ,
520 .%T "FreeBSD Release Engineering"
521 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
524 .%T "FreeBSD Release Engineering of Third Party Packages"
525 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
528 .%T "FreeBSD Developers' Handbook"
529 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
534 used a manual checklist, compiled by
536 to produce a release.
537 Apart from being incomplete, the list put a lot of specific demands on
538 available file systems and was quite torturous to execute.
542 release engineering effort, significant
543 effort was spent getting
544 .Pa src/release/Makefile
545 into a shape where it could at least automate most of the tediousness
546 of building a release in a sterile environment.
548 At near 1000 revisions spread over multiple branches, the
551 .Pa src/release/Makefile
552 contains a vivid historical record of some
553 of the hardships release engineers go through.
555 .Pa src/release/Makefile
556 was originally written by
561 .An Poul-Henning Kamp .
562 This manual page was written by
563 .An Murray Stokely Aq murray@FreeBSD.org .
565 Infrastructure changes are occasionally made to the
567 documentation set in such a way that release builds on security
569 To work around this, release builds can be made to checkout the
570 documentation from the last fully supported release of
574 .Dl "make release RELEASETAG=RELENG_4_9 DOCRELEASETAG=RELEASE_4_9_0 ..."