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 NOPKGBASE 291Include legacy tarball distribution sets for use on the install media, 292instead of base system packages. 293.It Va PKG_CMD 294A path to the 295.Xr pkg 8 296executable to use when installing packages in release images as a non-root user. 297.It Va PKG_REPOS_DIR 298An optional path to a directory containing 299.Xr pkg 8 300repository configuration files. 301These configuration files will be used when installing packages in release 302images as a non-root user. 303.It Va PKG_REPO_NAME 304The name of the repository configuration to use when installing packages in 305release images as a non-root user. 306.El 307.Sh EMBEDDED BUILDS 308The following 309.Fa release.conf 310variables are relevant only to release builds for embedded systems: 311.Bl -tag -width Ev 312.It Va EMBEDDEDBUILD 313Set to a non-null value to enable functionality for embedded device 314release builds. 315.Pp 316When set, 317.Va WITH_DVD 318is unset. 319Additionally, 320.Va EMBEDDED_TARGET 321and 322.Va EMBEDDED_TARGET_ARCH 323must also be defined. 324When the build environment is created, 325.Fa release.sh 326runs a separate build script located in an architecture-specific 327directory in 328.Pa src/release/${EMBEDDED_TARGET}/ . 329.It Va EMBEDDEDPORTS 330Set to the list of any ports that are required for the target device 331in the format of 332.Fa category/port . 333.It Va EMBEDDED_TARGET 334When set, its value is passed to 335.Xr make 1 336to set the 337.Va TARGET 338.Pq value of Cm uname Fl m 339to cross build the target userland. 340.It Va EMBEDDED_TARGET_ARCH 341When set, its value is passed to 342.Xr make 1 343to set the 344.Va TARGET_ARCH 345.Pq value of Cm uname Fl p 346to cross build the target userland. 347.El 348.Sh VIRTUAL MACHINE DISK IMAGES 349The following 350.Fa release.conf 351variables are relevant only to virtual machine disk image builds: 352.Bl -tag -width Ev 353.It Va WITH_VMIMAGES 354Set to a non-null value to build virtual machine disk images as part 355of the release build. 356.Va WITH_VMIMAGES 357may also be specified as an environment variable passed to 358.Xr make 1 . 359.It Va WITH_COMPRESSED_VMIMAGES 360Set to a non-null value to compress the virtual machine disk images with 361.Xr xz 1 362as part of the 363.Cm install 364.Xr make 1 365target. 366Note that compressing virtual machine disk images may take a very long 367time on some systems. 368.It Va VMBASE 369Set to change the name of the resulting virtual machine disk image file. 370The default value is 371.Va vm . 372.It Va VMSIZE 373Set to change the size of the virtual machine disk capacity. 374The default value is 375.Va 20g . 376See 377.Xr makefs 8 378for valid values. 379.Pp 380Virtual machine disk images are, by default, created as sparse images. 381When 382.Va WITH_COMPRESSED_VMIMAGES 383is used, the resulting files compressed with 384.Xr xz 1 385compress to roughly the same size, regardless of the specified disk image 386size. 387.It Va VMFS 388(Deprecated.) 389Set to specify which of the filesystem(s) listed in 390.Va VMFSLIST 391is linked to the historical non-filesystem-labelled file name. 392Valid values are 393.Va ufs 394and 395.Va zfs . 396The default value is 397.Va ufs . 398.It Va VMFSLIST 399Set to specify the list of file system types to build images for. 400Valid values are one or both of 401.Va ufs 402and 403.Va zfs . 404The default value is 405.Va ufs zfs . 406.It Va VMFORMATS 407Set to the target virtual disk image format(s) to create. 408By default, the 409.Va vhdf , Va vmdk , Va qcow2 , 410and 411.Va raw 412formats are created. 413See 414.Xr mkimg 1 415for valid format values. 416.El 417.Pp 418For a list of supported 419.Va VMFORMATS 420values 421.Pq including cloud hosting provider formats 422along with a brief description, run: 423.Bd -literal -offset indent 424cd /usr/src 425make -C release list-vmtargets 426.Ed 427.Sh CLOUD HOSTING MACHINE IMAGES 428The 429.Fx 430release build tools support building virtual machine images for various 431cloud hosting providers, each with their own specific configuration to 432include support for each hosting provider by default. 433.Pp 434The following 435.Xr make 1 436environment variables are supported: 437.Bl -tag -width Ev 438.It Va CLOUDWARE 439Set to a list of one or more cloud hosting providers, enclosed in quotes. 440Requires 441.Va WITH_CLOUDWARE 442to also be set. 443.It Va WITH_CLOUDWARE 444Set to a non-empty value to enable building virtual machine images 445for various cloud hosting providers. 446Requires 447.Va CLOUDWARE 448to also be set. 449.El 450.Pp 451Additionally, the 452.Va CLOUDWARE 453and 454.Va WITH_CLOUDWARE 455variables can be added to 456.Pa release.conf , 457and used in conjunction with 458.Pa release.sh . 459.Pp 460For a list of supported 461.Va CLOUDWARE 462values, run: 463.Bd -literal -offset indent 464cd /usr/src 465make -C release list-cloudware 466.Ed 467.Sh OCI IMAGES 468The 469.Fx 470release build tools have experimental support for building 471Open Container Initiative (OCI) format container base images. 472This is enabled using a 473.Fa release.conf 474variable: 475.Bl -tag -width Ev 476.It Va WITH_OCIIMAGES 477Set to a non-null value to build OCI base images. 478.El 479.Sh MAKEFILE TARGETS 480The release makefile 481.Pq Pa src/release/Makefile 482is fairly abstruse. 483Most developers will only be concerned with the 484.Cm release 485and 486.Cm install 487targets. 488.\" XXX: Some sort of introduction to this list? All the others have one. 489.Bl -tag -width ".Cm packagesystem" 490.It Cm release 491Meta-target to build all release media and distributions applicable to this 492platform. 493.It Cm install 494Copy all produced release media to 495.Pa ${DESTDIR} . 496.It Cm cdrom 497Builds installation CD-ROM images. 498This may require the 499.Xr md 4 500(memory disk) device driver be present in the kernel 501(either by being compiled in or available as a module). 502This target produces files called 503.Pa disc1.iso 504and 505.Pa bootonly.iso 506as its output. 507.It Cm dvdrom 508Builds installation DVD-ROM images. 509This may require the 510.Xr md 4 511(memory disk) device driver be present in the kernel 512(either by being compiled in or available as a module). 513This target produces the 514.Pa dvd1.iso 515file as its output. 516.It Cm memstick 517Builds an installation memory stick image named 518.Pa memstick.img . 519Not applicable on all platforms. 520Requires that the 521.Xr md 4 522.Pq memory disk 523device driver be present in the kernel 524.Pq either by being compiled in or available as a module . 525.It Cm mini-memstick 526Similar to 527.Cm memstick , 528with the exception that the installation distribution sets 529are not included. 530.It Cm ftp 531Creates a directory named 532.Pa ftp 533containing the distribution files used in network installations 534and suitable for upload to an FTP mirror. 535.It Cm vm-image 536Creates virtual machine disk images in various formats. 537The 538.Cm vm-image 539target requires the 540.Va WITH_VMIMAGES 541.Xr make 1 542environment variable to be set to a non-null value. 543.It Cm vm-cloudware 544Builds 545.Fx 546virtual machine images for various cloud hosting providers. 547See 548.Qq CLOUD HOSTING MACHINE IMAGES 549for implementation details. 550.It Cm list-cloudware 551Displays the list of valid 552.Va CLOUDWARE 553values. 554.It Cm list-vmtargets 555Displays the list of valid 556.Va VMFORMATS 557and 558.Va CLOUDWARE 559values. 560.El 561.Pp 562Major subtargets called by targets above: 563.Bl -tag -width ".Cm packagesystem" 564.It Cm packagesystem 565Generates all the distribution archives 566.Pq base, kernel, ports, doc 567applicable on this platform. 568.It Cm disc1 569Builds a bootable installation system containing all the distribution files 570packaged by the 571.Cm packagesystem 572target, and suitable for imaging by the 573.Cm cdrom , 574.Cm dvdrom 575and 576.Cm memstick 577targets. 578.It Cm reldoc 579Builds the release documentation. 580This includes the release notes, 581hardware guide, and installation instructions. 582Other documentation, such as the Handbook, 583is built during the 584.Cm base.txz 585target invoked by 586.Cm packagesystem . 587.El 588.Sh ENVIRONMENT 589Optional variables: 590.Bl -tag -width ".Ev TARGET_ARCH" 591.It Ev OSRELEASE 592Optional base name for generated media images when invoking the 593.Cm install 594target 595.Pq e.g., FreeBSD-12.1-RELEASE-amd64 . 596Defaults to the output of 597.Ic `uname -s`-`uname -r`-`uname -p` 598within the chroot. 599.It Ev WORLDDIR 600Location of a directory containing the src tree. 601By default, the directory 602above the one containing the makefile 603.Pq Pa src . 604.It Ev PORTSDIR 605Location of a directory containing the ports tree. 606By default, 607.Pa /usr/ports . 608If it is unset or cannot be found, ports will not be included in the release. 609.It Ev NOPORTS 610If defined, the Ports Collection will be omitted from the release. 611.It Ev NOSRC 612If set, do not include system source code in the release. 613.It Ev TARGET 614The target hardware platform. 615This is analogous to the 616.Dq Nm uname Fl m 617output. 618This is necessary to cross-build some target architectures. 619For example, cross-building for ARM64 machines requires 620.Ev TARGET_ARCH Ns = Ns Li aarch64 621and 622.Ev TARGET Ns = Ns Li arm64 . 623If not set, 624.Ev TARGET 625defaults to the current hardware platform. 626.It Ev TARGET_ARCH 627The target machine processor architecture. 628This is analogous to the 629.Dq Nm uname Fl p 630output. 631Set this to cross-build for a different architecture. 632If not set, 633.Ev TARGET_ARCH 634defaults to the current machine architecture, unless 635.Ev TARGET 636is also set, in which case it defaults to the appropriate 637value for that platform. 638Typically, one only needs to set 639.Ev TARGET . 640.El 641.Sh FILES 642.Bl -tag -compact -width Pa 643.It Pa /scratch 644.It Pa /usr/doc/Makefile 645.It Pa /usr/doc/share/mk/doc.project.mk 646.It Pa /usr/ports/Mk/bsd.port.mk 647.It Pa /usr/ports/Mk/bsd.sites.mk 648.It Pa /usr/share/examples/etc/make.conf 649.It Pa /usr/src/Makefile 650.It Pa /usr/src/Makefile.inc1 651.It Pa /usr/src/release/Makefile 652.It Pa /usr/src/release/Makefile.vm 653.It Pa /usr/src/release/release.sh 654.It Pa /usr/src/release/release.conf.sample 655.It Pa /usr/src/release/tools/*.conf 656.It Pa /usr/src/release/tools/vmimage.subr 657.El 658.Sh EXAMPLES 659The following sequence of commands can be used to build a 660.Dq "-CURRENT snapshot": 661.Bd -literal -offset indent 662cd /usr 663git clone -b main https://git.freebsd.org/src.git src 664cd src 665make buildworld buildkernel 666cd release 667make obj 668make release 669make install DESTDIR=/var/freebsd-snapshot 670.Ed 671.Pp 672After running these commands, all produced distribution files (tarballs 673for FTP, CD-ROM images, etc.) are available in the 674.Pa /var/freebsd-snapshot 675directory. 676.Pp 677The following sequence of commands can be used to build a 678.Dq "-CURRENT snapshot" 679in a clean environment, including ports and documentation: 680.Bd -literal -offset indent 681cd /usr/src/release 682sh release.sh 683.Ed 684.Pp 685Optionally, a configuration file can be used to customize the release build: 686.Bd -literal -offset indent 687cd /usr/src/release 688sh release.sh -c $HOME/release.conf 689.Ed 690.Pp 691Configuration files specific to various supported embedded systems, such as 692the Raspberry Pi, exist in the directory corresponding to the 693.Va TARGET 694.Xr make 1 695variable. 696For example, to build an image for 64-bit Raspberry Pis: 697.Bd -literal -offset indent 698cd /usr/src/release 699sh release.sh -c arm64/RPI.conf 700.Ed 701.Pp 702After running these commands, all prepared release files are available in the 703.Pa /scratch 704directory. 705The target directory can be changed by specifying the 706.Va CHROOTDIR 707variable in 708.Li release.conf . 709.Sh COMPATIBILITY 710The reldoc target was removed in commit f61e92ca5a23, and 711.Ev DOCDIR , 712.Ev DOCBRANCH , 713.Ev DOC_UPDATE_SKIP , 714and 715.Ev NODOC 716are therefore no longer supported. 717.Sh SEE ALSO 718.Xr cc 1 , 719.Xr git 1 Pq Pa ports/devel/git , 720.Xr install 1 , 721.Xr make 1 , 722.Xr mkimg 1 , 723.Xr uname 1 , 724.Xr md 4 , 725.Xr make.conf 5 , 726.Xr build 7 , 727.Xr ports 7 , 728.Xr chroot 8 , 729.Xr mtree 8 , 730.Xr sysctl 8 731.Rs 732.%T "FreeBSD Release Engineering" 733.%U https://docs.freebsd.org/en/articles/freebsd-releng/ 734.Re 735.Rs 736.%T "FreeBSD Developers' Handbook" 737.%U https://docs.freebsd.org/en/books/developers-handbook/ 738.Re 739.Sh HISTORY 740.Fx 7411.x 742used a manual checklist, compiled by 743.An Rod Grimes , 744to produce a release. 745Apart from being incomplete, the list put a lot of specific demands on 746available file systems and was quite torturous to execute. 747.Pp 748As part of the 749.Fx 2.0 750release engineering effort, significant 751effort was spent getting 752.Pa src/release/Makefile 753into a shape where it could at least automate most of the tediousness 754of building a release in a sterile environment. 755.Pp 756For the 757.Fx 9.0 758release, 759.Pa src/release/Makefile 760was overhauled and the wrapper script 761.Pa src/release/generate-release.sh 762introduced to support the introduction of a new installer. 763.Pp 764For the 765.Fx 9.2 766release, 767.Pa src/release/release.sh 768was introduced to support per-build configuration files. 769.Pa src/release/release.sh 770is heavily based on the 771.Pa src/release/generate-release.sh 772script. 773.Pp 774At near 1000 revisions spread over multiple branches, the 775.Xr git 1 776log of 777.Pa src/release/Makefile 778contains a vivid historical record of some 779of the hardships release engineers go through. 780.Sh AUTHORS 781.Pa src/release/Makefile 782was originally written by 783.An -nosplit 784.An Rod Grimes , 785.An Jordan Hubbard , 786and 787.An Poul-Henning Kamp . 788.Pp 789This manual page was originally written by 790.An Murray Stokely Aq Mt murray@FreeBSD.org . 791.Pp 792It was updated by 793.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org 794to include the 795.Fa generate-release.sh 796script used for the 797.Fx 9.0 798release cycle. 799.Pp 800It was later updated by 801.An Glen Barber Aq Mt gjb@FreeBSD.org 802to include the 803.Fa release.sh 804script used for the 805.Fx 9.2 806release cycle. 807