xref: /freebsd/share/man/man7/release.7 (revision de26e0ad7aba92e4c0fb62a2a10c8b92716841da)
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
32de26e0adSMurray Stokely.Nd information on the process used to build a complete system release
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
38de26e0adSMurray 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
49de26e0adSMurray Stokelyexperienced 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
62de26e0adSMurray Stokely.Pa md
63de26e0adSMurray Stokely(memory disk) device driver be present in the kernel.
64de26e0adSMurray Stokely.Pp
65de26e0adSMurray StokelyThis document does not cover source code management, quality
66de26e0adSMurray Stokelyassurance, or other aspects of the release engineering process.
67de26e0adSMurray Stokely.Sh TARGETS
68de26e0adSMurray Stokely.Pp
69de26e0adSMurray StokelyThe release makefile
70de26e0adSMurray Stokely.Pa (src/release/makefile)
71de26e0adSMurray Stokelyis fairly abstruse.
72de26e0adSMurray StokelyMost developers will only be concerned with the
73de26e0adSMurray Stokely.Pa release
74de26e0adSMurray Stokelytarget.
75de26e0adSMurray Stokely.Bl -tag -width configure
76de26e0adSMurray Stokely.It Ar release
77de26e0adSMurray StokelyUses
78de26e0adSMurray Stokely.Dq make installworld
79de26e0adSMurray Stokelyto install a clean system into a
80de26e0adSMurray Stokely.Xr chroot 8
81de26e0adSMurray Stokelyenvironment on the filesystem.
82de26e0adSMurray StokelyChecks out the specified version of the source code and then rebuilds
83de26e0adSMurray Stokelythe entire system in the clean environment with
84de26e0adSMurray Stokely.Dq make world .
85de26e0adSMurray StokelyThe detailed steps that follow are then executed to package up the
86de26e0adSMurray Stokelydifferent distributions, build the installation floppy disks, build
87de26e0adSMurray Stokelyrelease documentation, and so on.
88de26e0adSMurray Stokely.It Ar rerelease
89de26e0adSMurray StokelyAssumes that the output of a release build has been manually modified,
90de26e0adSMurray Stokelyand performs the minimal number of steps to rebuild the release using
91de26e0adSMurray Stokelythe intermediate output of the previous
92de26e0adSMurray Stokely.Dq make release .
93de26e0adSMurray Stokely.El
94de26e0adSMurray Stokely.Pp
95de26e0adSMurray StokelyTargets called by
96de26e0adSMurray Stokely.Dq make release .
97de26e0adSMurray Stokely.Bl -tag -width configure
98de26e0adSMurray Stokely.It Ar release.1
99de26e0adSMurray StokelyCleans out the
100de26e0adSMurray Stokely.Pa ${CHROOTDIR}/R
101de26e0adSMurray Stokelydirectory and uses
102de26e0adSMurray Stokely.Xr mtree 1
103de26e0adSMurray Stokelyto build the directory hierarchy for the system.
104de26e0adSMurray Stokely.It Ar release.2
105de26e0adSMurray StokelyInstalls the system into the distribution directories.
106de26e0adSMurray Stokely.It Ar release.3
107de26e0adSMurray StokelyMakes and installs the GENERIC kernel(s).
108de26e0adSMurray Stokely.It Ar release.4
109de26e0adSMurray StokelyUses
110de26e0adSMurray Stokely.Xr crunchgen 1
111de26e0adSMurray Stokelyto build
112de26e0adSMurray Stokely.Sq crunched
113de26e0adSMurray Stokelybinaries to live on the installation floppies.
114de26e0adSMurray Stokely.It Ar release.5
115de26e0adSMurray StokelyBuilds synthetic distributions, and cleans up the previously built
116de26e0adSMurray Stokelydistribution trees.
117de26e0adSMurray Stokely.It Ar release.6
118de26e0adSMurray StokelyCreates tarballs of the assembled distribution trees.
119de26e0adSMurray Stokely.It Ar release.7
120de26e0adSMurray StokelyMakes source distributions.
121de26e0adSMurray Stokely.It Ar release.8
122de26e0adSMurray StokelyCreates the boot and MFS root floppies.
123de26e0adSMurray Stokely.It Ar release.9
124de26e0adSMurray StokelyCreates the fixit floppy.
125de26e0adSMurray Stokely.It Ar ftp.1
126de26e0adSMurray StokelySets up a suitable area for FTP installations.
127de26e0adSMurray Stokely.It Ar cdrom.1
128de26e0adSMurray StokelySets up a suitable area to build CDROM images.
129de26e0adSMurray Stokely.It Ar iso.1
130de26e0adSMurray StokelyBuilds two ISO images (installation and
131de26e0adSMurray Stokely.Sq live
132de26e0adSMurray Stokelyfilesystem) from the CDROM release area.
133de26e0adSMurray Stokely.It Ar doc.1
134de26e0adSMurray StokelyBuilds all of the necessary tools to turn the FreeBSD Documentation
135de26e0adSMurray StokelyProject source documents (SGML, XML) into HTML and text documents that
136de26e0adSMurray Stokelywill accompany the release.  Also, builds and installs the actual
137de26e0adSMurray Stokelyuser documentation.  This includes the Handbook, FAQ, articles, and so
138de26e0adSMurray Stokelyon.
139de26e0adSMurray Stokely.It Ar doc.2
140de26e0adSMurray StokelyBuilds the release documentation.  This includes the release notes,
141de26e0adSMurray Stokelyhardware guide, and installation instructions.
142de26e0adSMurray Stokely.El
143de26e0adSMurray Stokely.Sh ENVIRONMENT
144de26e0adSMurray Stokely.Pp
145de26e0adSMurray StokelyVariables that you must specify:
146de26e0adSMurray Stokely.Bl -tag -width configure
147de26e0adSMurray Stokely.It Ev CHROOTDIR
148de26e0adSMurray StokelyThe directory to be used as the
149de26e0adSMurray Stokely.Xr chroot 8
150de26e0adSMurray Stokelyenvironment for the entire release build.
151de26e0adSMurray StokelyThis filesystem should have at least 2.3 gigabytes of free space on the
152de26e0adSMurray Stokelyi386 architecture.
153de26e0adSMurray Stokely.It Ev BUILDNAME
154de26e0adSMurray StokelyThe name of the release to be built.  This is used to set the
155de26e0adSMurray Stokely.Pa RELEASE
156de26e0adSMurray Stokelyvalue in
157de26e0adSMurray Stokely.Pa sys/conf/newvers.sh ,
158de26e0adSMurray Stokelywhich affects the output of
159de26e0adSMurray Stokely.Xr uname 1 .
160de26e0adSMurray Stokely.It Ev CVSROOT
161de26e0adSMurray StokelyThe location of a CVS Repository.
162de26e0adSMurray Stokely.It Ev RELEASETAG
163de26e0adSMurray StokelyThe CVS tag corresponding to the release you would like to build.
164de26e0adSMurray StokelyIf undefined, the release will be built from the HEAD of the CVS tree
165de26e0adSMurray Stokely(a
166de26e0adSMurray Stokely.Sq -CURRENT snapshot
167de26e0adSMurray Stokely).
168de26e0adSMurray Stokely.El
169de26e0adSMurray Stokely.Pp
170de26e0adSMurray StokelyOptional variables:
171de26e0adSMurray Stokely.Bl -tag -width configure
172de26e0adSMurray Stokely.It Ev LOCAL_PATCHES
173de26e0adSMurray StokelyA patch file against
174de26e0adSMurray Stokely.Pa /usr/src
175de26e0adSMurray Stokelythat will be applied in the
176de26e0adSMurray Stokely.Xr chroot 8
177de26e0adSMurray Stokelyenvironment before the release build begins.
178de26e0adSMurray Stokely.It Ev PATCH_FLAGS
179de26e0adSMurray StokelyArguments for the
180de26e0adSMurray Stokely.Xr patch 1
181de26e0adSMurray Stokelycommand used to apply
182de26e0adSMurray Stokely.Pa LOCAL_PATCHES .
183de26e0adSMurray Stokely.It Ev MAKE_ISOS
184de26e0adSMurray StokelyIf defined, bootable ISO CDROM images will be created from the
185de26e0adSMurray Stokelycontents of the CDROM stage directory.
186de26e0adSMurray Stokely.It Ev NODOC
187de26e0adSMurray StokelyIf set to
188de26e0adSMurray Stokely.Dq YES
189de26e0adSMurray Stokelythen the documentation will not be built.  Due to the SGML based
190de26e0adSMurray Stokelytoolchain and multiple languages supported by the
191de26e0adSMurray Stokely.Fx
192de26e0adSMurray StokelyDocumentation Project, this may speed up the release build time
193de26e0adSMurray Stokelyconsiderably.
194de26e0adSMurray Stokely.It Ev NOPORTS
195de26e0adSMurray StokelyIf set to
196de26e0adSMurray Stokely.Dq YES
197de26e0adSMurray Stokelythen the ports tree will be omitted from the release.
198de26e0adSMurray Stokely.It Ev RELEASEDISTFILES
199de26e0adSMurray StokelyThe directory where the distribution files for ports required by the
200de26e0adSMurray Stokelyrelease build can be found.
201de26e0adSMurray StokelyThis may save a significant amount of time over downloading the
202de26e0adSMurray Stokelydistfiles through a slow link.
203de26e0adSMurray Stokely.It Ev RELEASENOUPDATE
204de26e0adSMurray StokelyIf this variable is defined for
205de26e0adSMurray Stokely.Dq make rerelease ,
206de26e0adSMurray Stokelythe source code will not be updated with
207de26e0adSMurray Stokely.Dq cvs up .
208de26e0adSMurray Stokely.El
209de26e0adSMurray Stokely.Sh FILES
210de26e0adSMurray Stokely.Bl -tag -compact
211de26e0adSMurray Stokely.It Pa /etc/make.conf
212de26e0adSMurray Stokely.It Pa /usr/doc/Makefile
213de26e0adSMurray Stokely.It Pa /usr/doc/share/mk/doc.project.mk
214de26e0adSMurray Stokely.It Pa /usr/ports/Mk/bsd.port.mk
215de26e0adSMurray Stokely.It Pa /usr/ports/Mk/bsd.sites.mk
216de26e0adSMurray Stokely.It Pa /usr/share/examples/etc/make.conf
217de26e0adSMurray Stokely.It Pa /usr/src/Makefile
218de26e0adSMurray Stokely.It Pa /usr/src/Makefile.inc1
219de26e0adSMurray Stokely.It Pa /usr/src/release/Makefile
220de26e0adSMurray Stokely.It Pa /usr/src/release/${arch}/drivers.conf
221de26e0adSMurray Stokely.It Pa /usr/src/release/${arch}/boot_crunch.conf
222de26e0adSMurray Stokely.It Pa /usr/src/release/${arch}/fixit_crunch.conf
223de26e0adSMurray Stokely.El
224de26e0adSMurray Stokely.Sh EXAMPLES
225de26e0adSMurray StokelyThe following commands were used to build the
226de26e0adSMurray Stokely.Fx 4.5
227de26e0adSMurray Stokelyrelease :
228de26e0adSMurray Stokely.Bd -literal -offset indent
229de26e0adSMurray Stokelycd /usr
230de26e0adSMurray Stokelycvs co -rRELENG_4_5_0_RELEASE src
231de26e0adSMurray Stokelycd src
232de26e0adSMurray Stokelymake buildworld
233de26e0adSMurray Stokelycd release
234de26e0adSMurray Stokelymake release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\
235de26e0adSMurray Stokely  CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_5_0_RELEASE
236de26e0adSMurray Stokely.Ed
237de26e0adSMurray Stokely.Pp
238de26e0adSMurray StokelyAfter running these commands, a complete system suitable for FTP or
239de26e0adSMurray StokelyCDROM distribution is available in the
240de26e0adSMurray Stokely.Pa /local3/release/R/
241de26e0adSMurray Stokelydirectory.
242de26e0adSMurray Stokely.Pp
243de26e0adSMurray StokelyThe following commands can be used to build a -CURRENT snapshot of a
244de26e0adSMurray Stokelylocally modified source tree :
245de26e0adSMurray Stokely.Bd -literal -offset indent
246de26e0adSMurray Stokelycd /usr/src
247de26e0adSMurray Stokelycvs diff -u > /path/to/local.patch
248de26e0adSMurray Stokelymake buildworld
249de26e0adSMurray Stokelycd release
250de26e0adSMurray Stokelymake release CHROOTDIR=/local3/release BUILDNAME=5.0-SNAPSHOT \\
251de26e0adSMurray Stokely CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
252de26e0adSMurray Stokely.Ed
253de26e0adSMurray Stokely.Sh SEE ALSO
254de26e0adSMurray Stokely.Xr cc 1 ,
255de26e0adSMurray Stokely.Xr crunchgen 1 ,
256de26e0adSMurray Stokely.Xr install 1 ,
257de26e0adSMurray Stokely.Xr make 1 ,
258de26e0adSMurray Stokely.Xr mtree 1 ,
259de26e0adSMurray Stokely.Xr patch 1 ,
260de26e0adSMurray Stokely.Xr uname 1 ,
261de26e0adSMurray Stokely.Xr make.conf 5 ,
262de26e0adSMurray Stokely.Xr build 7 ,
263de26e0adSMurray Stokely.Xr ports 7 ,
264de26e0adSMurray Stokely.Xr chroot 8
265de26e0adSMurray Stokely.Pp
266de26e0adSMurray Stokely.Fx
267de26e0adSMurray StokelyRelease Engineering
268de26e0adSMurray Stokelyhttp://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng
269de26e0adSMurray Stokely.Pp
270de26e0adSMurray Stokely.Fx
271de26e0adSMurray StokelyRelease Engineering of Third Party Packages
272de26e0adSMurray Stokelyhttp://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages
273de26e0adSMurray Stokely.Pp
274de26e0adSMurray Stokely.Fx
275de26e0adSMurray StokelyDeveloper's Handbook
276de26e0adSMurray Stokelyhttp://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook
277de26e0adSMurray Stokely.Sh HISTORY
278de26e0adSMurray Stokely.Pp
279de26e0adSMurray Stokely.Fx
280de26e0adSMurray Stokely1.x
281de26e0adSMurray Stokelyused a manual checklist, compiled by Rod Grimes to produce a release.
282de26e0adSMurray StokelyApart from being incomplete, the list put a lot of specific demands on
283de26e0adSMurray Stokelyavailable filesystems and was quite torturous to execute.
284de26e0adSMurray Stokely.Pp
285de26e0adSMurray StokelyAs part of the FreeBSD 2.0 release engineering effort, significant
286de26e0adSMurray Stokelyeffort was spent getting
287de26e0adSMurray Stokely.Pa src/release/Makefile
288de26e0adSMurray Stokelyinto a shape where it could at least automate most of the tediousness
289de26e0adSMurray Stokelyof building a release in a sterile environment.
290de26e0adSMurray Stokely.Pp
291de26e0adSMurray StokelyWith its almost 1000 revisions spread over multiple branches, the cvs
292de26e0adSMurray Stokelylog of src/release/Makefile contains a vivid historical record of some
293de26e0adSMurray Stokelyof the hardships release engineers go through.
294de26e0adSMurray Stokely.Sh AUTHORS
295de26e0adSMurray Stokely.Pa src/release/Makefile
296de26e0adSMurray Stokelywas originally written by Rod Grimes, Jordan Hubbard, and Poul-Henning
297de26e0adSMurray StokelyKamp.
298de26e0adSMurray StokelyThis man page was written by
299de26e0adSMurray Stokely.An Murray Stokely Aq murray@FreeBSD.org .
300