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