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 August 6, 2023 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.FreeeBSD.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 MAKEFILE TARGETS 447The release makefile 448.Pq Pa src/release/Makefile 449is fairly abstruse. 450Most developers will only be concerned with the 451.Cm release 452and 453.Cm install 454targets. 455.\" XXX: Some sort of introduction to this list? All the others have one. 456.Bl -tag -width ".Cm packagesystem" 457.It Cm release 458Meta-target to build all release media and distributions applicable to this 459platform. 460.It Cm install 461Copy all produced release media to 462.Pa ${DESTDIR} . 463.It Cm cdrom 464Builds installation CD-ROM images. 465This may require the 466.Xr md 4 467(memory disk) device driver be present in the kernel 468(either by being compiled in or available as a module). 469This target produces files called 470.Pa disc1.iso 471and 472.Pa bootonly.iso 473as its output. 474.It Cm dvdrom 475Builds installation DVD-ROM images. 476This may require the 477.Xr md 4 478(memory disk) device driver be present in the kernel 479(either by being compiled in or available as a module). 480This target produces the 481.Pa dvd1.iso 482file as its output. 483.It Cm memstick 484Builds an installation memory stick image named 485.Pa memstick.img . 486Not applicable on all platforms. 487Requires that the 488.Xr md 4 489.Pq memory disk 490device driver be present in the kernel 491.Pq either by being compiled in or available as a module . 492.It Cm mini-memstick 493Similar to 494.Cm memstick , 495with the exception that the installation distribution sets 496are not included. 497.It Cm ftp 498Creates a directory named 499.Pa ftp 500containing the distribution files used in network installations 501and suitable for upload to an FTP mirror. 502.It Cm vm-image 503Creates virtual machine disk images in various formats. 504The 505.Cm vm-image 506target requires the 507.Va WITH_VMIMAGES 508.Xr make 1 509environment variable to be set to a non-null value. 510.It Cm vm-cloudware 511Builds 512.Fx 513virtual machine images for various cloud hosting providers. 514See 515.Qq CLOUD HOSTING MACHINE IMAGES 516for implementation details. 517.It Cm list-cloudware 518Displays the list of valid 519.Va CLOUDWARE 520values. 521.It Cm list-vmtargets 522Displays the list of valid 523.Va VMFORMATS 524and 525.Va CLOUDWARE 526values. 527.El 528.Pp 529Major subtargets called by targets above: 530.Bl -tag -width ".Cm packagesystem" 531.It Cm packagesystem 532Generates all the distribution archives 533.Pq base, kernel, ports, doc 534applicable on this platform. 535.It Cm disc1 536Builds a bootable installation system containing all the distribution files 537packaged by the 538.Cm packagesystem 539target, and suitable for imaging by the 540.Cm cdrom , 541.Cm dvdrom 542and 543.Cm memstick 544targets. 545.It Cm reldoc 546Builds the release documentation. 547This includes the release notes, 548hardware guide, and installation instructions. 549Other documentation, such as the Handbook, 550is built during the 551.Cm base.txz 552target invoked by 553.Cm packagesystem . 554.El 555.Sh ENVIRONMENT 556Optional variables: 557.Bl -tag -width ".Ev TARGET_ARCH" 558.It Ev OSRELEASE 559Optional base name for generated media images when invoking the 560.Cm install 561target 562.Pq e.g., FreeBSD-12.1-RELEASE-amd64 . 563Defaults to the output of 564.Ic `uname -s`-`uname -r`-`uname -p` 565within the chroot. 566.It Ev WORLDDIR 567Location of a directory containing the src tree. 568By default, the directory 569above the one containing the makefile 570.Pq Pa src . 571.It Ev PORTSDIR 572Location of a directory containing the ports tree. 573By default, 574.Pa /usr/ports . 575If it is unset or cannot be found, ports will not be included in the release. 576.It Ev NOPORTS 577If defined, the Ports Collection will be omitted from the release. 578.It Ev NOSRC 579If set, do not include system source code in the release. 580.It Ev TARGET 581The target hardware platform. 582This is analogous to the 583.Dq Nm uname Fl m 584output. 585This is necessary to cross-build some target architectures. 586For example, cross-building for ARM64 machines requires 587.Ev TARGET_ARCH Ns = Ns Li aarch64 588and 589.Ev TARGET Ns = Ns Li arm64 . 590If not set, 591.Ev TARGET 592defaults to the current hardware platform. 593.It Ev TARGET_ARCH 594The target machine processor architecture. 595This is analogous to the 596.Dq Nm uname Fl p 597output. 598Set this to cross-build for a different architecture. 599If not set, 600.Ev TARGET_ARCH 601defaults to the current machine architecture, unless 602.Ev TARGET 603is also set, in which case it defaults to the appropriate 604value for that platform. 605Typically, one only needs to set 606.Ev TARGET . 607.El 608.Sh FILES 609.Bl -tag -compact -width Pa 610.It Pa /usr/doc/Makefile 611.It Pa /usr/doc/share/mk/doc.project.mk 612.It Pa /usr/ports/Mk/bsd.port.mk 613.It Pa /usr/ports/Mk/bsd.sites.mk 614.It Pa /usr/share/examples/etc/make.conf 615.It Pa /usr/src/Makefile 616.It Pa /usr/src/Makefile.inc1 617.It Pa /usr/src/release/Makefile 618.It Pa /usr/src/release/Makefile.vm 619.It Pa /usr/src/release/release.sh 620.It Pa /usr/src/release/release.conf.sample 621.It Pa /usr/src/release/tools/*.conf 622.It Pa /usr/src/release/tools/vmimage.subr 623.El 624.Sh EXAMPLES 625The following sequence of commands can be used to build a 626.Dq "-CURRENT snapshot": 627.Bd -literal -offset indent 628cd /usr 629git clone -b main https://git.freebsd.org/src.git src 630cd src 631make buildworld buildkernel 632cd release 633make obj 634make release 635make install DESTDIR=/var/freebsd-snapshot 636.Ed 637.Pp 638After running these commands, all produced distribution files (tarballs 639for FTP, CD-ROM images, etc.) are available in the 640.Pa /var/freebsd-snapshot 641directory. 642.Pp 643The following sequence of commands can be used to build a 644.Dq "-CURRENT snapshot" 645in a clean environment, including ports and documentation: 646.Bd -literal -offset indent 647cd /usr/src/release 648sh release.sh 649.Ed 650.Pp 651Optionally, a configuration file can be used to customize the release build: 652.Bd -literal -offset indent 653cd /usr/src/release 654sh release.sh -c $HOME/release.conf 655.Ed 656.Pp 657Configuration files specific to various supported embedded systems, such as 658the Raspberry Pi, exist in the directory corresponding to the 659.Va TARGET 660.Xr make 1 661variable. 662For example, to build an image for the Raspberry Pi: 663.Bd -literal -offset indent 664cd /usr/src/release 665sh release.sh -c arm/RPI-B.conf 666.Ed 667.Pp 668To build an image for the Raspberry Pi 3: 669.Bd -literal -offset indent 670cd /usr/src/release 671sh release.sh -c arm64/RPI3.conf 672.Ed 673.Pp 674After running these commands, all prepared release files are available in the 675.Pa /scratch 676directory. 677The target directory can be changed by specifying the 678.Va CHROOTDIR 679variable in 680.Li release.conf . 681.Sh COMPATIBILITY 682The reldoc target was removed in commit f61e92ca5a23, and 683.Ev DOCDIR , 684.Ev DOCBRANCH , 685.Ev DOC_UPDATE_SKIP , 686and 687.Ev NODOC 688are therefore no longer supported. 689.Sh SEE ALSO 690.Xr cc 1 , 691.Xr git 1 Pq Pa ports/devel/git , 692.Xr install 1 , 693.Xr make 1 , 694.Xr mkimg 1 , 695.Xr uname 1 , 696.Xr md 4 , 697.Xr make.conf 5 , 698.Xr build 7 , 699.Xr ports 7 , 700.Xr chroot 8 , 701.Xr mtree 8 , 702.Xr sysctl 8 703.Rs 704.%T "FreeBSD Release Engineering" 705.%U https://docs.freebsd.org/en/articles/freebsd-releng/ 706.Re 707.Rs 708.%T "FreeBSD Developers' Handbook" 709.%U https://docs.freebsd.org/en/books/developers-handbook/ 710.Re 711.Sh HISTORY 712.Fx 7131.x 714used a manual checklist, compiled by 715.An Rod Grimes , 716to produce a release. 717Apart from being incomplete, the list put a lot of specific demands on 718available file systems and was quite torturous to execute. 719.Pp 720As part of the 721.Fx 2.0 722release engineering effort, significant 723effort was spent getting 724.Pa src/release/Makefile 725into a shape where it could at least automate most of the tediousness 726of building a release in a sterile environment. 727.Pp 728For the 729.Fx 9.0 730release, 731.Pa src/release/Makefile 732was overhauled and the wrapper script 733.Pa src/release/generate-release.sh 734introduced to support the introduction of a new installer. 735.Pp 736For the 737.Fx 9.2 738release, 739.Pa src/release/release.sh 740was introduced to support per-build configuration files. 741.Pa src/release/release.sh 742is heavily based on the 743.Pa src/release/generate-release.sh 744script. 745.Pp 746At near 1000 revisions spread over multiple branches, the 747.Xr git 1 748log of 749.Pa src/release/Makefile 750contains a vivid historical record of some 751of the hardships release engineers go through. 752.Sh AUTHORS 753.Pa src/release/Makefile 754was originally written by 755.An -nosplit 756.An Rod Grimes , 757.An Jordan Hubbard , 758and 759.An Poul-Henning Kamp . 760.Pp 761This manual page was originally written by 762.An Murray Stokely Aq Mt murray@FreeBSD.org . 763.Pp 764It was updated by 765.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org 766to include the 767.Fa generate-release.sh 768script used for the 769.Fx 9.0 770release cycle. 771.Pp 772It was later updated by 773.An Glen Barber Aq Mt gjb@FreeBSD.org 774to include the 775.Fa release.sh 776script used for the 777.Fx 9.2 778release cycle. 779