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