xref: /freebsd/share/man/man7/release.7 (revision 046c625e9382e17da953767b881aaa782fa73af8)
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.Dd September 11, 2025
26.Dt RELEASE 7
27.Os
28.Sh NAME
29.Nm release
30.Nd "release building infrastructure"
31.Sh DESCRIPTION
32.Fx
33provides a complete build environment suitable for users to make
34full releases of the
35.Fx
36operating system.
37All of the tools necessary to build a release are available from the
38.Fx
39source code repository in
40.Pa src/release .
41A complete release can be built with only a single command,
42including the creation of ISO images suitable for burning to CD-ROM,
43memory stick images, and a network install directory.
44This command is aptly named
45.Dq Li "make release" .
46.Pp
47For some users, it may be desirable to provide an absolutely clean
48build environment, with no local modifications to the source tree or to
49.Xr make.conf 5 ,
50and with clean checkouts of specific versions of the doc, src, and ports
51trees.
52For this purpose, a script
53.Pq Pa src/release/release.sh
54is provided to automate these checkouts and then execute
55.Dq Li "make release"
56in a clean
57.Xr chroot 8 .
58.Pp
59Before attempting to build a release, the user is expected to be
60familiar with the contents of
61.Xr build 7 ,
62and should have experience upgrading systems from source.
63.Pp
64The release build process requires that
65.Pa /usr/obj
66be populated with the output of
67.Dq Li "make buildworld"
68and
69.Dq Li "make buildkernel" .
70This is necessary to provide the object files for the release or, when
71using
72.Pa release.sh ,
73so that the object files for a complete system can be installed into a clean
74.Xr chroot 8
75environment.
76.Pp
77If the target release build is for a different architecture or machine type,
78the
79.Va TARGET
80and
81.Va TARGET_ARCH
82variables must be used.
83See the supported
84.Fa release.conf
85variables for more information.
86.Pp
87The release procedure on some architectures may also require that the
88.Xr md 4
89(memory disk) device driver be present in the kernel
90.Pq either by being compiled in or available as a module .
91.Pp
92This document does not cover source code management, quality
93assurance, or other aspects of the release engineering process.
94.Sh CLEAN RELEASE GENERATION
95Official releases of
96.Fx
97are produced in a clean environment to
98ensure consistency between the versions of the src, ports, and doc trees
99and to avoid contamination from the host system
100.Po such as local patches, changes
101to
102.Xr make.conf 5 ,
103etc.
104.Pc .
105This is accomplished using the wrapper script
106.Pa src/release/release.sh .
107.Pp
108.Ic release.sh
109.Op Fl c Ar release.conf
110.Pp
111.Ic release.sh
112checks out the
113.Li src/ ,
114.Li ports/ ,
115and
116.Li doc/
117trees to
118.Va CHROOTDIR ,
119then calls
120.Dq Li "make buildworld"
121and
122.Dq Li "make installworld"
123to generate a
124.Xr chroot 8
125environment.
126Next,
127.Dq Li "make release"
128is run within the
129.Xr chroot 8
130environment and places the result in
131.Pa $CHROOTDIR/R .
132.Pp
133The optional
134.Fa release.conf
135configuration file supports the following variables:
136.Bl -tag -width Ev
137.It Va CHROOTDIR
138The directory within which the release will be built.
139.It Va CHROOT_MAKEENV
140Additional
141.Xr make 1
142arguments to pass through, which directly affect the
143tuning of the build chroot.
144.It Va NOGIT
145Do not explicitly require the
146.Xr git 1
147port to be installed.
148.It Va GITROOT
149The
150.Xr git 1
151host used to check out the various trees.
152Defaults to
153.Pa https://git.FreeBSD.org .
154.It Va SRCBRANCH
155The
156.Li src/
157branch to use.
158Defaults to
159.Fl b Va main .
160.It Va PORTBRANCH
161The
162.Li ports/
163branch to use.
164Defaults to
165.Va head/@rHEAD .
166.It Va TARGET
167The target machine type for cross-building a release.
168.It Va TARGET_ARCH
169The target machine architecture for cross-building a release.
170.Pp
171For the supported list of
172.Va TARGET
173and
174.Va TARGET_ARCH
175combinations, consult the output of
176.Dq make targets
177as documented in
178.Xr build 7 .
179.It Va KERNEL
180The target kernel configuration to use.
181Defaults to
182.Va GENERIC .
183Multiple
184.Va KERNEL
185entries may be specified.
186.It Va MAKE_CONF
187The
188.Xr make.conf 5
189to use for the release build.
190Defaults to
191.Fa /dev/null
192to prevent polluting the release with local system changes.
193.It Va SRC_CONF
194The
195.Xr src.conf 5
196to use for the release build.
197Defaults to
198.Fa /dev/null
199to prevent polluting the release with local system changes.
200.It Va MAKE_FLAGS
201Additional flags to pass to
202.Xr make 1 .
203.It Va WORLD_FLAGS
204Additional flags to pass to
205.Xr make 1
206during the
207.Dq buildworld
208phase.
209Defaults to setting the number of
210.Xr make 1
211jobs
212.Pq Ar -j
213to the number of CPUs available on a SMP-capable system.
214.It Va KERNEL_FLAGS
215Additional flags to pass to
216.Xr make 1
217during the
218.Dq buildkernel
219phase.
220Defaults to setting the number of
221.Xr make 1
222jobs
223.Pq Ar -j
224to half the number of CPUs available on a SMP-capable system.
225.It Va NOPORTS
226Set to a non-empty value to skip the
227.Li ports/
228tree checkout.
229When set,
230.Va NOPORTS
231will prevent the
232.Fa ports.txz
233distribution package from being created.
234.It Va WITH_DVD
235Set to a non-empty value to include the
236.Cm dvdrom
237target.
238.It Va WITH_COMPRESSED_IMAGES
239Set to a non-empty value to compress the release images with
240.Xr xz 1 .
241The original
242.Pq uncompressed
243images are not removed.
244.It Va XZ_THREADS Pq Vt int
245Set to the number of threads
246.Xr xz 1
247should use when compressing images.
248By default,
249.Va XZ_THREADS
250is set to
251.Va 0 ,
252which uses all available cores on the system.
253.It Va VCSCMD
254The command run to obtain the source trees.
255Defaults to
256.Qq Cm git clone Fl q .
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.
269.It Va SRC_UPDATE_SKIP
270Set to a non-empty value to prevent checkout or update of
271.Fa /usr/src
272within the
273.Xr chroot 8 .
274This is intended for use only when
275.Fa /usr/src
276is expected to exist by alternative means.
277.It Va PORTS_UPDATE_SKIP
278Set to a non-empty value to prevent checkout or update of
279.Fa /usr/ports
280within the
281.Xr chroot 8 .
282This is intended for use only when
283.Fa /usr/ports
284is expected to exist by alternative means.
285.It Va PKGBASE
286Include base system packages for use with
287.Xr pkg 8
288on the install media, instead of legacy tarball distribution sets.
289.It Va PKG_CMD
290A path to the
291.Xr pkg 8
292executable to use when installing packages in release images as a non-root user.
293.It Va PKG_REPOS_DIR
294An optional path to a directory containing
295.Xr pkg 8
296repository configuration files.
297These configuration files will be used when installing packages in release
298images as a non-root user.
299.It Va PKG_REPO_NAME
300The name of the repository configuration to use when installing packages in
301release images as a non-root user.
302.El
303.Sh EMBEDDED BUILDS
304The following
305.Fa release.conf
306variables are relevant only to release builds for embedded systems:
307.Bl -tag -width Ev
308.It Va EMBEDDEDBUILD
309Set to a non-null value to enable functionality for embedded device
310release builds.
311.Pp
312When set,
313.Va WITH_DVD
314is unset.
315Additionally,
316.Va EMBEDDED_TARGET
317and
318.Va EMBEDDED_TARGET_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/${EMBEDDED_TARGET}/ .
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 .
329.It Va EMBEDDED_TARGET
330When set, its value is passed to
331.Xr make 1
332to set the
333.Va TARGET
334.Pq value of Cm uname Fl m
335to cross build the target userland.
336.It Va EMBEDDED_TARGET_ARCH
337When set, its value is passed to
338.Xr make 1
339to set the
340.Va TARGET_ARCH
341.Pq value of Cm uname Fl p
342to cross build the target userland.
343.El
344.Sh VIRTUAL MACHINE DISK IMAGES
345The following
346.Fa release.conf
347variables are relevant only to virtual machine disk image builds:
348.Bl -tag -width Ev
349.It Va WITH_VMIMAGES
350Set to a non-null value to build virtual machine disk images as part
351of the release build.
352.Va WITH_VMIMAGES
353may also be specified as an environment variable passed to
354.Xr make 1 .
355.It Va WITH_COMPRESSED_VMIMAGES
356Set to a non-null value to compress the virtual machine disk images with
357.Xr xz 1
358as part of the
359.Cm install
360.Xr make 1
361target.
362Note that compressing virtual machine disk images may take a very long
363time on some systems.
364.It Va VMBASE
365Set to change the name of the resulting virtual machine disk image file.
366The default value is
367.Va vm .
368.It Va VMSIZE
369Set to change the size of the virtual machine disk capacity.
370The default value is
371.Va 20g .
372See
373.Xr makefs 8
374for valid values.
375.Pp
376Virtual machine disk images are, by default, created as sparse images.
377When
378.Va WITH_COMPRESSED_VMIMAGES
379is used, the resulting files compressed with
380.Xr xz 1
381compress to roughly the same size, regardless of the specified disk image
382size.
383.It Va VMFS
384(Deprecated.)
385Set to specify which of the filesystem(s) listed in
386.Va VMFSLIST
387is linked to the historical non-filesystem-labelled file name.
388Valid values are
389.Va ufs
390and
391.Va zfs .
392The default value is
393.Va ufs .
394.It Va VMFSLIST
395Set to specify the list of file system types to build images for.
396Valid values are one or both of
397.Va ufs
398and
399.Va zfs .
400The default value is
401.Va ufs zfs .
402.It Va VMFORMATS
403Set to the target virtual disk image format(s) to create.
404By default, the
405.Va vhdf , Va vmdk , Va qcow2 ,
406and
407.Va raw
408formats are created.
409See
410.Xr mkimg 1
411for valid format values.
412.El
413.Pp
414For a list of supported
415.Va VMFORMATS
416values
417.Pq including cloud hosting provider formats
418along with a brief description, run:
419.Bd -literal -offset indent
420cd /usr/src
421make -C release list-vmtargets
422.Ed
423.Sh CLOUD HOSTING MACHINE IMAGES
424The
425.Fx
426release build tools support building virtual machine images for various
427cloud hosting providers, each with their own specific configuration to
428include support for each hosting provider by default.
429.Pp
430The following
431.Xr make 1
432environment variables are supported:
433.Bl -tag -width Ev
434.It Va CLOUDWARE
435Set to a list of one or more cloud hosting providers, enclosed in quotes.
436Requires
437.Va WITH_CLOUDWARE
438to also be set.
439.It Va WITH_CLOUDWARE
440Set to a non-empty value to enable building virtual machine images
441for various cloud hosting providers.
442Requires
443.Va CLOUDWARE
444to also be set.
445.El
446.Pp
447Additionally, the
448.Va CLOUDWARE
449and
450.Va WITH_CLOUDWARE
451variables can be added to
452.Pa release.conf ,
453and used in conjunction with
454.Pa release.sh .
455.Pp
456For a list of supported
457.Va CLOUDWARE
458values, run:
459.Bd -literal -offset indent
460cd /usr/src
461make -C release list-cloudware
462.Ed
463.Sh OCI IMAGES
464The
465.Fx
466release build tools have experimental support for building
467Open Container Initiative (OCI) format container base images.
468This is enabled using a
469.Fa release.conf
470variable:
471.Bl -tag -width Ev
472.It Va WITH_OCIIMAGES
473Set to a non-null value to build OCI base images.
474.El
475.Sh MAKEFILE TARGETS
476The release makefile
477.Pq Pa src/release/Makefile
478is fairly abstruse.
479Most developers will only be concerned with the
480.Cm release
481and
482.Cm install
483targets.
484.\" XXX: Some sort of introduction to this list?  All the others have one.
485.Bl -tag -width ".Cm packagesystem"
486.It Cm release
487Meta-target to build all release media and distributions applicable to this
488platform.
489.It Cm install
490Copy all produced release media to
491.Pa ${DESTDIR} .
492.It Cm cdrom
493Builds installation CD-ROM images.
494This may require the
495.Xr md 4
496(memory disk) device driver be present in the kernel
497(either by being compiled in or available as a module).
498This target produces files called
499.Pa disc1.iso
500and
501.Pa bootonly.iso
502as its output.
503.It Cm dvdrom
504Builds installation DVD-ROM images.
505This may require the
506.Xr md 4
507(memory disk) device driver be present in the kernel
508(either by being compiled in or available as a module).
509This target produces the
510.Pa dvd1.iso
511file as its output.
512.It Cm memstick
513Builds an installation memory stick image named
514.Pa memstick.img .
515Not applicable on all platforms.
516Requires that the
517.Xr md 4
518.Pq memory disk
519device driver be present in the kernel
520.Pq either by being compiled in or available as a module .
521.It Cm mini-memstick
522Similar to
523.Cm memstick ,
524with the exception that the installation distribution sets
525are not included.
526.It Cm ftp
527Creates a directory named
528.Pa ftp
529containing the distribution files used in network installations
530and suitable for upload to an FTP mirror.
531.It Cm vm-image
532Creates virtual machine disk images in various formats.
533The
534.Cm vm-image
535target requires the
536.Va WITH_VMIMAGES
537.Xr make 1
538environment variable to be set to a non-null value.
539.It Cm vm-cloudware
540Builds
541.Fx
542virtual machine images for various cloud hosting providers.
543See
544.Qq CLOUD HOSTING MACHINE IMAGES
545for implementation details.
546.It Cm list-cloudware
547Displays the list of valid
548.Va CLOUDWARE
549values.
550.It Cm list-vmtargets
551Displays the list of valid
552.Va VMFORMATS
553and
554.Va CLOUDWARE
555values.
556.El
557.Pp
558Major subtargets called by targets above:
559.Bl -tag -width ".Cm packagesystem"
560.It Cm packagesystem
561Generates all the distribution archives
562.Pq base, kernel, ports, doc
563applicable on this platform.
564.It Cm disc1
565Builds a bootable installation system containing all the distribution files
566packaged by the
567.Cm packagesystem
568target, and suitable for imaging by the
569.Cm cdrom ,
570.Cm dvdrom
571and
572.Cm memstick
573targets.
574.It Cm reldoc
575Builds the release documentation.
576This includes the release notes,
577hardware guide, and installation instructions.
578Other documentation, such as the Handbook,
579is built during the
580.Cm base.txz
581target invoked by
582.Cm packagesystem .
583.El
584.Sh ENVIRONMENT
585Optional variables:
586.Bl -tag -width ".Ev TARGET_ARCH"
587.It Ev OSRELEASE
588Optional base name for generated media images when invoking the
589.Cm install
590target
591.Pq e.g., FreeBSD-12.1-RELEASE-amd64 .
592Defaults to the output of
593.Ic `uname -s`-`uname -r`-`uname -p`
594within the chroot.
595.It Ev WORLDDIR
596Location of a directory containing the src tree.
597By default, the directory
598above the one containing the makefile
599.Pq Pa src .
600.It Ev PORTSDIR
601Location of a directory containing the ports tree.
602By default,
603.Pa /usr/ports .
604If it is unset or cannot be found, ports will not be included in the release.
605.It Ev NOPORTS
606If defined, the Ports Collection will be omitted from the release.
607.It Ev NOSRC
608If set, do not include system source code in the release.
609.It Ev TARGET
610The target hardware platform.
611This is analogous to the
612.Dq Nm uname Fl m
613output.
614This is necessary to cross-build some target architectures.
615For example, cross-building for ARM64 machines requires
616.Ev TARGET_ARCH Ns = Ns Li aarch64
617and
618.Ev TARGET Ns = Ns Li arm64 .
619If not set,
620.Ev TARGET
621defaults to the current hardware platform.
622.It Ev TARGET_ARCH
623The target machine processor architecture.
624This is analogous to the
625.Dq Nm uname Fl p
626output.
627Set this to cross-build for a different architecture.
628If not set,
629.Ev TARGET_ARCH
630defaults to the current machine architecture, unless
631.Ev TARGET
632is also set, in which case it defaults to the appropriate
633value for that platform.
634Typically, one only needs to set
635.Ev TARGET .
636.El
637.Sh FILES
638.Bl -tag -compact -width Pa
639.It Pa /usr/doc/Makefile
640.It Pa /usr/doc/share/mk/doc.project.mk
641.It Pa /usr/ports/Mk/bsd.port.mk
642.It Pa /usr/ports/Mk/bsd.sites.mk
643.It Pa /usr/share/examples/etc/make.conf
644.It Pa /usr/src/Makefile
645.It Pa /usr/src/Makefile.inc1
646.It Pa /usr/src/release/Makefile
647.It Pa /usr/src/release/Makefile.vm
648.It Pa /usr/src/release/release.sh
649.It Pa /usr/src/release/release.conf.sample
650.It Pa /usr/src/release/tools/*.conf
651.It Pa /usr/src/release/tools/vmimage.subr
652.El
653.Sh EXAMPLES
654The following sequence of commands can be used to build a
655.Dq "-CURRENT snapshot":
656.Bd -literal -offset indent
657cd /usr
658git clone -b main https://git.freebsd.org/src.git src
659cd src
660make buildworld buildkernel
661cd release
662make obj
663make release
664make install DESTDIR=/var/freebsd-snapshot
665.Ed
666.Pp
667After running these commands, all produced distribution files (tarballs
668for FTP, CD-ROM images, etc.) are available in the
669.Pa /var/freebsd-snapshot
670directory.
671.Pp
672The following sequence of commands can be used to build a
673.Dq "-CURRENT snapshot"
674in a clean environment, including ports and documentation:
675.Bd -literal -offset indent
676cd /usr/src/release
677sh release.sh
678.Ed
679.Pp
680Optionally, a configuration file can be used to customize the release build:
681.Bd -literal -offset indent
682cd /usr/src/release
683sh release.sh -c $HOME/release.conf
684.Ed
685.Pp
686Configuration files specific to various supported embedded systems, such as
687the Raspberry Pi, exist in the directory corresponding to the
688.Va TARGET
689.Xr make 1
690variable.
691For example, to build an image for the Raspberry Pi:
692.Bd -literal -offset indent
693cd /usr/src/release
694sh release.sh -c arm/RPI-B.conf
695.Ed
696.Pp
697To build an image for the Raspberry Pi 3:
698.Bd -literal -offset indent
699cd /usr/src/release
700sh release.sh -c arm64/RPI3.conf
701.Ed
702.Pp
703After running these commands, all prepared release files are available in the
704.Pa /scratch
705directory.
706The target directory can be changed by specifying the
707.Va CHROOTDIR
708variable in
709.Li release.conf .
710.Sh COMPATIBILITY
711The reldoc target was removed in commit f61e92ca5a23, and
712.Ev DOCDIR ,
713.Ev DOCBRANCH ,
714.Ev DOC_UPDATE_SKIP ,
715and
716.Ev NODOC
717are therefore no longer supported.
718.Sh SEE ALSO
719.Xr cc 1 ,
720.Xr git 1 Pq Pa ports/devel/git ,
721.Xr install 1 ,
722.Xr make 1 ,
723.Xr mkimg 1 ,
724.Xr uname 1 ,
725.Xr md 4 ,
726.Xr make.conf 5 ,
727.Xr build 7 ,
728.Xr ports 7 ,
729.Xr chroot 8 ,
730.Xr mtree 8 ,
731.Xr sysctl 8
732.Rs
733.%T "FreeBSD Release Engineering"
734.%U https://docs.freebsd.org/en/articles/freebsd-releng/
735.Re
736.Rs
737.%T "FreeBSD Developers' Handbook"
738.%U https://docs.freebsd.org/en/books/developers-handbook/
739.Re
740.Sh HISTORY
741.Fx
7421.x
743used a manual checklist, compiled by
744.An Rod Grimes ,
745to produce a release.
746Apart from being incomplete, the list put a lot of specific demands on
747available file systems and was quite torturous to execute.
748.Pp
749As part of the
750.Fx 2.0
751release engineering effort, significant
752effort was spent getting
753.Pa src/release/Makefile
754into a shape where it could at least automate most of the tediousness
755of building a release in a sterile environment.
756.Pp
757For the
758.Fx 9.0
759release,
760.Pa src/release/Makefile
761was overhauled and the wrapper script
762.Pa src/release/generate-release.sh
763introduced to support the introduction of a new installer.
764.Pp
765For the
766.Fx 9.2
767release,
768.Pa src/release/release.sh
769was introduced to support per-build configuration files.
770.Pa src/release/release.sh
771is heavily based on the
772.Pa src/release/generate-release.sh
773script.
774.Pp
775At near 1000 revisions spread over multiple branches, the
776.Xr git 1
777log of
778.Pa src/release/Makefile
779contains a vivid historical record of some
780of the hardships release engineers go through.
781.Sh AUTHORS
782.Pa src/release/Makefile
783was originally written by
784.An -nosplit
785.An Rod Grimes ,
786.An Jordan Hubbard ,
787and
788.An Poul-Henning Kamp .
789.Pp
790This manual page was originally written by
791.An Murray Stokely Aq Mt murray@FreeBSD.org .
792.Pp
793It was updated by
794.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org
795to include the
796.Fa generate-release.sh
797script used for the
798.Fx 9.0
799release cycle.
800.Pp
801It was later updated by
802.An Glen Barber Aq Mt gjb@FreeBSD.org
803to include the
804.Fa release.sh
805script used for the
806.Fx 9.2
807release cycle.
808