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.\"
| 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: head/share/man/man7/release.7 262499 2014-02-25 22:13:48Z gjb $
| 25.\" $FreeBSD: head/share/man/man7/release.7 262810 2014-03-05 23:17:53Z gjb $
|
26.\"
| 26.\"
|
27.Dd February 25, 2014
| 27.Dd March 5, 2014
|
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.
| 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 CHROOT_MAKEENV
142Additional
143.Xr make 1
144arguments to pass through, which directly affect the
145tuning of the build chroot.
|
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.It Va WITH_DVD
245Set to a non-empty value to include the
246.Cm dvdrom
247target.
248.It Va VCSCMD
249The command run to obtain the source trees.
250Defaults to
251.Qq Cm svn checkout .
| 146.It Va SVNROOT
147The
148.Xr svn 1
149host used to check out the various trees.
150Defaults to
151.Pa svn://svn.FreeeBSD.org .
152.It Va SRCBRANCH
153The
154.Li src/
155branch to use.
156Defaults to
157.Va head/@rHEAD .
158.It Va DOCBRANCH
159The
160.Li doc/
161branch to use.
162Defaults to
163.Va head/@rHEAD .
164.It Va PORTBRANCH
165The
166.Li ports/
167branch to use.
168Defaults to
169.Va head/@rHEAD .
170.It Va TARGET
171The target machine type for cross-building a release.
172.It Va TARGET_ARCH
173The target machine architecture for cross-building a release.
174.Pp
175For the supported list of
176.Va TARGET
177and
178.Va TARGET_ARCH
179combinations, consult the output of
180.Dq make targets
181as documented in
182.Xr build 7 .
183.It Va KERNEL
184The target kernel configuration to use.
185Defaults to
186.Va GENERIC .
187Multiple
188.Va KERNEL
189entries may be specified.
190.It Va MAKE_CONF
191The
192.Xr make.conf 5
193to use for the release build.
194Defaults to
195.Fa /dev/null
196to prevent polluting the release with local system changes.
197.It Va SRC_CONF
198The
199.Xr src.conf 5
200to use for the release build.
201Defaults to
202.Fa /dev/null
203to prevent polluting the release with local system changes.
204.It Va MAKE_FLAGS
205Additional flags to pass to
206.Xr make 1 .
207.It Va WORLD_FLAGS
208Additional flags to pass to
209.Xr make 1
210during the
211.Dq buildworld
212phase.
213Defaults to setting the number of
214.Xr make 1
215jobs
216.Pq Ar -j
217to the number of CPUs available on a SMP-capable system.
218.It Va KERNEL_FLAGS
219Additional flags to pass to
220.Xr make 1
221during the
222.Dq buildkernel
223phase.
224Defaults to setting the number of
225.Xr make 1
226jobs
227.Pq Ar -j
228to half the number of CPUs available on a SMP-capable system.
229.It Va NODOC
230Set to a non-empty value to skip the
231.Li doc/
232tree checkout.
233When set,
234.Va NODOC
235will prevent the
236.Fa doc.txz
237distribution package from being created.
238.It Va NOPORTS
239Set to a non-empty value to skip the
240.Li ports/
241tree checkout.
242When set,
243.Va NOPORTS
244will prevent the
245.Fa ports.txz
246distribution package from being created.
247Setting this also sets
248.Va NODOC .
249.It Va WITH_DVD
250Set to a non-empty value to include the
251.Cm dvdrom
252target.
253.It Va VCSCMD
254The command run to obtain the source trees.
255Defaults to
256.Qq Cm svn checkout .
|
| 257.It Va CHROOTBUILD_SKIP
258If defined, the
259.Li buildworld ,
260.Li installworld ,
261and
262.Li distribution
263stages of the
264.Xr chroot 8
265build environment setup are skipped.
266This is intended solely for cases where the
267.Xr chroot 8
268userland are provided by alternate means.
|
252.El
| 269.El
|
| 270.Sh EMBEDDED BUILDS
271The following
272.Fa release.conf
273variables are relevant only to release builds for embedded systems:
274.Bl -tag -width Ev
275.It Va EMBEDDEDBUILD
276Set to a non-null value to enable functionality for embedded device
277release builds.
278.Pq This option is considered highly experimental.
279.Pp
280When set,
281.Va WITH_DVD
282is unset, and
283.Va NODOC
284is defined.
285Additionally,
286.Va XDEV
287and
288.Va XDEV_ARCH
289must also be defined.
290When the build environment is created,
291.Fa release.sh
292runs a separate build script located in an architecture-specific
293directory in
294.Pa src/release/${XDEV}/ .
295.It Va EMBEDDEDPORTS
296Set to the list of any ports that are required for the target device
297in the format of
298.Fa category/port .
299The
300.Fa devel/subversion
301port is built by default.
302.It Va CROCHETSRC
303Set to the source URL for the Crochet build tool.
304.It Va CROCHETBRANCH
305Set to the subversion branch from
306.Va ${CROCHETSRC}
307to use.
308Defaults to
309.Pa trunk .
310.It Va UBOOTSRC
311Set to the source URL of u-boot, if required.
312.It Va UBOOTBRANCH
313Set to the subversion branch from
314.Va ${UBOOTSRC}
315to use.
316Defaults to
317.Pa trunk .
318.It Va UBOOTDIR
319Set to the target directory within
320.Va ${CHROOTDIR}
321to check out
322.Va ${UBOOTSRC}/${UBOOTBRANCH} .
323.El
|
253.Sh MAKEFILE TARGETS
254The release makefile
255.Pq Pa src/release/Makefile
256is fairly abstruse.
257Most developers will only be concerned with the
258.Cm release
259and
260.Cm install
261targets.
262.\" XXX: Some sort of introduction to this list? All the others have one.
263.Bl -tag -width ".Cm packagesystem"
264.It Cm release
265Meta-target to build all release media and distributions applicable to this
266platform.
267.It Cm install
268Copy all produced release media to
269.Pa ${DESTDIR} .
270.It Cm cdrom
271Builds installation CD-ROM images.
272This may require the
273.Xr md 4
274(memory disk) device driver be present in the kernel
275(either by being compiled in or available as a module).
276This target produces files called
277.Pa disc1.iso
278and
279.Pa bootonly.iso
280as its output.
281.It Cm dvdrom
282Builds installation DVD-ROM images.
283This may require the
284.Xr md 4
285(memory disk) device driver be present in the kernel
286(either by being compiled in or available as a module).
287This target produces the
288.Pa dvd1.iso
289file as its output.
290.It Cm memstick
291Builds an installation memory stick image named
292.Pa memstick.img .
293Not applicable on all platforms.
294Requires that the
295.Xr md 4
296.Pq memory disk
297device driver be present in the kernel
298.Pq either by being compiled in or available as a module .
299.It Cm mini-memstick
300Similar to
301.Cm memstick ,
302with the exception that the installation distribution sets
303are not included.
304.It Cm ftp
305Creates a directory named
306.Pa ftp
307containing the distribution files used in network installations
308and suitable for upload to an FTP mirror.
309.El
310.Pp
311Major subtargets called by targets above:
312.Bl -tag -width ".Cm packagesystem"
313.It Cm packagesystem
314Generates all the distribution archives
315.Pq base, kernel, ports, doc
316applicable on this platform.
317.It Cm system
318Builds a bootable installation system containing all the distribution files
319packaged by the
320.Cm packagesystem
321target, and suitable for imaging by the
322.Cm cdrom ,
323.Cm dvdrom
324and
325.Cm memstick
326targets.
327.It Cm reldoc
328Builds the release documentation.
329This includes the release notes,
330hardware guide, and installation instructions.
331Other documentation, such as the Handbook,
332is built during the
333.Cm base.txz
334target invoked by
335.Cm packagesystem .
336.El
337.Sh ENVIRONMENT
338Optional variables:
339.Bl -tag -width ".Ev TARGET_ARCH"
340.It Ev OSRELEASE
341Optional base name for generated media images
342.Pq e.g., FreeBSD-9.0-RC2-amd64 .
343Defaults to the output of
344.Ic `uname -s`-`uname -r`-`uname -p`
345within the chroot.
346.It Ev WORLDDIR
347Location of a directory containing the src tree.
348By default, the directory
349above the one containing the makefile
350.Pq Pa src .
351.It Ev PORTSDIR
352Location of a directory containing the ports tree.
353By default,
354.Pa /usr/ports .
355If it is unset or cannot be found, ports will not be included in the release.
356.It Ev DOCDIR
357Location of a directory containing the doc tree.
358By default,
359.Pa /usr/doc .
360If it is unset or cannot be found, most documentation will not be included in
361the release; see
362.Ev NODOC
363below.
364.It Ev NOPORTS
365If defined, the Ports Collection will be omitted from the release.
366.It Ev NOSRC
367If set, do not include system source code in the release.
368.It Ev NODOC
369If defined, the XML-based documentation from the
370.Fx
371Documentation Project will not be built.
372However, the
373.Dq doc
374distribution will still be created with the minimal documentation set
375provided in
376.Pa src/share/doc .
377.It Ev TARGET
378The target hardware platform.
379This is analogous to the
380.Dq Nm uname Fl m
381output.
382This is necessary to cross-build some target architectures.
383For example, cross-building for PC98 machines requires
384.Ev TARGET_ARCH Ns = Ns Li i386
385and
386.Ev TARGET Ns = Ns Li pc98 .
387If not set,
388.Ev TARGET
389defaults to the current hardware platform.
390.It Ev TARGET_ARCH
391The target machine processor architecture.
392This is analogous to the
393.Dq Nm uname Fl p
394output.
395Set this to cross-build for a different architecture.
396If not set,
397.Ev TARGET_ARCH
398defaults to the current machine architecture, unless
399.Ev TARGET
400is also set, in which case it defaults to the appropriate
401value for that platform.
402Typically, one only needs to set
403.Ev TARGET .
404.El
405.Sh FILES
406.Bl -tag -compact -width Pa
407.It Pa /usr/doc/Makefile
408.It Pa /usr/doc/share/mk/doc.project.mk
409.It Pa /usr/ports/Mk/bsd.port.mk
410.It Pa /usr/ports/Mk/bsd.sites.mk
411.It Pa /usr/share/examples/etc/make.conf
412.It Pa /usr/src/Makefile
413.It Pa /usr/src/Makefile.inc1
414.It Pa /usr/src/release/Makefile
415.It Pa /usr/src/release/release.sh
416.It Pa /usr/src/release/release.conf.sample
417.El
418.Sh EXAMPLES
419The following sequence of commands can be used to build a
420.Dq "-CURRENT snapshot":
421.Bd -literal -offset indent
422cd /usr
423svn co svn://svn.freebsd.org/base/head src
424cd src
425make buildworld buildkernel
426cd release
427make release
428make install DESTDIR=/var/freebsd-snapshot
429.Ed
430.Pp
431After running these commands, all produced distribution files (tarballs
432for FTP, CD-ROM images, etc.) are available in the
433.Pa /var/freebsd-snapshot
434directory.
435.Pp
436The following sequence of commands can be used to build a
437.Dq "-CURRENT snapshot"
438in a clean environment, including ports and documentation:
439.Bd -literal -offset indent
440cd /usr/src/release
441sh release.sh
442.Ed
443.Pp
444Optionally, a configuration file can be used customize the release build,
445such as the subversion revision to use, the branch of the subversion tree for
446.Li src/ ,
447.Li ports/ ,
448and
449.Li doc/ .
450.Bd -literal -offset indent
451cd /usr/src/release
452sh release.sh -c $HOME/release.conf
453.Ed
454.Pp
455After running these commands, all prepared release files are available in the
456.Pa /scratch
457directory.
458The target directory can be changed by specifying the
459.Va CHROOTDIR
460variable in
461.Li release.conf .
462.Sh SEE ALSO
463.Xr cc 1 ,
464.Xr install 1 ,
465.Xr make 1 ,
466.Xr svn 1 Pq Pa ports/devel/subversion ,
467.Xr uname 1 ,
468.Xr md 4 ,
469.Xr make.conf 5 ,
470.Xr build 7 ,
471.Xr ports 7 ,
472.Xr chroot 8 ,
473.Xr mtree 8 ,
474.Xr sysctl 8
475.Rs
476.%T "FreeBSD Release Engineering"
477.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
478.Re
479.Rs
480.%T "FreeBSD Release Engineering of Third Party Packages"
481.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
482.Re
483.Rs
484.%T "FreeBSD Developers' Handbook"
485.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
486.Re
487.Sh HISTORY
488.Fx
4891.x
490used a manual checklist, compiled by
491.An Rod Grimes ,
492to produce a release.
493Apart from being incomplete, the list put a lot of specific demands on
494available file systems and was quite torturous to execute.
495.Pp
496As part of the
497.Fx 2.0
498release engineering effort, significant
499effort was spent getting
500.Pa src/release/Makefile
501into a shape where it could at least automate most of the tediousness
502of building a release in a sterile environment.
503.Pp
504For the
505.Fx 9.0
506release,
507.Pa src/release/Makefile
508was overhauled and the wrapper script
509.Pa src/release/generate-release.sh
510introduced to support the introduction of a new installer.
511.Pp
512For the
513.Fx 9.2
514release,
515.Pa src/release/release.sh
516was introduced to support per-build configuration files.
517.Pa src/release/release.sh
518is heavily based on the
519.Pa src/release/generate-release.sh
520script.
521.Pp
522At near 1000 revisions spread over multiple branches, the
523.Xr svn 1
524log of
525.Pa src/release/Makefile
526contains a vivid historical record of some
527of the hardships release engineers go through.
528.Sh AUTHORS
529.Pa src/release/Makefile
530was originally written by
531.An -nosplit
532.An Rod Grimes ,
533.An Jordan Hubbard ,
534and
535.An Poul-Henning Kamp .
536.Pp
537This manual page was originally written by
538.An Murray Stokely Aq murray@FreeBSD.org .
539.Pp
540It was updated by
541.An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org
542to include the
543.Fa generate-release.sh
544script used for the
545.Fx 9.0
546release cycle.
547.Pp
548It was later updated by
549.An Glen Barber Aq gjb@FreeBSD.org
550to include the
551.Fa release.sh
552script used for the
553.Fx 9.2
554release cycle.
| 324.Sh MAKEFILE TARGETS
325The release makefile
326.Pq Pa src/release/Makefile
327is fairly abstruse.
328Most developers will only be concerned with the
329.Cm release
330and
331.Cm install
332targets.
333.\" XXX: Some sort of introduction to this list? All the others have one.
334.Bl -tag -width ".Cm packagesystem"
335.It Cm release
336Meta-target to build all release media and distributions applicable to this
337platform.
338.It Cm install
339Copy all produced release media to
340.Pa ${DESTDIR} .
341.It Cm cdrom
342Builds installation CD-ROM images.
343This may require the
344.Xr md 4
345(memory disk) device driver be present in the kernel
346(either by being compiled in or available as a module).
347This target produces files called
348.Pa disc1.iso
349and
350.Pa bootonly.iso
351as its output.
352.It Cm dvdrom
353Builds installation DVD-ROM images.
354This may require the
355.Xr md 4
356(memory disk) device driver be present in the kernel
357(either by being compiled in or available as a module).
358This target produces the
359.Pa dvd1.iso
360file as its output.
361.It Cm memstick
362Builds an installation memory stick image named
363.Pa memstick.img .
364Not applicable on all platforms.
365Requires that the
366.Xr md 4
367.Pq memory disk
368device driver be present in the kernel
369.Pq either by being compiled in or available as a module .
370.It Cm mini-memstick
371Similar to
372.Cm memstick ,
373with the exception that the installation distribution sets
374are not included.
375.It Cm ftp
376Creates a directory named
377.Pa ftp
378containing the distribution files used in network installations
379and suitable for upload to an FTP mirror.
380.El
381.Pp
382Major subtargets called by targets above:
383.Bl -tag -width ".Cm packagesystem"
384.It Cm packagesystem
385Generates all the distribution archives
386.Pq base, kernel, ports, doc
387applicable on this platform.
388.It Cm system
389Builds a bootable installation system containing all the distribution files
390packaged by the
391.Cm packagesystem
392target, and suitable for imaging by the
393.Cm cdrom ,
394.Cm dvdrom
395and
396.Cm memstick
397targets.
398.It Cm reldoc
399Builds the release documentation.
400This includes the release notes,
401hardware guide, and installation instructions.
402Other documentation, such as the Handbook,
403is built during the
404.Cm base.txz
405target invoked by
406.Cm packagesystem .
407.El
408.Sh ENVIRONMENT
409Optional variables:
410.Bl -tag -width ".Ev TARGET_ARCH"
411.It Ev OSRELEASE
412Optional base name for generated media images
413.Pq e.g., FreeBSD-9.0-RC2-amd64 .
414Defaults to the output of
415.Ic `uname -s`-`uname -r`-`uname -p`
416within the chroot.
417.It Ev WORLDDIR
418Location of a directory containing the src tree.
419By default, the directory
420above the one containing the makefile
421.Pq Pa src .
422.It Ev PORTSDIR
423Location of a directory containing the ports tree.
424By default,
425.Pa /usr/ports .
426If it is unset or cannot be found, ports will not be included in the release.
427.It Ev DOCDIR
428Location of a directory containing the doc tree.
429By default,
430.Pa /usr/doc .
431If it is unset or cannot be found, most documentation will not be included in
432the release; see
433.Ev NODOC
434below.
435.It Ev NOPORTS
436If defined, the Ports Collection will be omitted from the release.
437.It Ev NOSRC
438If set, do not include system source code in the release.
439.It Ev NODOC
440If defined, the XML-based documentation from the
441.Fx
442Documentation Project will not be built.
443However, the
444.Dq doc
445distribution will still be created with the minimal documentation set
446provided in
447.Pa src/share/doc .
448.It Ev TARGET
449The target hardware platform.
450This is analogous to the
451.Dq Nm uname Fl m
452output.
453This is necessary to cross-build some target architectures.
454For example, cross-building for PC98 machines requires
455.Ev TARGET_ARCH Ns = Ns Li i386
456and
457.Ev TARGET Ns = Ns Li pc98 .
458If not set,
459.Ev TARGET
460defaults to the current hardware platform.
461.It Ev TARGET_ARCH
462The target machine processor architecture.
463This is analogous to the
464.Dq Nm uname Fl p
465output.
466Set this to cross-build for a different architecture.
467If not set,
468.Ev TARGET_ARCH
469defaults to the current machine architecture, unless
470.Ev TARGET
471is also set, in which case it defaults to the appropriate
472value for that platform.
473Typically, one only needs to set
474.Ev TARGET .
475.El
476.Sh FILES
477.Bl -tag -compact -width Pa
478.It Pa /usr/doc/Makefile
479.It Pa /usr/doc/share/mk/doc.project.mk
480.It Pa /usr/ports/Mk/bsd.port.mk
481.It Pa /usr/ports/Mk/bsd.sites.mk
482.It Pa /usr/share/examples/etc/make.conf
483.It Pa /usr/src/Makefile
484.It Pa /usr/src/Makefile.inc1
485.It Pa /usr/src/release/Makefile
486.It Pa /usr/src/release/release.sh
487.It Pa /usr/src/release/release.conf.sample
488.El
489.Sh EXAMPLES
490The following sequence of commands can be used to build a
491.Dq "-CURRENT snapshot":
492.Bd -literal -offset indent
493cd /usr
494svn co svn://svn.freebsd.org/base/head src
495cd src
496make buildworld buildkernel
497cd release
498make release
499make install DESTDIR=/var/freebsd-snapshot
500.Ed
501.Pp
502After running these commands, all produced distribution files (tarballs
503for FTP, CD-ROM images, etc.) are available in the
504.Pa /var/freebsd-snapshot
505directory.
506.Pp
507The following sequence of commands can be used to build a
508.Dq "-CURRENT snapshot"
509in a clean environment, including ports and documentation:
510.Bd -literal -offset indent
511cd /usr/src/release
512sh release.sh
513.Ed
514.Pp
515Optionally, a configuration file can be used customize the release build,
516such as the subversion revision to use, the branch of the subversion tree for
517.Li src/ ,
518.Li ports/ ,
519and
520.Li doc/ .
521.Bd -literal -offset indent
522cd /usr/src/release
523sh release.sh -c $HOME/release.conf
524.Ed
525.Pp
526After running these commands, all prepared release files are available in the
527.Pa /scratch
528directory.
529The target directory can be changed by specifying the
530.Va CHROOTDIR
531variable in
532.Li release.conf .
533.Sh SEE ALSO
534.Xr cc 1 ,
535.Xr install 1 ,
536.Xr make 1 ,
537.Xr svn 1 Pq Pa ports/devel/subversion ,
538.Xr uname 1 ,
539.Xr md 4 ,
540.Xr make.conf 5 ,
541.Xr build 7 ,
542.Xr ports 7 ,
543.Xr chroot 8 ,
544.Xr mtree 8 ,
545.Xr sysctl 8
546.Rs
547.%T "FreeBSD Release Engineering"
548.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
549.Re
550.Rs
551.%T "FreeBSD Release Engineering of Third Party Packages"
552.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
553.Re
554.Rs
555.%T "FreeBSD Developers' Handbook"
556.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
557.Re
558.Sh HISTORY
559.Fx
5601.x
561used a manual checklist, compiled by
562.An Rod Grimes ,
563to produce a release.
564Apart from being incomplete, the list put a lot of specific demands on
565available file systems and was quite torturous to execute.
566.Pp
567As part of the
568.Fx 2.0
569release engineering effort, significant
570effort was spent getting
571.Pa src/release/Makefile
572into a shape where it could at least automate most of the tediousness
573of building a release in a sterile environment.
574.Pp
575For the
576.Fx 9.0
577release,
578.Pa src/release/Makefile
579was overhauled and the wrapper script
580.Pa src/release/generate-release.sh
581introduced to support the introduction of a new installer.
582.Pp
583For the
584.Fx 9.2
585release,
586.Pa src/release/release.sh
587was introduced to support per-build configuration files.
588.Pa src/release/release.sh
589is heavily based on the
590.Pa src/release/generate-release.sh
591script.
592.Pp
593At near 1000 revisions spread over multiple branches, the
594.Xr svn 1
595log of
596.Pa src/release/Makefile
597contains a vivid historical record of some
598of the hardships release engineers go through.
599.Sh AUTHORS
600.Pa src/release/Makefile
601was originally written by
602.An -nosplit
603.An Rod Grimes ,
604.An Jordan Hubbard ,
605and
606.An Poul-Henning Kamp .
607.Pp
608This manual page was originally written by
609.An Murray Stokely Aq murray@FreeBSD.org .
610.Pp
611It was updated by
612.An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org
613to include the
614.Fa generate-release.sh
615script used for the
616.Fx 9.0
617release cycle.
618.Pp
619It was later updated by
620.An Glen Barber Aq gjb@FreeBSD.org
621to include the
622.Fa release.sh
623script used for the
624.Fx 9.2
625release cycle.
|