xref: /freebsd/share/man/man7/release.7 (revision 8d20be1e22095c27faf8fe8b2f0d089739cc742e)
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, 2013
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
40.Fx
41source code repository in
42.Pa src/release .
43A complete release can actually be built with only a single command,
44including the creation of ISO images suitable for burning to CD-ROM,
45memory stick images, and an FTP install directory.
46This command is aptly named
47.Dq Li "make release" .
48.Pp
49For some users, it may be desirable to provide an absolutely clean
50build environment, with no local modifications to the source tree or to
51.Xr make.conf 5 ,
52and with clean checkouts of specific versions of the doc, src, and ports
53trees.
54For this purpose, a script
55.Pq Pa src/release/release.sh
56is provided to automate these checkouts and then execute
57.Dq Li "make release"
58in a clean
59.Xr chroot 8 .
60.Pp
61Before attempting to build a release, the user is expected to be
62familiar with the contents of
63.Xr build 7 ,
64and should have experience upgrading systems from source.
65.Pp
66The release build process requires that
67.Pa /usr/obj
68be populated with the output of
69.Dq Li "make buildworld"
70and
71.Dq Li "make buildkernel" .
72This is necessary to provide the object files for the release or, when
73using
74.Pa release.sh ,
75so that the object files for a complete system can be installed into a clean
76.Xr chroot 8
77environment.
78.Pp
79If the target release build is for a different architecture or machine type,
80the
81.Va TARGET
82and
83.Va TARGET_ARCH
84variables must be used.
85See the supported
86.Fa release.conf
87variables for more information.
88.Pp
89The release procedure on some architectures may also require that the
90.Xr md 4
91(memory disk) device driver be present in the kernel
92.Pq either by being compiled in or available as a module .
93.Pp
94This document does not cover source code management, quality
95assurance, or other aspects of the release engineering process.
96.Sh CLEAN RELEASE GENERATION
97Official releases of
98.Fx
99are produced in a totally clean environment to
100ensure consistency between the versions of the src, ports, and doc trees
101and to avoid contamination from the host system
102.Po such as local patches, changes
103to
104.Xr make.conf 5 ,
105etc.
106.Pc .
107This is accomplished using the wrapper script
108.Pa src/release/release.sh .
109.Pp
110.Ic release.sh
111.Op Fl c Ar release.conf
112.Pp
113.Ic release.sh
114checks out the
115.Li src/ ,
116.Li ports/ ,
117and
118.Li doc/
119trees to
120.Va CHROOTDIR ,
121then calls
122.Dq Li "make buildworld"
123and
124.Dq Li "make installworld"
125to generate a
126.Xr chroot 8
127environment.
128Next,
129.Dq Li "make release"
130is run within the
131.Xr chroot 8
132environment and places the result in
133.Pa $CHROOTDIR/R .
134.Pp
135The optional
136.Fa release.conf
137configuration file supports the following variables:
138.Bl -tag -width Ev
139.It Va CHROOTDIR
140The directory within which the release will be built.
141.It Va SVNROOT
142The
143.Xr svn 1
144host used to check out the various trees.
145Defaults to
146.Pa svn://svn.FreeeBSD.org .
147.It Va SRCBRANCH
148The
149.Li src/
150branch to use.
151Defaults to
152.Va head/@rHEAD .
153.It Va DOCBRANCH
154The
155.Li doc/
156branch to use.
157Defaults to
158.Va head/@rHEAD .
159.It Va PORTBRANCH
160The
161.Li ports/
162branch to use.
163Defaults to
164.Va head/@rHEAD .
165.It Va TARGET
166The target machine type for cross-building a release.
167.It Va TARGET_ARCH
168The target machine architecture for cross-building a release.
169.Pp
170For the supported list of
171.Va TARGET
172and
173.Va TARGET_ARCH
174combinations, consult the output of
175.Dq make targets
176as documented in
177.Xr build 7 .
178.It Va KERNEL
179The target kernel configuration to use.
180Defaults to
181.Va GENERIC .
182Multiple
183.Va KERNEL
184entries may be specified.
185.It Va MAKE_CONF
186The
187.Xr make.conf 5
188to use for the release build.
189Defaults to
190.Fa /dev/null
191to prevent polluting the release with local system changes.
192.It Va SRC_CONF
193The
194.Xr src.conf 5
195to use for the release build.
196Defaults to
197.Fa /dev/null
198to prevent polluting the release with local system changes.
199.It Va MAKE_FLAGS
200Additional flags to pass to
201.Xr make 1 .
202.It Va WORLD_FLAGS
203Additional flags to pass to
204.Xr make 1
205during the
206.Dq buildworld
207phase.
208Defaults to setting the number of
209.Xr make 1
210jobs
211.Pq Ar -j
212to the number of CPUs available on a SMP-capable system.
213.It Va KERNEL_FLAGS
214Additional flags to pass to
215.Xr make 1
216during the
217.Dq buildkernel
218phase.
219Defaults to setting the number of
220.Xr make 1
221jobs
222.Pq Ar -j
223to half the number of CPUs available on a SMP-capable system.
224.It Va NODOC
225Set to a non-empty value to skip the
226.Li doc/
227tree checkout.
228When set,
229.Va NODOC
230will prevent the
231.Fa doc.txz
232distribution package from being created.
233.It Va NOPORTS
234Set to a non-empty value to skip the
235.Li ports/
236tree checkout.
237When set,
238.Va NOPORTS
239will prevent the
240.Fa ports.txz
241distribution package from being created.
242Setting this also sets
243.Va NODOC .
244.El
245.Sh MAKEFILE TARGETS
246The release makefile
247.Pq Pa src/release/Makefile
248is fairly abstruse.
249Most developers will only be concerned with the
250.Cm release
251and
252.Cm install
253targets.
254.\" XXX: Some sort of introduction to this list?  All the others have one.
255.Bl -tag -width ".Cm packagesystem"
256.It Cm release
257Meta-target to build all release media and distributions applicable to this
258platform.
259.It Cm install
260Copy all produced release media to
261.Pa ${DESTDIR} .
262.It Cm cdrom
263Builds installation CD-ROM images.
264This may require the
265.Xr md 4
266(memory disk) device driver be present in the kernel
267(either by being compiled in or available as a module).
268This target produces files called
269.Pa disc1.iso
270and
271.Pa bootonly.iso
272as its output.
273.It Cm memstick
274Builds an installation memory stick image named
275.Pa memstick.img .
276Not applicable on all platforms.
277Requires that the
278.Xr md 4
279.Pq memory disk
280device driver be present in the kernel
281.Pq either by being compiled in or available as a module .
282.It Cm ftp
283Creates a directory named
284.Pa ftp
285containing the distribution files used in network installations
286and suitable for upload to an FTP mirror.
287.El
288.Pp
289Major subtargets called by targets above:
290.Bl -tag -width ".Cm packagesystem"
291.It Cm packagesystem
292Generates all the distribution archives
293.Pq base, kernel, ports, doc
294applicable on this platform.
295.It Cm system
296Builds a bootable installation system containing all the distribution files
297packaged by the
298.Cm packagesystem
299target, and suitable for imaging by the
300.Cm cdrom
301and
302.Cm memstick
303targets.
304.It Cm reldoc
305Builds the release documentation.
306This includes the release notes,
307hardware guide, and installation instructions.
308Other documentation, such as the Handbook,
309is built during the
310.Cm base.txz
311target invoked by
312.Cm packagesystem .
313.El
314.Sh ENVIRONMENT
315Optional variables:
316.Bl -tag -width ".Ev TARGET_ARCH"
317.It Ev OSRELEASE
318Optional base name for generated media images
319.Pq e.g., FreeBSD-9.0-RC2-amd64 .
320Defaults to the output of
321.Ic `uname -s`-`uname -r`-`uname -p`
322within the chroot.
323.It Ev WORLDDIR
324Location of a directory containing the src tree.
325By default, the directory
326above the one containing the makefile
327.Pq Pa src .
328.It Ev PORTSDIR
329Location of a directory containing the ports tree.
330By default,
331.Pa /usr/ports .
332If it is unset or cannot be found, ports will not be included in the release.
333.It Ev DOCDIR
334Location of a directory containing the doc tree.
335By default,
336.Pa /usr/doc .
337If it is unset or cannot be found, most documentation will not be included in
338the release; see
339.Ev NODOC
340below.
341.It Ev NOPORTS
342If defined, the Ports Collection will be omitted from the release.
343.It Ev NOSRC
344If set, do not include system source code in the release.
345.It Ev NODOC
346If defined, the XML-based documentation from the
347.Fx
348Documentation Project will not be built.
349However, the
350.Dq doc
351distribution will still be created with the minimal documentation set
352provided in
353.Pa src/share/doc .
354.It Ev TARGET
355The target hardware platform.
356This is analogous to the
357.Dq Nm uname Fl m
358output.
359This is necessary to cross-build some target architectures.
360For example, cross-building for PC98 machines requires
361.Ev TARGET_ARCH Ns = Ns Li i386
362and
363.Ev TARGET Ns = Ns Li pc98 .
364If not set,
365.Ev TARGET
366defaults to the current hardware platform.
367.It Ev TARGET_ARCH
368The target machine processor architecture.
369This is analogous to the
370.Dq Nm uname Fl p
371output.
372Set this to cross-build for a different architecture.
373If not set,
374.Ev TARGET_ARCH
375defaults to the current machine architecture, unless
376.Ev TARGET
377is also set, in which case it defaults to the appropriate
378value for that platform.
379Typically, one only needs to set
380.Ev TARGET .
381.El
382.Sh FILES
383.Bl -tag -compact -width Pa
384.It Pa /usr/doc/Makefile
385.It Pa /usr/doc/share/mk/doc.project.mk
386.It Pa /usr/ports/Mk/bsd.port.mk
387.It Pa /usr/ports/Mk/bsd.sites.mk
388.It Pa /usr/share/examples/etc/make.conf
389.It Pa /usr/src/Makefile
390.It Pa /usr/src/Makefile.inc1
391.It Pa /usr/src/release/Makefile
392.It Pa /usr/src/release/release.sh
393.It Pa /usr/src/release/release.conf.sample
394.El
395.Sh EXAMPLES
396The following sequence of commands can be used to build a
397.Dq "-CURRENT snapshot":
398.Bd -literal -offset indent
399cd /usr
400svn co svn://svn.freebsd.org/base/head src
401cd src
402make buildworld buildkernel
403cd release
404make release
405make install DESTDIR=/var/freebsd-snapshot
406.Ed
407.Pp
408After running these commands, all produced distribution files (tarballs
409for FTP, CD-ROM images, etc.) are available in the
410.Pa /var/freebsd-snapshot
411directory.
412.Pp
413The following sequence of commands can be used to build a
414.Dq "-CURRENT snapshot"
415in a clean environment, including ports and documentation:
416.Bd -literal -offset indent
417cd /usr/src/release
418sh release.sh
419.Ed
420.Pp
421Optionally, a configuration file can be used customize the release build,
422such as the subversion revision to use, the branch of the subversion tree for
423.Li src/ ,
424.Li ports/ ,
425and
426.Li doc/ .
427.Bd -literal -offset indent
428cd /usr/src/release
429sh release.sh -c $HOME/release.conf
430.Ed
431.Pp
432After running these commands, all prepared release files are available in the
433.Pa /scratch
434directory.
435The target directory can be changed by specifying the
436.Va CHROOTDIR
437variable in
438.Li release.conf .
439.Sh SEE ALSO
440.Xr cc 1 ,
441.Xr install 1 ,
442.Xr make 1 ,
443.Xr svn 1 Pq Pa ports/devel/subversion ,
444.Xr uname 1 ,
445.Xr md 4 ,
446.Xr make.conf 5 ,
447.Xr build 7 ,
448.Xr ports 7 ,
449.Xr chroot 8 ,
450.Xr mtree 8 ,
451.Xr sysctl 8
452.Rs
453.%T "FreeBSD Release Engineering"
454.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
455.Re
456.Rs
457.%T "FreeBSD Release Engineering of Third Party Packages"
458.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
459.Re
460.Rs
461.%T "FreeBSD Developers' Handbook"
462.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
463.Re
464.Sh HISTORY
465.Fx
4661.x
467used a manual checklist, compiled by
468.An Rod Grimes ,
469to produce a release.
470Apart from being incomplete, the list put a lot of specific demands on
471available file systems and was quite torturous to execute.
472.Pp
473As part of the
474.Fx 2.0
475release engineering effort, significant
476effort was spent getting
477.Pa src/release/Makefile
478into a shape where it could at least automate most of the tediousness
479of building a release in a sterile environment.
480.Pp
481For the
482.Fx 9.0
483release,
484.Pa src/release/Makefile
485was overhauled and the wrapper script
486.Pa src/release/generate-release.sh
487introduced to support the introduction of a new installer.
488.Pp
489For the
490.Fx 9.2
491release,
492.Pa src/release/release.sh
493was introduced to support per-build configuration files.
494.Pa src/release/release.sh
495is heavily based on the
496.Pa src/release/generate-release.sh
497script.
498.Pp
499At near 1000 revisions spread over multiple branches, the
500.Xr svn 1
501log of
502.Pa src/release/Makefile
503contains a vivid historical record of some
504of the hardships release engineers go through.
505.Sh AUTHORS
506.Pa src/release/Makefile
507was originally written by
508.An -nosplit
509.An Rod Grimes ,
510.An Jordan Hubbard ,
511and
512.An Poul-Henning Kamp .
513.Pp
514This manual page was originally written by
515.An Murray Stokely Aq murray@FreeBSD.org .
516.Pp
517It was updated by
518.An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org
519to include the
520.Fa generate-release.sh
521script used for the
522.Fx 9.0
523release cycle.
524.Pp
525It was later updated by
526.An Glen Barber Aq gjb@FreeBSD.org
527to include the
528.Fa release.sh
529script used for the
530.Fx 9.2
531release cycle.
532