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