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