xref: /freebsd/share/man/man7/release.7 (revision 23090366f729c56cab62de74c7a51792357e98a9)
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 September 16, 2012
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
119Environment variables:
120.Bl -tag -width ".Cm MAKE_FLAGS"
121.It Ev MAKE_FLAGS
122This environment variable can be set to pass flags (e.g. -j) to
123.Xr make 1
124when invoked by the script.
125.It Ev SVNROOT
126The location of the FreeBSD SVN source, doc, and ports repositories.
127Defaults to
128.Pa svn://svn.freebsd.org/base
129for the source tree,
130.Pa svn://svn.freebsd.org/ports/head
131for the Ports Collection, and
132.Pa svn://svn.freebsd.org/doc/head
133for the Documentation Project source.
134.It Ev RELSTRING
135Optional base name for generated media images (e.g. FreeBSD-9.0-RC2-amd64).
136Defaults to the output of
137.Ic `uname -s`-`uname -r`-`uname -p`
138within the chroot.
139.El
140.Sh MAKEFILE TARGETS
141The release makefile
142.Pq Pa src/release/Makefile
143is fairly abstruse.
144Most developers will only be concerned with the
145.Cm release
146and
147.Cm install
148targets.
149.\" XXX: Some sort of introduction to this list?  All the others have one.
150.Bl -tag -width ".Cm packagesystem"
151.It Cm release
152Meta-target to build all release media and distributions applicable to this
153platform.
154.It Cm install
155Copy all produced release media to
156.Pa ${DESTDIR} .
157.It Cm cdrom
158Builds installation CD-ROM images. On some systems, this may require that
159.Xr mkisofs 8
160be installed
161.Pq Pa sysutils/cdrtools
162and possibly that the
163.Xr md 4
164(memory disk) device driver be present in the kernel
165(either by being compiled in or available as a module). This target
166produces files called
167.Pa release.iso
168and
169.Pa bootonly.iso
170as its output.
171.It Cm memstick
172Builds an installation memory stick image named
173.Pa memstick .
174Not applicable on all platforms. Requires that the
175.Xr md 4
176(memory disk) device driver be present in the kernel
177(either by being compiled in or available as a module).
178.It Cm ftp
179Creates a directory named
180.Pa ftp
181containing the distribution files used in network installations
182and suitable for upload to an FTP mirror.
183.El
184.Pp
185Major subtargets called by targets above:
186.Bl -tag -width ".Cm packagesystem"
187.It Cm packagesystem
188Generates all the distribution archives (e.g. base, kernel, ports, doc)
189applicable on this platform.
190.It Cm system
191Builds a bootable installation system containing all the distribution files
192packaged by the
193.Cm packagesystem
194target, and suitable for imaging by the
195.Cm cdrom
196and
197.Cm memstick
198targets.
199.It Cm reldoc
200Builds the release documentation.
201This includes the release notes,
202hardware guide, and installation instructions. Other documentation (e.g.
203the Handbook) is built during the
204.Cm base.txz
205target invoked by
206.Cm packagesystem .
207.El
208.Sh ENVIRONMENT
209Optional variables:
210.Bl -tag -width ".Va TARGET_ARCH"
211.It Va WORLDDIR
212Location of a directory containing the src tree. By default, the directory
213above the one containing the makefile
214.Pq Pa src .
215.It Va PORTSDIR
216Location of a directory containing the ports tree. By default,
217.Pa /usr/ports .
218If it is unset or cannot be found, ports will not be included in the release.
219.It Va DOCDIR
220Location of a directory containing the doc tree. By default,
221.Pa /usr/doc .
222If it is unset or cannot be found, most documentation will not be included in
223the release; see
224.Ev NODOC
225below.
226.It Va NOPORTS
227If defined, the Ports Collection will be omitted from the release.
228.It Va NOSRC
229If set, do not include system source code in the release.
230.It Va NODOC
231If defined, the XML-based documentation from the
232.Fx
233Documentation Project will not be built.
234However, the
235.Dq doc
236distribution will still be created with the minimal documentation set
237provided in
238.Pa src/share/doc .
239.It Va TARGET
240The target hardware platform.
241This is analogous to the
242.Dq Nm uname Fl m
243output.
244This is necessary to cross-build some target architectures.
245For example, cross-building for PC98 machines requires
246.Va TARGET_ARCH Ns = Ns Li i386
247and
248.Va TARGET Ns = Ns Li pc98 .
249If not set,
250.Va TARGET
251defaults to the current hardware platform.
252.It Va TARGET_ARCH
253The target machine processor architecture.
254This is analogous to the
255.Dq Nm uname Fl p
256output.
257Set this to cross-build for a different architecture.
258If not set,
259.Va TARGET_ARCH
260defaults to the current machine architecture, unless
261.Va TARGET
262is also set, in which case it defaults to the appropriate
263value for that platform.
264Typically, one only needs to set
265.Va TARGET .
266.El
267.Sh FILES
268.Bl -tag -compact -width Pa
269.It Pa /usr/doc/Makefile
270.It Pa /usr/doc/share/mk/doc.project.mk
271.It Pa /usr/ports/Mk/bsd.port.mk
272.It Pa /usr/ports/Mk/bsd.sites.mk
273.It Pa /usr/share/examples/etc/make.conf
274.It Pa /usr/src/Makefile
275.It Pa /usr/src/Makefile.inc1
276.It Pa /usr/src/release/Makefile
277.It Pa /usr/src/release/generate-release.sh
278.El
279.Sh EXAMPLES
280The following sequence of commands can be used to build a
281.Dq "-CURRENT snapshot":
282.Bd -literal -offset indent
283cd /usr
284svn co svn://svn.freebsd.org/base/head src
285cd src
286make buildworld buildkernel
287cd release
288make release
289make install DESTDIR=/var/freebsd-snapshot
290.Ed
291.Pp
292After running these commands, all produced distribution files (tarballs
293for FTP, CD-ROM images, etc.) are available in the
294.Pa /var/freebsd-snapshot
295directory.
296.Pp
297The following sequence of commands can be used to build a
298.Dq "-CURRENT snapshot"
299in a clean environment, including ports and documentation:
300.Bd -literal -offset indent
301cd /usr/src/release
302export SVNROOT=svn://svn.freebsd.org/base
303sh generate-release.sh head /local3/release
304.Ed
305.Pp
306After running these commands, all prepared release files are available in the
307.Pa /local3/release/R
308directory.
309.Sh SEE ALSO
310.Xr cc 1 ,
311.Xr install 1 ,
312.Xr make 1 ,
313.Xr svn 1 Pq Pa ports/devel/subversion-freebsd ,
314.Xr uname 1 ,
315.Xr md 4 ,
316.Xr make.conf 5 ,
317.Xr build 7 ,
318.Xr ports 7 ,
319.Xr chroot 8 ,
320.Xr mtree 8 ,
321.Xr sysctl 8
322.Rs
323.%T "FreeBSD Release Engineering"
324.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
325.Re
326.Rs
327.%T "FreeBSD Release Engineering of Third Party Packages"
328.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
329.Re
330.Rs
331.%T "FreeBSD Developers' Handbook"
332.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
333.Re
334.Sh HISTORY
335.Fx
3361.x
337used a manual checklist, compiled by
338.An Rod Grimes ,
339to produce a release.
340Apart from being incomplete, the list put a lot of specific demands on
341available file systems and was quite torturous to execute.
342.Pp
343As part of the
344.Fx 2.0
345release engineering effort, significant
346effort was spent getting
347.Pa src/release/Makefile
348into a shape where it could at least automate most of the tediousness
349of building a release in a sterile environment.
350.Pp
351For the
352.Fx 9.0
353release,
354.Pa src/release/Makefile
355was overhauled and the wrapper script
356.Pa src/release/generate-release.sh
357introduced to support the introduction of a new installer.
358.Pp
359At near 1000 revisions spread over multiple branches, the
360.Xr svn 1
361log of
362.Pa src/release/Makefile
363contains a vivid historical record of some
364of the hardships release engineers go through.
365.Sh AUTHORS
366.Pa src/release/Makefile
367was originally written by
368.An -nosplit
369.An Rod Grimes ,
370.An Jordan Hubbard ,
371and
372.An Poul-Henning Kamp .
373This manual page was written by
374.An Murray Stokely Aq murray@FreeBSD.org .
375