xref: /freebsd/share/man/man7/release.7 (revision acd3428b7d3e94cef0e1881c868cb4b131d4ff41)
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$
26.\"
27.Dd August 14, 2006
28.Dt RELEASE 7
29.Os
30.Sh NAME
31.Nm release
32.Nd "release building infrastructure"
33.Sh DESCRIPTION
34.Fx
35provides a complete build environment suitable for users to make
36full releases of the
37.Fx
38operating system.
39All of the tools necessary to build a release are available from the
40CVS repository in
41.Pa src/release .
42A complete release can actually be built with only a single command,
43including the creation of ISO images suitable for burning to CD-ROM,
44installation floppies, and an FTP install directory.
45This command is aptly named
46.Dq Li "make release" .
47.Pp
48Before attempting to build a release, the user is expected to be
49familiar with the contents of
50.Xr build 7 ,
51and should have experience upgrading systems from source.
52The release build process requires that
53.Pa /usr/obj
54be populated with the output of
55a native
56.Dq Li "make buildworld"
57compiled from sources matching the currently running kernel.
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 md 4
64(memory disk) device driver be present in the kernel
65(either by being compiled in or available 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 package-split"
78.It Cm release
79Uses
80.Dq Li "make installworld"
81to install a clean system into a
82.Xr chroot 8
83environment on the file system.
84Checks out the specified version of the source code and then rebuilds
85the entire system in the clean environment with
86.Dq Li "make buildworld" .
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 (the default).
94.It Cm rerelease
95Assumes that the output of a release build has been manually modified,
96and performs the minimal number of steps to rebuild the release using
97the intermediate output of the previous
98.Dq Li "make release" .
99.It Cm floppies
100Generate a new set of boot and fixit floppies.
101This will call the
102.Cm release.4 ,
103.Cm release.8 ,
104.Cm floppies.1 ,
105.Cm floppies.2 ,
106and
107.Cm floppies.3
108targets to re-generate the floppy images of a previous
109.Dq Li "make release" .
110This is most often used to build custom boot floppies.
111.It Cm package-split
112Generates the portions of the disc 1 and disc 2 images related to packages.
113It uses the list of desired packages from the
114.Pa src/release/scripts/package-split.py
115script to pull packages out of a package build provided by the ports team
116and organize them appropriately.
117The resulting directory can then be passed to
118.Dq Li "make release"
119via the
120.Va CD_PACKAGE_TREE
121variable to populate the ISO images built by the
122.Cm iso.1
123target with the correct package related bits.
124.El
125.Pp
126Targets called by
127.Dq Li "make release" :
128.Bl -tag -width ".Cm fetch-distfiles"
129.It Cm release.1
130Cleans out the
131.Pa ${CHROOTDIR}/R
132directory and uses
133.Xr mtree 8
134to build the directory hierarchy for the system.
135.It Cm release.2
136Installs the system into the distribution directories.
137.It Cm release.3
138Makes and installs the
139.Pa GENERIC
140kernel as well as any other kernels listed in
141.Va KERNELS .
142.It Cm release.4
143Uses
144.Xr crunchgen 1
145to build
146.Dq crunched
147binaries to live on the installation floppies.
148.It Cm release.5
149Builds synthetic distributions, and cleans up the previously built
150distribution trees.
151.It Cm release.6
152Creates tarballs of the assembled distribution trees.
153.It Cm release.7
154Makes source distributions.
155.It Cm release.8
156Creates the MFS root file systems.
157.It Cm floppies.1
158Creates the boot and kernel floppies.
159.It Cm floppies.2
160Creates the fixit floppy.
161.It Cm floppies.3
162Finalizes the
163.Pa ${CHROOTDIR}/R/ftp/stage/floppies
164staging directory.
165.It Cm ftp.1
166Sets up a suitable area for FTP installations in
167.Pa ${CHROOTDIR}/R/ftp .
168.It Cm cdrom.1
169Create the layout for the live file system CD-ROM image in
170.Pa ${CHROOTDIR}/R/cdrom .
171.It Cm cdrom.2
172Create the layout for the first and second CD-ROM images.
173.It Cm cdrom.3
174Create the layout for the boot-only CD-ROM image and the boot-only UFS
175miniroot image.
176.It Cm iso.1
177Builds ISO images (installation and
178.Dq live
179file system) from the CD-ROM release area
180(disabled by default, see
181.Va MAKE_ISOS
182below).
183.It Cm fetch-distfiles
184Fetches distfiles needed during the release build that are not already in
185.Va RELEASEDISTFILES .
186.It Cm doc.1
187Builds all of the necessary tools to turn the
188.Fx
189Documentation Project source documents (SGML, XML) into HTML
190and text documents that will accompany the release.
191Also, builds and installs the actual user documentation.
192This includes the Handbook, FAQ, articles, and so on.
193.It Cm doc.2
194Builds the release documentation.
195This includes the release notes,
196hardware guide, and installation instructions.
197.El
198.Sh ENVIRONMENT
199Variables that must be specified:
200.Bl -tag -width ".Va CHROOTDIR"
201.It Va CHROOTDIR
202The directory to be used as the
203.Xr chroot 8
204environment 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.
210This file system should have at least 3.2 gigabytes of free space on the
211i386 architecture.
212.It Va CVSROOT
213The location of the
214.Fx
215CVS repository.
216This path name is in reference to the real system root,
217.Em not
218the root of the
219.Xr chroot 8
220directory tree.
221.El
222.Pp
223Optional variables:
224.Bl -tag -width ".Va NO_PREFETCHDISTFILES"
225.It Va BUILDNAME
226The name of the release to be built.
227This is used to set the
228.Va RELEASE
229value in
230.Pa sys/conf/newvers.sh ,
231which affects the output of
232.Xr uname 1 .
233If not set, a name with the timestamp and the
234.Dq Li -SNAP
235suffix will be generated.
236.It Va CD_PACKAGE_TREE
237A directory containing extra bits for the first and second CD-ROM images.
238The extra files for the first disc should be in
239.Pa ${CD_PACKAGE_TREE}/disc1
240and the extra files for the second disc should be in
241.Pa ${CD_PACKAGE_TREE}/disc2 .
242Typically, this variable will be set to the output directory of an earlier
243invocation of the
244.Cm package-split
245target.
246.It Va CVSARGS
247Additional arguments for
248.Xr cvs 1
249that come before the subcommands such as
250.Dq Li "-qR" .
251.It Va CVSCMDARGS
252Additional arguments for
253.Xr cvs 1
254.Ic checkout
255and
256.Ic update
257commands.
258For example, setting this variable to
259.Dq Li "-D '01/01/2002 00:00:00 GMT'"
260for
261.Dq Li "make release"
262or
263.Dq Li "make rerelease"
264will ask
265.Xr cvs 1
266to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively.
267.It Va DOC_LANG
268The list of languages and encodings the SGML-based documentation
269should be built for.
270If not set, the documentation is built for all available languages.
271.It Va DOCRELEASETAG
272The CVS tag to use when checking out the documentation tree.
273Usually,
274the head of the documentation tree is used by default.
275If
276.Va RELEASETAG
277specifies a release tag,
278then the associated release version is used as the default instead.
279.It Va EXTLOCALDIR
280The directory that will be copied to
281.Pa ${CHROOTDIR}/usr/local .
282.It Va EXTSRCDIR
283The directory specified by this variable will be copied into
284.Pa ${CHROOTDIR}/usr/src
285instead of that directory being populated by a CVS checkout.
286For
287.Dq Li "rerelease" ,
288this will NOT be copied; cvs update will be used instead.
289.It Va EXTDOCDIR
290The directory specified by this variable will be copied into
291.Pa ${CHROOTDIR}/usr/doc .
292For
293.Dq Li "rerelease" ,
294this will NOT be copied; cvs update will be used instead.
295.It Va EXTPORTSDIR
296The directory specified by this variable will be copied into
297.Pa ${CHROOTDIR}/usr/ports .
298For
299.Dq Li "rerelease" ,
300this will do NOTHING.
301.It Va KERNEL_FLAGS
302The contents of this variable are passed to
303.Xr make 1
304when building kernels during the release build.
305For example, setting this variable to
306.Dq Li "-j 4"
307will instruct
308.Xr make 1
309to execute up to four processes at a time.
310.It Va KERNELS
311Specifies a list of additional kernel configurations to compile and
312install into the
313.Dq base
314distribution.
315Each kernel is installed into
316.Pa /boot/<config>
317so that it can be booted from the loader via
318.Dq Li "boot <config>" .
319.It Va LOCAL_PATCHES
320Patch files against
321.Pa /usr/src
322that will be applied in the
323.Xr chroot 8
324environment before the release build begins.
325.It Va PATCH_FLAGS
326Arguments for the
327.Xr patch 1
328command used to apply
329.Va LOCAL_PATCHES
330patch file.
331.It Va LOCAL_SCRIPT
332A script that will be run in the
333.Xr chroot 8
334environment immediately after any local patches are applied.
335.It Va MAKE_ISOS
336If defined, bootable ISO CD-ROM images will be created from the
337contents of the CD-ROM stage directory.
338.It Va NOCDROM
339If defined, the CD-ROM stage directories will not be created.
340.It Va NODOC
341If defined, the SGML-based documentation from the
342.Fx
343Documentation Project will not be built.
344However, the
345.Dq doc
346distribution will still be created with the minimal documentation set
347provided in
348.Pa src/share/doc .
349.It Va NO_FLOPPIES
350If defined, no boot and fixit floppy disk images will be created (for those
351platforms supporting them).
352.It Va NOPORTS
353If defined, the Ports Collection will be omitted from the release.
354.It Va PORTSRELEASETAG
355The CVS tag to use when checking out the ports tree.
356Usually,
357the head of the ports tree is used by default.
358If
359.Va RELEASETAG
360specifies a release tag,
361then the associated release version is used as the default instead.
362.It Va NO_PREFETCHDISTFILES
363If this variable is defined,
364then distfiles needed during the release build will not be downloaded prior to
365entering the
366.Xr chroot 8
367environment.
368Note that if
369.Va NO_PREFETCHDISTFILES
370is not set,
371the fetching is done after any distfiles are obtained via
372.Va RELEASEDISTFILES .
373.It Va RELEASEDISTFILES
374The directory where the distribution files for ports required by the
375release build can be found.
376This may save a significant amount of time over downloading the
377distfiles through a slow link.
378.It Va RELEASENOUPDATE
379If this variable is defined for
380.Dq Li "make rerelease" ,
381the source code will not be updated with
382.Dq Li "cvs update" .
383.It Va RELEASETAG
384The CVS tag corresponding to the release that is to be built.
385If undefined, the release will be built from the
386.Dv HEAD
387of the CVS tree
388(a
389.Dq "-CURRENT snapshot" ) .
390.It Va SEPARATE_LIVEFS
391Store the live file system on its own CD-ROM image rather than placing it on
392the first disc.
393.It Va TARGET_ARCH
394The target machine processor architecture.
395This is analogous to the
396.Dq Nm uname Fl p
397output.
398Set this to cross-build for a different architecture.
399.It Va TARGET
400The target hardware platform.
401This is analogous to the
402.Dq Nm uname Fl m
403output.
404This is necessary to cross-build some target architectures.
405For example, cross-building for PC98 machines requires
406.Va TARGET_ARCH Ns = Ns Li i386
407and
408.Va TARGET Ns = Ns Li pc98 .
409.It Va WORLDDIR
410The directory where
411.Dq Li "make buildworld"
412was run; defaults to
413.Pa ${.CURDIR}/..
414which usually points to
415.Pa /usr/src .
416.It Va WORLD_FLAGS
417The contents of this variable are passed to
418.Xr make 1
419when building world during the release build.
420For example, setting this variable to
421.Dq Li "-j 4"
422will instruct
423.Xr make 1
424to execute up to four processes at a time.
425.El
426.Sh FILES
427.Bl -tag -compact
428.It Pa /usr/doc/Makefile
429.It Pa /usr/doc/share/mk/doc.project.mk
430.It Pa /usr/ports/Mk/bsd.port.mk
431.It Pa /usr/ports/Mk/bsd.sites.mk
432.It Pa /usr/share/examples/etc/make.conf
433.It Pa /usr/src/Makefile
434.It Pa /usr/src/Makefile.inc1
435.It Pa /usr/src/release/Makefile
436.It Pa /usr/src/release/${arch}/boot_crunch.conf
437.It Pa /usr/src/release/${arch}/fixit_crunch.conf
438.El
439.Sh EXAMPLES
440The following sequence of commands was used to build the
441.Fx 4.9
442release:
443.Bd -literal -offset indent
444cd /usr
445cvs co -rRELENG_4_9_0_RELEASE src
446cd src
447make buildworld
448cd release
449make release CHROOTDIR=/local3/release BUILDNAME=4.9-RELEASE \\
450  CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_9_0_RELEASE
451.Ed
452.Pp
453After running these commands, a complete system suitable for FTP or
454CD-ROM distribution is available in the
455.Pa /local3/release/R
456directory.
457.Pp
458The following sequence of commands can be used to build a
459.Dq "-CURRENT snapshot"
460of a
461locally modified source tree:
462.Bd -literal -offset indent
463cd /usr/src
464cvs diff -u > /path/to/local.patch
465make buildworld
466cd release
467make release CHROOTDIR=/local3/release BUILDNAME=6.0-CURRENT \\
468  CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
469.Ed
470.Sh SEE ALSO
471.Xr cc 1 ,
472.Xr crunchgen 1 ,
473.Xr cvs 1 ,
474.Xr install 1 ,
475.Xr make 1 ,
476.Xr patch 1 ,
477.Xr uname 1 ,
478.Xr md 4 ,
479.Xr make.conf 5 ,
480.Xr build 7 ,
481.Xr ports 7 ,
482.Xr chroot 8 ,
483.Xr mtree 8 ,
484.Xr sysctl 8
485.Rs
486.%T "FreeBSD Release Engineering"
487.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
488.Re
489.Rs
490.%T "FreeBSD Release Engineering of Third Party Packages"
491.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
492.Re
493.Rs
494.%T "FreeBSD Developers' Handbook"
495.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
496.Re
497.Sh HISTORY
498.Fx
4991.x
500used a manual checklist, compiled by
501.An Rod Grimes ,
502to produce a release.
503Apart from being incomplete, the list put a lot of specific demands on
504available file systems and was quite torturous to execute.
505.Pp
506As part of the
507.Fx 2.0
508release engineering effort, significant
509effort was spent getting
510.Pa src/release/Makefile
511into a shape where it could at least automate most of the tediousness
512of building a release in a sterile environment.
513.Pp
514With its almost 1000 revisions spread over multiple branches, the
515.Xr cvs 1
516log of
517.Pa src/release/Makefile
518contains a vivid historical record of some
519of the hardships release engineers go through.
520.Sh AUTHORS
521.Pa src/release/Makefile
522was originally written by
523.An -nosplit
524.An Rod Grimes ,
525.An Jordan Hubbard ,
526and
527.An Poul-Henning Kamp .
528This manual page was written by
529.An Murray Stokely Aq murray@FreeBSD.org .
530.Sh BUGS
531Infrastructure changes are occasionally made to the
532.Fx
533documentation set in such a way that release builds on security
534branches can fail.
535To work around this, release builds can be made to checkout the
536documentation from the last fully supported release of
537.Fx .
538For example:
539.Pp
540.Dl "make release RELEASETAG=RELENG_4_9 DOCRELEASETAG=RELEASE_4_9_0 ..."
541