]> CyberLeo.Net >> Repos - FreeBSD/stable/10.git/blob - share/man/man7/release.7
MFC r272414:
[FreeBSD/stable/10.git] / share / man / man7 / release.7
1 .\" Copyright (c) 2002 Murray Stokely <murray@FreeBSD.org>
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\"
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23 .\" SUCH DAMAGE.
24 .\"
25 .\" $FreeBSD$
26 .\"
27 .Dd October 2, 2014
28 .Dt RELEASE 7
29 .Os
30 .Sh NAME
31 .Nm release
32 .Nd "release building infrastructure"
33 .Sh DESCRIPTION
34 .Fx
35 provides a complete build environment suitable for users to make
36 full releases of the
37 .Fx
38 operating system.
39 All of the tools necessary to build a release are available from the
40 .Fx
41 source code repository in
42 .Pa src/release .
43 A complete release can actually be built with only a single command,
44 including the creation of ISO images suitable for burning to CD-ROM,
45 memory stick images, and an FTP install directory.
46 This command is aptly named
47 .Dq Li "make release" .
48 .Pp
49 For some users, it may be desirable to provide an absolutely clean
50 build environment, with no local modifications to the source tree or to
51 .Xr make.conf 5 ,
52 and with clean checkouts of specific versions of the doc, src, and ports
53 trees.
54 For this purpose, a script
55 .Pq Pa src/release/release.sh
56 is provided to automate these checkouts and then execute
57 .Dq Li "make release"
58 in a clean
59 .Xr chroot 8 .
60 .Pp
61 Before attempting to build a release, the user is expected to be
62 familiar with the contents of
63 .Xr build 7 ,
64 and should have experience upgrading systems from source.
65 .Pp
66 The release build process requires that
67 .Pa /usr/obj
68 be populated with the output of
69 .Dq Li "make buildworld"
70 and
71 .Dq Li "make buildkernel" .
72 This is necessary to provide the object files for the release or, when
73 using
74 .Pa release.sh ,
75 so that the object files for a complete system can be installed into a clean
76 .Xr chroot 8
77 environment.
78 .Pp
79 If the target release build is for a different architecture or machine type,
80 the
81 .Va TARGET
82 and
83 .Va TARGET_ARCH
84 variables must be used.
85 See the supported
86 .Fa release.conf
87 variables for more information.
88 .Pp
89 The 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
94 This document does not cover source code management, quality
95 assurance, or other aspects of the release engineering process.
96 .Sh CLEAN RELEASE GENERATION
97 Official releases of
98 .Fx
99 are produced in a totally clean environment to
100 ensure consistency between the versions of the src, ports, and doc trees
101 and to avoid contamination from the host system
102 .Po such as local patches, changes
103 to
104 .Xr make.conf 5 ,
105 etc.
106 .Pc .
107 This 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
114 checks out the
115 .Li src/ ,
116 .Li ports/ ,
117 and
118 .Li doc/
119 trees to
120 .Va CHROOTDIR ,
121 then calls
122 .Dq Li "make buildworld"
123 and
124 .Dq Li "make installworld"
125 to generate a
126 .Xr chroot 8
127 environment.
128 Next,
129 .Dq Li "make release"
130 is run within the
131 .Xr chroot 8
132 environment and places the result in
133 .Pa $CHROOTDIR/R .
134 .Pp
135 The optional
136 .Fa release.conf
137 configuration file supports the following variables:
138 .Bl -tag -width Ev
139 .It Va CHROOTDIR
140 The directory within which the release will be built.
141 .It Va CHROOT_MAKEENV
142 Additional
143 .Xr make 1
144 arguments to pass through, which directly affect the
145 tuning of the build chroot.
146 .It Va SVNROOT
147 The
148 .Xr svn 1
149 host used to check out the various trees.
150 Defaults to
151 .Pa svn://svn.FreeeBSD.org .
152 .It Va SRCBRANCH
153 The
154 .Li src/
155 branch to use.
156 Defaults to
157 .Va head/@rHEAD .
158 .It Va DOCBRANCH
159 The
160 .Li doc/
161 branch to use.
162 Defaults to
163 .Va head/@rHEAD .
164 .It Va PORTBRANCH
165 The
166 .Li ports/
167 branch to use.
168 Defaults to
169 .Va head/@rHEAD .
170 .It Va TARGET
171 The target machine type for cross-building a release.
172 .It Va TARGET_ARCH
173 The target machine architecture for cross-building a release.
174 .Pp
175 For the supported list of
176 .Va TARGET
177 and
178 .Va TARGET_ARCH
179 combinations, consult the output of
180 .Dq make targets
181 as documented in
182 .Xr build 7 .
183 .It Va KERNEL
184 The target kernel configuration to use.
185 Defaults to
186 .Va GENERIC .
187 Multiple
188 .Va KERNEL
189 entries may be specified.
190 .It Va MAKE_CONF
191 The
192 .Xr make.conf 5
193 to use for the release build.
194 Defaults to
195 .Fa /dev/null
196 to prevent polluting the release with local system changes.
197 .It Va SRC_CONF
198 The
199 .Xr src.conf 5
200 to use for the release build.
201 Defaults to
202 .Fa /dev/null
203 to prevent polluting the release with local system changes.
204 .It Va MAKE_FLAGS
205 Additional flags to pass to
206 .Xr make 1 .
207 .It Va WORLD_FLAGS
208 Additional flags to pass to
209 .Xr make 1
210 during the
211 .Dq buildworld
212 phase.
213 Defaults to setting the number of
214 .Xr make 1
215 jobs
216 .Pq Ar -j
217 to the number of CPUs available on a SMP-capable system.
218 .It Va KERNEL_FLAGS
219 Additional flags to pass to
220 .Xr make 1
221 during the
222 .Dq buildkernel
223 phase.
224 Defaults to setting the number of
225 .Xr make 1
226 jobs
227 .Pq Ar -j
228 to half the number of CPUs available on a SMP-capable system.
229 .It Va NODOC
230 Set to a non-empty value to skip the
231 .Li doc/
232 tree checkout.
233 When set,
234 .Va NODOC
235 will prevent the
236 .Fa doc.txz
237 distribution package from being created.
238 .It Va NOPORTS
239 Set to a non-empty value to skip the
240 .Li ports/
241 tree checkout.
242 When set,
243 .Va NOPORTS
244 will prevent the
245 .Fa ports.txz
246 distribution package from being created.
247 Setting this also sets
248 .Va NODOC .
249 .It Va WITH_DVD
250 Set to a non-empty value to include the
251 .Cm dvdrom
252 target.
253 .It Va WITH_COMPRESSED_IMAGES
254 Set to a non-empty value to compress the release images with
255 .Xr xz 1 .
256 The original
257 .Pq uncompressed
258 images are not removed.
259 .It Va VCSCMD
260 The command run to obtain the source trees.
261 Defaults to
262 .Qq Cm svn checkout .
263 .It Va CHROOTBUILD_SKIP
264 If defined, the
265 .Li buildworld ,
266 .Li installworld ,
267 and
268 .Li distribution
269 stages of the
270 .Xr chroot 8
271 build environment setup are skipped.
272 This is intended solely for cases where the
273 .Xr chroot 8
274 userland are provided by alternate means.
275 .It Va SRC_UPDATE_SKIP
276 Set to a non-empty value to prevent checkout or update of
277 .Fa /usr/src
278 within the
279 .Xr chroot 8 .
280 This is intended for use only when
281 .Fa /usr/src
282 is expected to exist by alternative means.
283 .It Va DOC_UPDATE_SKIP
284 Set to a non-empty value to prevent checkout or update of
285 .Fa /usr/doc
286 within the
287 .Xr chroot 8 .
288 This is intended for use only when
289 .Fa /usr/doc
290 is expected to exist by alternative means.
291 .It Va PORTS_UPDATE_SKIP
292 Set to a non-empty value to prevent checkout or update of
293 .Fa /usr/ports
294 within the
295 .Xr chroot 8 .
296 This is intended for use only when
297 .Fa /usr/ports
298 is expected to exist by alternative means.
299 .El
300 .Sh EMBEDDED BUILDS
301 The following
302 .Fa release.conf
303 variables are relevant only to release builds for embedded systems:
304 .Bl -tag -width Ev
305 .It Va EMBEDDEDBUILD
306 Set to a non-null value to enable functionality for embedded device
307 release builds.
308 .Pq This option is considered highly experimental.
309 .Pp
310 When set,
311 .Va WITH_DVD
312 is unset, and
313 .Va NODOC
314 is defined.
315 Additionally,
316 .Va XDEV
317 and
318 .Va XDEV_ARCH
319 must also be defined.
320 When the build environment is created,
321 .Fa release.sh
322 runs a separate build script located in an architecture-specific
323 directory in
324 .Pa src/release/${XDEV}/ .
325 .It Va EMBEDDEDPORTS
326 Set to the list of any ports that are required for the target device
327 in the format of
328 .Fa category/port .
329 The
330 .Fa devel/subversion
331 port is built by default.
332 .It Va CROCHETSRC
333 Set to the source URL for the Crochet build tool.
334 .It Va CROCHETBRANCH
335 Set to the subversion branch from
336 .Va ${CROCHETSRC}
337 to use.
338 Defaults to
339 .Pa trunk .
340 .It Va UBOOTSRC
341 Set to the source URL of u-boot, if required.
342 .It Va UBOOTBRANCH
343 Set to the subversion branch from
344 .Va ${UBOOTSRC}
345 to use.
346 Defaults to
347 .Pa trunk .
348 .It Va UBOOTDIR
349 Set to the target directory within
350 .Va ${CHROOTDIR}
351 to check out
352 .Va ${UBOOTSRC}/${UBOOTBRANCH} .
353 .El
354 .Sh VIRTUAL MACHINE DISK IMAGES
355 The following
356 .Fa release.conf
357 variables are relevant only to virtual machine disk image builds:
358 .Bl -tag -width Ev
359 .It Va WITH_VMIMAGES
360 Set to a non-null value to build virtual machine disk images as part
361 of the release build.
362 .Va WITH_VMIMAGES
363 may also be specified as an envirionment variable passed to
364 .Xr make 1 .
365 .Pp
366 The option requires
367 .Xr mkimg 1
368 version 20140927 or later.
369 .It Va WITH_COMPRESSED_VMIMAGES
370 Set to a non-null value to compress the virtual machine disk images with
371 .Xr xz 1
372 as part of the
373 .Cm install
374 .Xr make 1
375 target.
376 Note that compressing virtual machine disk images may take a very long
377 time on some systems.
378 .It Va VMBASE
379 Set to change the name of the resulting virtual machine disk image file.
380 The default value is
381 .Va vm .
382 .It Va VMSIZE
383 Set to change the size of the virtual machine disk capacity.
384 The default value is
385 .Va 20G .
386 See
387 .Xr truncate 1
388 for valid values.
389 .Pp
390 Virtual machine disk images are, by default, created as sparse images.
391 When
392 .Va WITH_COMPRESSED_VMIMAGES
393 is used, the resulting files compressed with
394 .Xr xz 1
395 compress to roughly the same size, regardless of the specified disk image
396 size.
397 .It Va VMFORMATS
398 Set to the target virtual disk image format(s) to create.
399 By default, the
400 .Va vhdf , Va vmdk , Va qcow2 ,
401 and
402 .Va raw
403 formats are created.
404 See
405 .Xr mkimg 1
406 for valid format values
407 .Pq requires version 20140927 or later .
408 .El
409 .Sh MAKEFILE TARGETS
410 The release makefile
411 .Pq Pa src/release/Makefile
412 is fairly abstruse.
413 Most developers will only be concerned with the
414 .Cm release
415 and
416 .Cm install
417 targets.
418 .\" XXX: Some sort of introduction to this list?  All the others have one.
419 .Bl -tag -width ".Cm packagesystem"
420 .It Cm release
421 Meta-target to build all release media and distributions applicable to this
422 platform.
423 .It Cm install
424 Copy all produced release media to
425 .Pa ${DESTDIR} .
426 .It Cm cdrom
427 Builds installation CD-ROM images.
428 This may require the
429 .Xr md 4
430 (memory disk) device driver be present in the kernel
431 (either by being compiled in or available as a module).
432 This target produces files called
433 .Pa disc1.iso
434 and
435 .Pa bootonly.iso
436 as its output.
437 .It Cm dvdrom
438 Builds installation DVD-ROM images.
439 This may require the
440 .Xr md 4
441 (memory disk) device driver be present in the kernel
442 (either by being compiled in or available as a module).
443 This target produces the
444 .Pa dvd1.iso
445 file as its output.
446 .It Cm memstick
447 Builds an installation memory stick image named
448 .Pa memstick.img .
449 Not applicable on all platforms.
450 Requires that the
451 .Xr md 4
452 .Pq memory disk
453 device driver be present in the kernel
454 .Pq either by being compiled in or available as a module .
455 .It Cm mini-memstick
456 Similar to
457 .Cm memstick ,
458 with the exception that the installation distribution sets
459 are not included.
460 .It Cm ftp
461 Creates a directory named
462 .Pa ftp
463 containing the distribution files used in network installations
464 and suitable for upload to an FTP mirror.
465 .It Cm vm-image
466 Creates virtual machine disk images in various formats.
467 The
468 .Cm vm-image
469 target requires the
470 .Va WITH_VMIMAGES
471 .Xr make 1
472 envirionment variable to be set to a non-null value.
473 .El
474 .Pp
475 Major subtargets called by targets above:
476 .Bl -tag -width ".Cm packagesystem"
477 .It Cm packagesystem
478 Generates all the distribution archives
479 .Pq base, kernel, ports, doc
480 applicable on this platform.
481 .It Cm system
482 Builds a bootable installation system containing all the distribution files
483 packaged by the
484 .Cm packagesystem
485 target, and suitable for imaging by the
486 .Cm cdrom ,
487 .Cm dvdrom
488 and
489 .Cm memstick
490 targets.
491 .It Cm reldoc
492 Builds the release documentation.
493 This includes the release notes,
494 hardware guide, and installation instructions.
495 Other documentation, such as the Handbook,
496 is built during the
497 .Cm base.txz
498 target invoked by
499 .Cm packagesystem .
500 .El
501 .Sh ENVIRONMENT
502 Optional variables:
503 .Bl -tag -width ".Ev TARGET_ARCH"
504 .It Ev OSRELEASE
505 Optional base name for generated media images
506 .Pq e.g., FreeBSD-9.0-RC2-amd64 .
507 Defaults to the output of
508 .Ic `uname -s`-`uname -r`-`uname -p`
509 within the chroot.
510 .It Ev WORLDDIR
511 Location of a directory containing the src tree.
512 By default, the directory
513 above the one containing the makefile
514 .Pq Pa src .
515 .It Ev PORTSDIR
516 Location of a directory containing the ports tree.
517 By default,
518 .Pa /usr/ports .
519 If it is unset or cannot be found, ports will not be included in the release.
520 .It Ev DOCDIR
521 Location of a directory containing the doc tree.
522 By default,
523 .Pa /usr/doc .
524 If it is unset or cannot be found, most documentation will not be included in
525 the release; see
526 .Ev NODOC
527 below.
528 .It Ev NOPORTS
529 If defined, the Ports Collection will be omitted from the release.
530 .It Ev NOSRC
531 If set, do not include system source code in the release.
532 .It Ev NODOC
533 If defined, the XML-based documentation from the
534 .Fx
535 Documentation Project will not be built.
536 However, the
537 .Dq doc
538 distribution will still be created with the minimal documentation set
539 provided in
540 .Pa src/share/doc .
541 .It Ev TARGET
542 The target hardware platform.
543 This is analogous to the
544 .Dq Nm uname Fl m
545 output.
546 This is necessary to cross-build some target architectures.
547 For example, cross-building for PC98 machines requires
548 .Ev TARGET_ARCH Ns = Ns Li i386
549 and
550 .Ev TARGET Ns = Ns Li pc98 .
551 If not set,
552 .Ev TARGET
553 defaults to the current hardware platform.
554 .It Ev TARGET_ARCH
555 The target machine processor architecture.
556 This is analogous to the
557 .Dq Nm uname Fl p
558 output.
559 Set this to cross-build for a different architecture.
560 If not set,
561 .Ev TARGET_ARCH
562 defaults to the current machine architecture, unless
563 .Ev TARGET
564 is also set, in which case it defaults to the appropriate
565 value for that platform.
566 Typically, one only needs to set
567 .Ev TARGET .
568 .El
569 .Sh FILES
570 .Bl -tag -compact -width Pa
571 .It Pa /usr/doc/Makefile
572 .It Pa /usr/doc/share/mk/doc.project.mk
573 .It Pa /usr/ports/Mk/bsd.port.mk
574 .It Pa /usr/ports/Mk/bsd.sites.mk
575 .It Pa /usr/share/examples/etc/make.conf
576 .It Pa /usr/src/Makefile
577 .It Pa /usr/src/Makefile.inc1
578 .It Pa /usr/src/release/Makefile
579 .It Pa /usr/src/release/release.sh
580 .It Pa /usr/src/release/release.conf.sample
581 .El
582 .Sh EXAMPLES
583 The following sequence of commands can be used to build a
584 .Dq "-CURRENT snapshot":
585 .Bd -literal -offset indent
586 cd /usr
587 svn co svn://svn.freebsd.org/base/head src
588 cd src
589 make buildworld buildkernel
590 cd release
591 make release
592 make install DESTDIR=/var/freebsd-snapshot
593 .Ed
594 .Pp
595 After running these commands, all produced distribution files (tarballs
596 for FTP, CD-ROM images, etc.) are available in the
597 .Pa /var/freebsd-snapshot
598 directory.
599 .Pp
600 The following sequence of commands can be used to build a
601 .Dq "-CURRENT snapshot"
602 in a clean environment, including ports and documentation:
603 .Bd -literal -offset indent
604 cd /usr/src/release
605 sh release.sh
606 .Ed
607 .Pp
608 Optionally, a configuration file can be used customize the release build,
609 such as the subversion revision to use, the branch of the subversion tree for
610 .Li src/ ,
611 .Li ports/ ,
612 and
613 .Li doc/ .
614 .Bd -literal -offset indent
615 cd /usr/src/release
616 sh release.sh -c $HOME/release.conf
617 .Ed
618 .Pp
619 After running these commands, all prepared release files are available in the
620 .Pa /scratch
621 directory.
622 The target directory can be changed by specifying the
623 .Va CHROOTDIR
624 variable in
625 .Li release.conf .
626 .Sh SEE ALSO
627 .Xr cc 1 ,
628 .Xr install 1 ,
629 .Xr make 1 ,
630 .Xr svn 1 Pq Pa ports/devel/subversion ,
631 .Xr uname 1 ,
632 .Xr md 4 ,
633 .Xr make.conf 5 ,
634 .Xr build 7 ,
635 .Xr ports 7 ,
636 .Xr chroot 8 ,
637 .Xr mtree 8 ,
638 .Xr sysctl 8
639 .Rs
640 .%T "FreeBSD Release Engineering"
641 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
642 .Re
643 .Rs
644 .%T "FreeBSD Release Engineering of Third Party Packages"
645 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
646 .Re
647 .Rs
648 .%T "FreeBSD Developers' Handbook"
649 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
650 .Re
651 .Sh HISTORY
652 .Fx
653 1.x
654 used a manual checklist, compiled by
655 .An Rod Grimes ,
656 to produce a release.
657 Apart from being incomplete, the list put a lot of specific demands on
658 available file systems and was quite torturous to execute.
659 .Pp
660 As part of the
661 .Fx 2.0
662 release engineering effort, significant
663 effort was spent getting
664 .Pa src/release/Makefile
665 into a shape where it could at least automate most of the tediousness
666 of building a release in a sterile environment.
667 .Pp
668 For the
669 .Fx 9.0
670 release,
671 .Pa src/release/Makefile
672 was overhauled and the wrapper script
673 .Pa src/release/generate-release.sh
674 introduced to support the introduction of a new installer.
675 .Pp
676 For the
677 .Fx 9.2
678 release,
679 .Pa src/release/release.sh
680 was introduced to support per-build configuration files.
681 .Pa src/release/release.sh
682 is heavily based on the
683 .Pa src/release/generate-release.sh
684 script.
685 .Pp
686 At near 1000 revisions spread over multiple branches, the
687 .Xr svn 1
688 log of
689 .Pa src/release/Makefile
690 contains a vivid historical record of some
691 of the hardships release engineers go through.
692 .Sh AUTHORS
693 .Pa src/release/Makefile
694 was originally written by
695 .An -nosplit
696 .An Rod Grimes ,
697 .An Jordan Hubbard ,
698 and
699 .An Poul-Henning Kamp .
700 .Pp
701 This manual page was originally written by
702 .An Murray Stokely Aq murray@FreeBSD.org .
703 .Pp
704 It was updated by
705 .An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org
706 to include the
707 .Fa generate-release.sh
708 script used for the
709 .Fx 9.0
710 release cycle.
711 .Pp
712 It was later updated by
713 .An Glen Barber Aq gjb@FreeBSD.org
714 to include the
715 .Fa release.sh
716 script used for the
717 .Fx 9.2
718 release cycle.