xref: /freebsd/share/man/man7/release.7 (revision 994c71f0c8fc89df3a45c5e400ec580c7433fe4c)
1de26e0adSMurray Stokely.\" Copyright (c) 2002
2de26e0adSMurray Stokely.\"	Murray Stokely <murray@FreeBSD.org>
3de26e0adSMurray Stokely.\"
4de26e0adSMurray Stokely.\" Redistribution and use in source and binary forms, with or without
5de26e0adSMurray Stokely.\" modification, are permitted provided that the following conditions
6de26e0adSMurray Stokely.\" are met:
7de26e0adSMurray Stokely.\" 1. Redistributions of source code must retain the above copyright
8de26e0adSMurray Stokely.\"    notice, this list of conditions and the following disclaimer.
9de26e0adSMurray Stokely.\" 2. Redistributions in binary form must reproduce the above copyright
10de26e0adSMurray Stokely.\"    notice, this list of conditions and the following disclaimer in the
11de26e0adSMurray Stokely.\"    documentation and/or other materials provided with the distribution.
12de26e0adSMurray Stokely.\"
13de26e0adSMurray Stokely.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
14de26e0adSMurray Stokely.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15de26e0adSMurray Stokely.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16de26e0adSMurray Stokely.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
17de26e0adSMurray Stokely.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18de26e0adSMurray Stokely.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19de26e0adSMurray Stokely.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20de26e0adSMurray Stokely.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21de26e0adSMurray Stokely.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22de26e0adSMurray Stokely.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23de26e0adSMurray Stokely.\" SUCH DAMAGE.
24de26e0adSMurray Stokely.\"
25de26e0adSMurray Stokely.\" $FreeBSD$
26de26e0adSMurray Stokely.\"
27de26e0adSMurray Stokely.Dd March 12, 2002
28de26e0adSMurray Stokely.Dt RELEASE 7
29de26e0adSMurray Stokely.Os
30de26e0adSMurray Stokely.Sh NAME
31de26e0adSMurray Stokely.Nm release
32994c71f0SMurray Stokely.Nd release building infrastructure
33de26e0adSMurray Stokely.Sh DESCRIPTION
34de26e0adSMurray Stokely.Fx
35de26e0adSMurray Stokelyprovides a complete build environment suitable for users to make
36de26e0adSMurray Stokelyfull releases of the
37de26e0adSMurray Stokely.Fx
38994c71f0SMurray Stokelyoperating system.
39de26e0adSMurray StokelyAll of the tools necessary to build a release are available from the
40de26e0adSMurray StokelyCVS repository in
41de26e0adSMurray Stokely.Pa src/release .
42de26e0adSMurray StokelyA complete release can actually be built with only a single command,
43de26e0adSMurray Stokelyincluding the creation of ISO images suitable for burning to CDROM,
44de26e0adSMurray Stokelyinstallation floppies, and an FTP install directory.
45de26e0adSMurray StokelyThis command is aptly named
46de26e0adSMurray Stokely.Dq make release .
47de26e0adSMurray Stokely.Pp
48de26e0adSMurray StokelyBefore attempting to build a release, the user is expected to be
49994c71f0SMurray Stokelyfamiliar with the contents of
50de26e0adSMurray Stokely.Xr build 7 ,
51de26e0adSMurray Stokelyand should have experience upgrading systems from source with
52de26e0adSMurray Stokely.Dq make world .
53de26e0adSMurray StokelyThe release build process requires that
54de26e0adSMurray Stokely.Pa /usr/obj
55de26e0adSMurray Stokelybe populated with the output of
56de26e0adSMurray Stokely.Dq make buildworld .
57de26e0adSMurray StokelyThis is necessary so that the object files for a complete system can
58de26e0adSMurray Stokelybe installed into a clean
59de26e0adSMurray Stokely.Xr chroot 8
60de26e0adSMurray Stokelyenvironment.
61de26e0adSMurray StokelyThe release procedure also requires that the
62994c71f0SMurray Stokely.Xr md 4
63994c71f0SMurray Stokely(memory disk) device driver be present in the kernel
64994c71f0SMurray Stokely(either by being compiled in or loaded as a module).
65de26e0adSMurray Stokely.Pp
66de26e0adSMurray StokelyThis document does not cover source code management, quality
67de26e0adSMurray Stokelyassurance, or other aspects of the release engineering process.
68de26e0adSMurray Stokely.Sh TARGETS
69de26e0adSMurray StokelyThe release makefile
70994c71f0SMurray Stokely.Pq Pa src/release/Makefile
71de26e0adSMurray Stokelyis fairly abstruse.
72de26e0adSMurray StokelyMost developers will only be concerned with the
73994c71f0SMurray Stokely.Ar release
74de26e0adSMurray Stokelytarget.
75994c71f0SMurray Stokely.\" XXX: Some sort of introduction to this list?  All the others have one.
76994c71f0SMurray Stokely.Bl -tag -width rerelease
77de26e0adSMurray Stokely.It Ar release
78de26e0adSMurray StokelyUses
79de26e0adSMurray Stokely.Dq make installworld
80de26e0adSMurray Stokelyto install a clean system into a
81de26e0adSMurray Stokely.Xr chroot 8
82de26e0adSMurray Stokelyenvironment on the filesystem.
83de26e0adSMurray StokelyChecks out the specified version of the source code and then rebuilds
84de26e0adSMurray Stokelythe entire system in the clean environment with
85de26e0adSMurray Stokely.Dq make world .
86de26e0adSMurray StokelyThe detailed steps that follow are then executed to package up the
87de26e0adSMurray Stokelydifferent distributions, build the installation floppy disks, build
88de26e0adSMurray Stokelyrelease documentation, and so on.
89de26e0adSMurray Stokely.It Ar rerelease
90de26e0adSMurray StokelyAssumes that the output of a release build has been manually modified,
91de26e0adSMurray Stokelyand performs the minimal number of steps to rebuild the release using
92de26e0adSMurray Stokelythe intermediate output of the previous
93de26e0adSMurray Stokely.Dq make release .
94de26e0adSMurray Stokely.El
95de26e0adSMurray Stokely.Pp
96de26e0adSMurray StokelyTargets called by
97994c71f0SMurray Stokely.Dq make release :
98994c71f0SMurray Stokely.Bl -tag -width release.9
99de26e0adSMurray Stokely.It Ar release.1
100de26e0adSMurray StokelyCleans out the
101de26e0adSMurray Stokely.Pa ${CHROOTDIR}/R
102de26e0adSMurray Stokelydirectory and uses
103de26e0adSMurray Stokely.Xr mtree 1
104de26e0adSMurray Stokelyto build the directory hierarchy for the system.
105de26e0adSMurray Stokely.It Ar release.2
106de26e0adSMurray StokelyInstalls the system into the distribution directories.
107de26e0adSMurray Stokely.It Ar release.3
108994c71f0SMurray Stokely.\" XXX: This should either be "GENERIC kernel" (singular) or
109994c71f0SMurray Stokely.\" XXX: "GENERIC and <some other> kernels".
110994c71f0SMurray StokelyMakes and installs the
111994c71f0SMurray Stokely.Pa GENERIC
112994c71f0SMurray Stokelykernel.
113de26e0adSMurray Stokely.It Ar release.4
114de26e0adSMurray StokelyUses
115de26e0adSMurray Stokely.Xr crunchgen 1
116de26e0adSMurray Stokelyto build
117de26e0adSMurray Stokely.Sq crunched
118de26e0adSMurray Stokelybinaries to live on the installation floppies.
119de26e0adSMurray Stokely.It Ar release.5
120de26e0adSMurray StokelyBuilds synthetic distributions, and cleans up the previously built
121de26e0adSMurray Stokelydistribution trees.
122de26e0adSMurray Stokely.It Ar release.6
123de26e0adSMurray StokelyCreates tarballs of the assembled distribution trees.
124de26e0adSMurray Stokely.It Ar release.7
125de26e0adSMurray StokelyMakes source distributions.
126de26e0adSMurray Stokely.It Ar release.8
127de26e0adSMurray StokelyCreates the boot and MFS root floppies.
128de26e0adSMurray Stokely.It Ar release.9
129de26e0adSMurray StokelyCreates the fixit floppy.
130de26e0adSMurray Stokely.It Ar ftp.1
131de26e0adSMurray StokelySets up a suitable area for FTP installations.
132de26e0adSMurray Stokely.It Ar cdrom.1
133de26e0adSMurray StokelySets up a suitable area to build CDROM images.
134de26e0adSMurray Stokely.It Ar iso.1
135de26e0adSMurray StokelyBuilds two ISO images (installation and
136de26e0adSMurray Stokely.Sq live
137994c71f0SMurray Stokelyfilesystem) from the CDROM release area
138994c71f0SMurray Stokely(Disabled by default, see
139994c71f0SMurray Stokely.Pa MAKE_ISOS
140994c71f0SMurray Stokelybelow).
141de26e0adSMurray Stokely.It Ar doc.1
142994c71f0SMurray StokelyBuilds all of the necessary tools to turn the
143994c71f0SMurray Stokely.Fx
144994c71f0SMurray StokelyDocumentation Project source documents (SGML, XML) into HTML
145994c71f0SMurray Stokelyand text documents that will accompany the release.
146994c71f0SMurray StokelyAlso, builds and installs the actual user documentation.
147994c71f0SMurray StokelyThis includes the Handbook, FAQ, articles, and so on.
148de26e0adSMurray Stokely.It Ar doc.2
149994c71f0SMurray StokelyBuilds the release documentation.
150994c71f0SMurray StokelyThis includes the release notes,
151de26e0adSMurray Stokelyhardware guide, and installation instructions.
152de26e0adSMurray Stokely.El
153de26e0adSMurray Stokely.Sh ENVIRONMENT
154994c71f0SMurray StokelyVariables that must be specified:
155994c71f0SMurray Stokely.Bl -tag -width RELEASETAG
156de26e0adSMurray Stokely.It Ev CHROOTDIR
157de26e0adSMurray StokelyThe directory to be used as the
158de26e0adSMurray Stokely.Xr chroot 8
159de26e0adSMurray Stokelyenvironment for the entire release build.
160994c71f0SMurray Stokely.\" XXX: I recommend against hardcoding specific numbers like "2.3" here;
161994c71f0SMurray Stokely.\" XXX: perhaps it should be replaced with something to the effect of
162994c71f0SMurray Stokely.\" XXX: "we don't know how much space you'll need, but make sure you have
163994c71f0SMurray Stokely.\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number,
164994c71f0SMurray Stokely.\" XXX: but at least it looks less like a decree and more like an estimate.
165de26e0adSMurray StokelyThis filesystem should have at least 2.3 gigabytes of free space on the
166de26e0adSMurray Stokelyi386 architecture.
167de26e0adSMurray Stokely.It Ev BUILDNAME
168994c71f0SMurray StokelyThe name of the release to be built.
169994c71f0SMurray StokelyThis is used to set the
170994c71f0SMurray Stokely.Dv RELEASE
171de26e0adSMurray Stokelyvalue in
172de26e0adSMurray Stokely.Pa sys/conf/newvers.sh ,
173de26e0adSMurray Stokelywhich affects the output of
174de26e0adSMurray Stokely.Xr uname 1 .
175de26e0adSMurray Stokely.It Ev CVSROOT
176994c71f0SMurray StokelyThe location of the
177994c71f0SMurray Stokely.Fx
178994c71f0SMurray StokelyCVS repository.
179de26e0adSMurray Stokely.It Ev RELEASETAG
180994c71f0SMurray StokelyThe CVS tag corresponding to the release that is to be built.
181de26e0adSMurray StokelyIf undefined, the release will be built from the HEAD of the CVS tree
182de26e0adSMurray Stokely(a
183994c71f0SMurray Stokely.Sq -CURRENT snapshot ) .
184de26e0adSMurray Stokely.El
185de26e0adSMurray Stokely.Pp
186de26e0adSMurray StokelyOptional variables:
187994c71f0SMurray Stokely.Bl -tag -width RELEASEDISTFILES
188de26e0adSMurray Stokely.It Ev LOCAL_PATCHES
189de26e0adSMurray StokelyA patch file against
190de26e0adSMurray Stokely.Pa /usr/src
191de26e0adSMurray Stokelythat will be applied in the
192de26e0adSMurray Stokely.Xr chroot 8
193de26e0adSMurray Stokelyenvironment before the release build begins.
194de26e0adSMurray Stokely.It Ev PATCH_FLAGS
195de26e0adSMurray StokelyArguments for the
196de26e0adSMurray Stokely.Xr patch 1
197de26e0adSMurray Stokelycommand used to apply
198994c71f0SMurray Stokely.Ev LOCAL_PATCHES .
199de26e0adSMurray Stokely.It Ev MAKE_ISOS
200de26e0adSMurray StokelyIf defined, bootable ISO CDROM images will be created from the
201de26e0adSMurray Stokelycontents of the CDROM stage directory.
202de26e0adSMurray Stokely.It Ev NODOC
203de26e0adSMurray StokelyIf set to
204de26e0adSMurray Stokely.Dq YES
205994c71f0SMurray Stokelythen the documentation will not be built.
206994c71f0SMurray StokelyDue to the SGML-based
207de26e0adSMurray Stokelytoolchain and multiple languages supported by the
208de26e0adSMurray Stokely.Fx
209994c71f0SMurray StokelyDocumentation Project, this may speed up the release build considerably.
210de26e0adSMurray Stokely.It Ev NOPORTS
211de26e0adSMurray StokelyIf set to
212de26e0adSMurray Stokely.Dq YES
213de26e0adSMurray Stokelythen the ports tree will be omitted from the release.
214de26e0adSMurray Stokely.It Ev RELEASEDISTFILES
215de26e0adSMurray StokelyThe directory where the distribution files for ports required by the
216de26e0adSMurray Stokelyrelease build can be found.
217de26e0adSMurray StokelyThis may save a significant amount of time over downloading the
218de26e0adSMurray Stokelydistfiles through a slow link.
219de26e0adSMurray Stokely.It Ev RELEASENOUPDATE
220de26e0adSMurray StokelyIf this variable is defined for
221de26e0adSMurray Stokely.Dq make rerelease ,
222de26e0adSMurray Stokelythe source code will not be updated with
223de26e0adSMurray Stokely.Dq cvs up .
224de26e0adSMurray Stokely.El
225de26e0adSMurray Stokely.Sh FILES
226de26e0adSMurray Stokely.Bl -tag -compact
227de26e0adSMurray Stokely.It Pa /etc/make.conf
228de26e0adSMurray Stokely.It Pa /usr/doc/Makefile
229de26e0adSMurray Stokely.It Pa /usr/doc/share/mk/doc.project.mk
230de26e0adSMurray Stokely.It Pa /usr/ports/Mk/bsd.port.mk
231de26e0adSMurray Stokely.It Pa /usr/ports/Mk/bsd.sites.mk
232de26e0adSMurray Stokely.It Pa /usr/share/examples/etc/make.conf
233de26e0adSMurray Stokely.It Pa /usr/src/Makefile
234de26e0adSMurray Stokely.It Pa /usr/src/Makefile.inc1
235de26e0adSMurray Stokely.It Pa /usr/src/release/Makefile
236de26e0adSMurray Stokely.It Pa /usr/src/release/${arch}/drivers.conf
237de26e0adSMurray Stokely.It Pa /usr/src/release/${arch}/boot_crunch.conf
238de26e0adSMurray Stokely.It Pa /usr/src/release/${arch}/fixit_crunch.conf
239de26e0adSMurray Stokely.El
240de26e0adSMurray Stokely.Sh EXAMPLES
241994c71f0SMurray StokelyThe following sequence of commands was used to build the
242de26e0adSMurray Stokely.Fx 4.5
243de26e0adSMurray Stokelyrelease:
244de26e0adSMurray Stokely.Bd -literal -offset indent
245de26e0adSMurray Stokelycd /usr
246de26e0adSMurray Stokelycvs co -rRELENG_4_5_0_RELEASE src
247de26e0adSMurray Stokelycd src
248de26e0adSMurray Stokelymake buildworld
249de26e0adSMurray Stokelycd release
250de26e0adSMurray Stokelymake release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\
251de26e0adSMurray Stokely  CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_5_0_RELEASE
252de26e0adSMurray Stokely.Ed
253de26e0adSMurray Stokely.Pp
254de26e0adSMurray StokelyAfter running these commands, a complete system suitable for FTP or
255de26e0adSMurray StokelyCDROM distribution is available in the
256994c71f0SMurray Stokely.Pa /local3/release/R
257de26e0adSMurray Stokelydirectory.
258de26e0adSMurray Stokely.Pp
259994c71f0SMurray StokelyThe following sequence of commands can be used to build a
260994c71f0SMurray Stokely.Sq -CURRENT snapshot
261994c71f0SMurray Stokelyof a
262de26e0adSMurray Stokelylocally modified source tree:
263de26e0adSMurray Stokely.Bd -literal -offset indent
264de26e0adSMurray Stokelycd /usr/src
265de26e0adSMurray Stokelycvs diff -u > /path/to/local.patch
266de26e0adSMurray Stokelymake buildworld
267de26e0adSMurray Stokelycd release
268de26e0adSMurray Stokelymake release CHROOTDIR=/local3/release BUILDNAME=5.0-SNAPSHOT \\
269de26e0adSMurray Stokely CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
270de26e0adSMurray Stokely.Ed
271de26e0adSMurray Stokely.Sh SEE ALSO
272de26e0adSMurray Stokely.Xr cc 1 ,
273de26e0adSMurray Stokely.Xr crunchgen 1 ,
274de26e0adSMurray Stokely.Xr install 1 ,
275de26e0adSMurray Stokely.Xr make 1 ,
276de26e0adSMurray Stokely.Xr mtree 1 ,
277de26e0adSMurray Stokely.Xr patch 1 ,
278de26e0adSMurray Stokely.Xr uname 1 ,
279de26e0adSMurray Stokely.Xr make.conf 5 ,
280de26e0adSMurray Stokely.Xr build 7 ,
281de26e0adSMurray Stokely.Xr ports 7 ,
282de26e0adSMurray Stokely.Xr chroot 8
283994c71f0SMurray Stokely.Rs
284994c71f0SMurray Stokely.%T FreeBSD Release Engineering
285994c71f0SMurray Stokely.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
286994c71f0SMurray Stokely.Re
287994c71f0SMurray Stokely.Rs
288994c71f0SMurray Stokely.%T FreeBSD Release Engineering of Third Party Packages
289994c71f0SMurray Stokely.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
290994c71f0SMurray Stokely.Re
291994c71f0SMurray Stokely.Rs
292994c71f0SMurray Stokely.%T FreeBSD Developers' Handbook
293994c71f0SMurray Stokely.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
294994c71f0SMurray Stokely.Re
295de26e0adSMurray Stokely.Sh HISTORY
296de26e0adSMurray Stokely.Fx
297de26e0adSMurray Stokely1.x
298994c71f0SMurray Stokelyused a manual checklist, compiled by Rod Grimes, to produce a release.
299de26e0adSMurray StokelyApart from being incomplete, the list put a lot of specific demands on
300de26e0adSMurray Stokelyavailable filesystems and was quite torturous to execute.
301de26e0adSMurray Stokely.Pp
302994c71f0SMurray StokelyAs part of the
303994c71f0SMurray Stokely.Fx 2.0
304994c71f0SMurray Stokelyrelease engineering effort, significant
305de26e0adSMurray Stokelyeffort was spent getting
306de26e0adSMurray Stokely.Pa src/release/Makefile
307de26e0adSMurray Stokelyinto a shape where it could at least automate most of the tediousness
308de26e0adSMurray Stokelyof building a release in a sterile environment.
309de26e0adSMurray Stokely.Pp
310994c71f0SMurray StokelyWith its almost 1000 revisions spread over multiple branches, the CVS
311994c71f0SMurray Stokelylog of
312994c71f0SMurray Stokely.Pa src/release/Makefile
313994c71f0SMurray Stokelycontains a vivid historical record of some
314de26e0adSMurray Stokelyof the hardships release engineers go through.
315de26e0adSMurray Stokely.Sh AUTHORS
316de26e0adSMurray Stokely.Pa src/release/Makefile
317994c71f0SMurray Stokelywas originally written by Rod Grimes, Jordan Hubbard, and Poul-Henning Kamp.
318994c71f0SMurray StokelyThis manual page was written by
319de26e0adSMurray Stokely.An Murray Stokely Aq murray@FreeBSD.org .
320