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