1 .\" Copyright (c) 2002 Murray Stokely <murray@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
30 .Nd "release building infrastructure"
33 provides a complete build environment suitable for users to make
37 All of the tools necessary to build a release are available from the
39 source code repository in
41 A complete release can be built with only a single command,
42 including the creation of ISO images suitable for burning to CD-ROM,
43 memory stick images, and a network install directory.
44 This command is aptly named
45 .Dq Li "make release" .
47 For some users, it may be desirable to provide an absolutely clean
48 build environment, with no local modifications to the source tree or to
50 and with clean checkouts of specific versions of the doc, src, and ports
52 For this purpose, a script
53 .Pq Pa src/release/release.sh
54 is provided to automate these checkouts and then execute
59 Before attempting to build a release, the user is expected to be
60 familiar with the contents of
62 and should have experience upgrading systems from source.
64 The release build process requires that
66 be populated with the output of
67 .Dq Li "make buildworld"
69 .Dq Li "make buildkernel" .
70 This is necessary to provide the object files for the release or, when
73 so that the object files for a complete system can be installed into a clean
77 If the target release build is for a different architecture or machine type,
82 variables must be used.
85 variables for more information.
87 The release procedure on some architectures may also require that the
89 (memory disk) device driver be present in the kernel
90 .Pq either by being compiled in or available as a module .
92 This document does not cover source code management, quality
93 assurance, or other aspects of the release engineering process.
94 .Sh CLEAN RELEASE GENERATION
97 are produced in a clean environment to
98 ensure consistency between the versions of the src, ports, and doc trees
99 and to avoid contamination from the host system
100 .Po such as local patches, changes
105 This is accomplished using the wrapper script
106 .Pa src/release/release.sh .
109 .Op Fl c Ar release.conf
120 .Dq Li "make buildworld"
122 .Dq Li "make installworld"
127 .Dq Li "make release"
130 environment and places the result in
135 configuration file supports the following variables:
138 The directory within which the release will be built.
139 .It Va CHROOT_MAKEENV
142 arguments to pass through, which directly affect the
143 tuning of the build chroot.
145 Do not explicitly require the
147 port to be installed.
151 host used to check out the various trees.
153 .Pa https://git.FreeeBSD.org .
167 The target machine type for cross-building a release.
169 The target machine architecture for cross-building a release.
171 For the supported list of
175 combinations, consult the output of
180 The target kernel configuration to use.
185 entries may be specified.
189 to use for the release build.
192 to prevent polluting the release with local system changes.
196 to use for the release build.
199 to prevent polluting the release with local system changes.
201 Additional flags to pass to
204 Additional flags to pass to
209 Defaults to setting the number of
213 to the number of CPUs available on a SMP-capable system.
215 Additional flags to pass to
220 Defaults to setting the number of
224 to half the number of CPUs available on a SMP-capable system.
226 Set to a non-empty value to skip the
233 distribution package from being created.
235 Set to a non-empty value to include the
238 .It Va WITH_COMPRESSED_IMAGES
239 Set to a non-empty value to compress the release images with
243 images are not removed.
244 .It Va XZ_THREADS Pq Vt int
245 Set to the number of threads
247 should use when compressing images.
252 which uses all available cores on the system.
254 The command run to obtain the source trees.
256 .Qq Cm git clone Fl q .
257 .It Va CHROOTBUILD_SKIP
265 build environment setup are skipped.
266 This is intended solely for cases where the
268 userland are provided by alternate means.
269 .It Va SRC_UPDATE_SKIP
270 Set to a non-empty value to prevent checkout or update of
274 This is intended for use only when
276 is expected to exist by alternative means.
277 .It Va PORTS_UPDATE_SKIP
278 Set to a non-empty value to prevent checkout or update of
282 This is intended for use only when
284 is expected to exist by alternative means.
289 variables are relevant only to release builds for embedded systems:
292 Set to a non-null value to enable functionality for embedded device
301 .Va EMBEDDED_TARGET_ARCH
302 must also be defined.
303 When the build environment is created,
305 runs a separate build script located in an architecture-specific
307 .Pa src/release/${EMBEDDED_TARGET}/ .
309 Set to the list of any ports that are required for the target device
312 .It Va EMBEDDED_TARGET
313 When set, its value is passed to
317 .Pq value of Cm uname Fl m
318 to cross build the target userland.
319 .It Va EMBEDDED_TARGET_ARCH
320 When set, its value is passed to
324 .Pq value of Cm uname Fl p
325 to cross build the target userland.
327 .Sh VIRTUAL MACHINE DISK IMAGES
330 variables are relevant only to virtual machine disk image builds:
333 Set to a non-null value to build virtual machine disk images as part
334 of the release build.
336 may also be specified as an environment variable passed to
338 .It Va WITH_COMPRESSED_VMIMAGES
339 Set to a non-null value to compress the virtual machine disk images with
345 Note that compressing virtual machine disk images may take a very long
346 time on some systems.
348 Set to change the name of the resulting virtual machine disk image file.
352 Set to change the size of the virtual machine disk capacity.
359 Virtual machine disk images are, by default, created as sparse images.
361 .Va WITH_COMPRESSED_VMIMAGES
362 is used, the resulting files compressed with
364 compress to roughly the same size, regardless of the specified disk image
368 Set to specify which of the filesystem(s) listed in
370 is linked to the historical non-filesystem-labelled file name.
378 Set to specify the list of file system types to build images for.
379 Valid values are one or both of
386 Set to the target virtual disk image format(s) to create.
388 .Va vhdf , Va vmdk , Va qcow2 ,
394 for valid format values.
397 For a list of supported
400 .Pq including cloud hosting provider formats
401 along with a brief description, run:
402 .Bd -literal -offset indent
404 make -C release list-vmtargets
406 .Sh CLOUD HOSTING MACHINE IMAGES
409 release build tools support building virtual machine images for various
410 cloud hosting providers, each with their own specific configuration to
411 include support for each hosting provider by default.
415 environment variables are supported:
418 Set to a list of one or more cloud hosting providers, enclosed in quotes.
422 .It Va WITH_CLOUDWARE
423 Set to a non-empty value to enable building virtual machine images
424 for various cloud hosting providers.
434 variables can be added to
436 and used in conjunction with
439 For a list of supported
442 .Bd -literal -offset indent
444 make -C release list-cloudware
448 .Pq Pa src/release/Makefile
450 Most developers will only be concerned with the
455 .\" XXX: Some sort of introduction to this list? All the others have one.
456 .Bl -tag -width ".Cm packagesystem"
458 Meta-target to build all release media and distributions applicable to this
461 Copy all produced release media to
464 Builds installation CD-ROM images.
467 (memory disk) device driver be present in the kernel
468 (either by being compiled in or available as a module).
469 This target produces files called
475 Builds installation DVD-ROM images.
478 (memory disk) device driver be present in the kernel
479 (either by being compiled in or available as a module).
480 This target produces the
484 Builds an installation memory stick image named
486 Not applicable on all platforms.
490 device driver be present in the kernel
491 .Pq either by being compiled in or available as a module .
495 with the exception that the installation distribution sets
498 Creates a directory named
500 containing the distribution files used in network installations
501 and suitable for upload to an FTP mirror.
503 Creates virtual machine disk images in various formats.
509 environment variable to be set to a non-null value.
513 virtual machine images for various cloud hosting providers.
515 .Qq CLOUD HOSTING MACHINE IMAGES
516 for implementation details.
517 .It Cm list-cloudware
518 Displays the list of valid
521 .It Cm list-vmtargets
522 Displays the list of valid
529 Major subtargets called by targets above:
530 .Bl -tag -width ".Cm packagesystem"
532 Generates all the distribution archives
533 .Pq base, kernel, ports, doc
534 applicable on this platform.
536 Builds a bootable installation system containing all the distribution files
539 target, and suitable for imaging by the
546 Builds the release documentation.
547 This includes the release notes,
548 hardware guide, and installation instructions.
549 Other documentation, such as the Handbook,
557 .Bl -tag -width ".Ev TARGET_ARCH"
559 Optional base name for generated media images when invoking the
562 .Pq e.g., FreeBSD-12.1-RELEASE-amd64 .
563 Defaults to the output of
564 .Ic `uname -s`-`uname -r`-`uname -p`
567 Location of a directory containing the src tree.
568 By default, the directory
569 above the one containing the makefile
572 Location of a directory containing the ports tree.
575 If it is unset or cannot be found, ports will not be included in the release.
577 If defined, the Ports Collection will be omitted from the release.
579 If set, do not include system source code in the release.
581 The target hardware platform.
582 This is analogous to the
585 This is necessary to cross-build some target architectures.
586 For example, cross-building for ARM64 machines requires
587 .Ev TARGET_ARCH Ns = Ns Li aarch64
589 .Ev TARGET Ns = Ns Li arm64 .
592 defaults to the current hardware platform.
594 The target machine processor architecture.
595 This is analogous to the
598 Set this to cross-build for a different architecture.
601 defaults to the current machine architecture, unless
603 is also set, in which case it defaults to the appropriate
604 value for that platform.
605 Typically, one only needs to set
609 .Bl -tag -compact -width Pa
610 .It Pa /usr/doc/Makefile
611 .It Pa /usr/doc/share/mk/doc.project.mk
612 .It Pa /usr/ports/Mk/bsd.port.mk
613 .It Pa /usr/ports/Mk/bsd.sites.mk
614 .It Pa /usr/share/examples/etc/make.conf
615 .It Pa /usr/src/Makefile
616 .It Pa /usr/src/Makefile.inc1
617 .It Pa /usr/src/release/Makefile
618 .It Pa /usr/src/release/Makefile.vm
619 .It Pa /usr/src/release/release.sh
620 .It Pa /usr/src/release/release.conf.sample
621 .It Pa /usr/src/release/tools/*.conf
622 .It Pa /usr/src/release/tools/vmimage.subr
625 The following sequence of commands can be used to build a
626 .Dq "-CURRENT snapshot":
627 .Bd -literal -offset indent
629 git clone -b main https://git.freebsd.org/src.git src
631 make buildworld buildkernel
635 make install DESTDIR=/var/freebsd-snapshot
638 After running these commands, all produced distribution files (tarballs
639 for FTP, CD-ROM images, etc.) are available in the
640 .Pa /var/freebsd-snapshot
643 The following sequence of commands can be used to build a
644 .Dq "-CURRENT snapshot"
645 in a clean environment, including ports and documentation:
646 .Bd -literal -offset indent
651 Optionally, a configuration file can be used to customize the release build:
652 .Bd -literal -offset indent
654 sh release.sh -c $HOME/release.conf
657 Configuration files specific to various supported embedded systems, such as
658 the Raspberry Pi, exist in the directory corresponding to the
662 For example, to build an image for the Raspberry Pi:
663 .Bd -literal -offset indent
665 sh release.sh -c arm/RPI-B.conf
668 To build an image for the Raspberry Pi 3:
669 .Bd -literal -offset indent
671 sh release.sh -c arm64/RPI3.conf
674 After running these commands, all prepared release files are available in the
677 The target directory can be changed by specifying the
682 The reldoc target was removed in commit f61e92ca5a23, and
685 .Ev DOC_UPDATE_SKIP ,
688 are therefore no longer supported.
691 .Xr git 1 Pq Pa ports/devel/git ,
704 .%T "FreeBSD Release Engineering"
705 .%U https://docs.freebsd.org/en/articles/freebsd-releng/
708 .%T "FreeBSD Developers' Handbook"
709 .%U https://docs.freebsd.org/en/books/developers-handbook/
714 used a manual checklist, compiled by
716 to produce a release.
717 Apart from being incomplete, the list put a lot of specific demands on
718 available file systems and was quite torturous to execute.
722 release engineering effort, significant
723 effort was spent getting
724 .Pa src/release/Makefile
725 into a shape where it could at least automate most of the tediousness
726 of building a release in a sterile environment.
731 .Pa src/release/Makefile
732 was overhauled and the wrapper script
733 .Pa src/release/generate-release.sh
734 introduced to support the introduction of a new installer.
739 .Pa src/release/release.sh
740 was introduced to support per-build configuration files.
741 .Pa src/release/release.sh
742 is heavily based on the
743 .Pa src/release/generate-release.sh
746 At near 1000 revisions spread over multiple branches, the
749 .Pa src/release/Makefile
750 contains a vivid historical record of some
751 of the hardships release engineers go through.
753 .Pa src/release/Makefile
754 was originally written by
759 .An Poul-Henning Kamp .
761 This manual page was originally written by
762 .An Murray Stokely Aq Mt murray@FreeBSD.org .
765 .An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org
767 .Fa generate-release.sh
772 It was later updated by
773 .An Glen Barber Aq Mt gjb@FreeBSD.org