xref: /freebsd/share/man/man7/release.7 (revision f5f7c05209ca2c3748fd8b27c5e80ffad49120eb)
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 February 3, 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. For this purpose, a script
54.Pq Pa src/release/generate-release.sh
55is provided to automate these checkouts and then execute
56.Dq Li "make release"
57in a clean
58.Xr chroot 8 .
59.Pp
60Before attempting to build a release, the user is expected to be
61familiar with the contents of
62.Xr build 7 ,
63and should have experience upgrading systems from source.
64.Pp
65The release build process requires that
66.Pa /usr/obj
67be populated with the output of
68.Dq Li "make buildworld"
69and
70.Dq Li "make buildkernel" .
71This is necessary to provide the object files for the release or, when
72using
73.Pa generate-release.sh ,
74so that the object files for a complete system can be installed into a clean
75.Xr chroot 8
76environment. In this second case, the built world must be capable of running
77on the build system (i.e. it must be for the same architecture and be
78compatible with the installed kernel).
79The release procedure on some architectures may also require that the
80.Xr md 4
81(memory disk) device driver be present in the kernel
82(either by being compiled in or available as a module).
83.Pp
84This document does not cover source code management, quality
85assurance, or other aspects of the release engineering process.
86.Sh CLEAN RELEASE GENERATION
87Official releases of FreeBSD are produced in a totally clean environment to
88ensure consistency between the versions of the src, ports, and doc trees
89and to avoid contamination from the host system (e.g. local patches, changes
90to
91.Xr make.conf 5 ,
92etc.). This is accomplished using the wrapper script
93.Pa src/release/generate-release.sh .
94.Pp
95.Ic generate-release.sh
96svn-branch scratch-dir
97.Pp
98.Ic generate-release.sh
99calls
100.Dq Li "make installworld"
101to generate a
102.Xr chroot 8
103environment in
104.Ar scratch-dir .
105It then checks out the src tree specified by
106.Ar svn-branch
107using
108.Xr svn 1 .
109Once the various source trees have been obtained, it executes
110.Dq Li "make release"
111within the
112.Xr chroot 8
113environment and places the result in
114.Pa $scratch-dir/R .
115Note that because this uses a chroot, it cannot be used to cross-build
116.Fx
117release media.
118.Pp
119Optional environment variables:
120.Bl -tag -width ".Cm WORLD_FLAGS"
121.It Ev WORLD_FLAGS
122This environment variable can be set to pass flags (e.g. -j) to
123.Xr make 1
124when invoked to build a world by the script.
125.It Ev KERNEL_FLAGS
126This environment variable can be set to pass flags (e.g. -j) to
127.Xr make 1
128when invoked to build a kernel by the script.
129.It Ev SVNROOTBASE
130The base part of URL of the FreeBSD SVN repositories.
131Defaults to
132.Pa svn://svn.freebsd.org .
133.It Ev SVNROOTSRC
134The URL of the FreeBSD SVN source repository.
135Defaults to
136.Pa ${SVNROOTBASE}/base .
137.It Ev SVNROOTDOC
138The URL of the FreeBSD SVN doc repository.
139Defaults to
140.Pa ${SVNROOTBASE}/doc .
141.It Ev SVNROOTPORTS
142The URL of the FreeBSD SVN ports repository.
143Defaults to
144.Pa ${SVNROOTBASE}/ports .
145.It Ev BRANCHDOC
146The branch name of the FreeBSD SVN doc repository.
147Defaults to
148.Pa head .
149.It Ev BRANCHPORTS
150The branch name of the FreeBSD SVN ports repository.
151Defaults to
152.Pa head .
153.El
154.Sh MAKEFILE TARGETS
155The release makefile
156.Pq Pa src/release/Makefile
157is fairly abstruse.
158Most developers will only be concerned with the
159.Cm release
160and
161.Cm install
162targets.
163.\" XXX: Some sort of introduction to this list?  All the others have one.
164.Bl -tag -width ".Cm packagesystem"
165.It Cm release
166Meta-target to build all release media and distributions applicable to this
167platform.
168.It Cm install
169Copy all produced release media to
170.Pa ${DESTDIR} .
171.It Cm cdrom
172Builds installation CD-ROM images.
173This may require the
174.Xr md 4
175(memory disk) device driver be present in the kernel
176(either by being compiled in or available as a module).
177This target produces files called
178.Pa release.iso
179and
180.Pa bootonly.iso
181as its output.
182.It Cm memstick
183Builds an installation memory stick image named
184.Pa memstick .
185Not applicable on all platforms.
186Requires that the
187.Xr md 4
188(memory disk) device driver be present in the kernel
189(either by being compiled in or available as a module).
190.It Cm ftp
191Creates a directory named
192.Pa ftp
193containing the distribution files used in network installations
194and suitable for upload to an FTP mirror.
195.El
196.Pp
197Major subtargets called by targets above:
198.Bl -tag -width ".Cm packagesystem"
199.It Cm packagesystem
200Generates all the distribution archives (e.g. base, kernel, ports, doc)
201applicable on this platform.
202.It Cm system
203Builds a bootable installation system containing all the distribution files
204packaged by the
205.Cm packagesystem
206target, and suitable for imaging by the
207.Cm cdrom
208and
209.Cm memstick
210targets.
211.It Cm reldoc
212Builds the release documentation.
213This includes the release notes,
214hardware guide, and installation instructions. Other documentation (e.g.
215the Handbook) is built during the
216.Cm base.txz
217target invoked by
218.Cm packagesystem .
219.El
220.Sh ENVIRONMENT
221Optional variables:
222.Bl -tag -width ".Ev TARGET_ARCH"
223.It Ev OSRELEASE
224Optional base name for generated media images (e.g. FreeBSD-9.0-RC2-amd64).
225Defaults to the output of
226.Ic `uname -s`-`uname -r`-`uname -p`
227within the chroot.
228.It Ev WORLDDIR
229Location of a directory containing the src tree. By default, the directory
230above the one containing the makefile
231.Pq Pa src .
232.It Ev PORTSDIR
233Location of a directory containing the ports tree. By default,
234.Pa /usr/ports .
235If it is unset or cannot be found, ports will not be included in the release.
236.It Ev DOCDIR
237Location of a directory containing the doc tree. By default,
238.Pa /usr/doc .
239If it is unset or cannot be found, most documentation will not be included in
240the release; see
241.Ev NODOC
242below.
243.It Ev NOPORTS
244If defined, the Ports Collection will be omitted from the release.
245.It Ev NOSRC
246If set, do not include system source code in the release.
247.It Ev NODOC
248If defined, the XML-based documentation from the
249.Fx
250Documentation Project will not be built.
251However, the
252.Dq doc
253distribution will still be created with the minimal documentation set
254provided in
255.Pa src/share/doc .
256.It Ev TARGET
257The target hardware platform.
258This is analogous to the
259.Dq Nm uname Fl m
260output.
261This is necessary to cross-build some target architectures.
262For example, cross-building for PC98 machines requires
263.Ev TARGET_ARCH Ns = Ns Li i386
264and
265.Ev TARGET Ns = Ns Li pc98 .
266If not set,
267.Ev TARGET
268defaults to the current hardware platform.
269.It Ev TARGET_ARCH
270The target machine processor architecture.
271This is analogous to the
272.Dq Nm uname Fl p
273output.
274Set this to cross-build for a different architecture.
275If not set,
276.Ev TARGET_ARCH
277defaults to the current machine architecture, unless
278.Ev TARGET
279is also set, in which case it defaults to the appropriate
280value for that platform.
281Typically, one only needs to set
282.Ev TARGET .
283.El
284.Sh FILES
285.Bl -tag -compact -width Pa
286.It Pa /usr/doc/Makefile
287.It Pa /usr/doc/share/mk/doc.project.mk
288.It Pa /usr/ports/Mk/bsd.port.mk
289.It Pa /usr/ports/Mk/bsd.sites.mk
290.It Pa /usr/share/examples/etc/make.conf
291.It Pa /usr/src/Makefile
292.It Pa /usr/src/Makefile.inc1
293.It Pa /usr/src/release/Makefile
294.It Pa /usr/src/release/generate-release.sh
295.El
296.Sh EXAMPLES
297The following sequence of commands can be used to build a
298.Dq "-CURRENT snapshot":
299.Bd -literal -offset indent
300cd /usr
301svn co svn://svn.freebsd.org/base/head src
302cd src
303make buildworld buildkernel
304cd release
305make release
306make install DESTDIR=/var/freebsd-snapshot
307.Ed
308.Pp
309After running these commands, all produced distribution files (tarballs
310for FTP, CD-ROM images, etc.) are available in the
311.Pa /var/freebsd-snapshot
312directory.
313.Pp
314The following sequence of commands can be used to build a
315.Dq "-CURRENT snapshot"
316in a clean environment, including ports and documentation:
317.Bd -literal -offset indent
318cd /usr/src/release
319sh generate-release.sh head /local3/release
320.Ed
321.Pp
322After running these commands, all prepared release files are available in the
323.Pa /local3/release/R
324directory.
325.Sh SEE ALSO
326.Xr cc 1 ,
327.Xr install 1 ,
328.Xr make 1 ,
329.Xr svn 1 Pq Pa ports/devel/subversion ,
330.Xr uname 1 ,
331.Xr md 4 ,
332.Xr make.conf 5 ,
333.Xr build 7 ,
334.Xr ports 7 ,
335.Xr chroot 8 ,
336.Xr mtree 8 ,
337.Xr sysctl 8
338.Rs
339.%T "FreeBSD Release Engineering"
340.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
341.Re
342.Rs
343.%T "FreeBSD Release Engineering of Third Party Packages"
344.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
345.Re
346.Rs
347.%T "FreeBSD Developers' Handbook"
348.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
349.Re
350.Sh HISTORY
351.Fx
3521.x
353used a manual checklist, compiled by
354.An Rod Grimes ,
355to produce a release.
356Apart from being incomplete, the list put a lot of specific demands on
357available file systems and was quite torturous to execute.
358.Pp
359As part of the
360.Fx 2.0
361release engineering effort, significant
362effort was spent getting
363.Pa src/release/Makefile
364into a shape where it could at least automate most of the tediousness
365of building a release in a sterile environment.
366.Pp
367For the
368.Fx 9.0
369release,
370.Pa src/release/Makefile
371was overhauled and the wrapper script
372.Pa src/release/generate-release.sh
373introduced to support the introduction of a new installer.
374.Pp
375At near 1000 revisions spread over multiple branches, the
376.Xr svn 1
377log of
378.Pa src/release/Makefile
379contains a vivid historical record of some
380of the hardships release engineers go through.
381.Sh AUTHORS
382.Pa src/release/Makefile
383was originally written by
384.An -nosplit
385.An Rod Grimes ,
386.An Jordan Hubbard ,
387and
388.An Poul-Henning Kamp .
389This manual page was written by
390.An Murray Stokely Aq murray@FreeBSD.org .
391