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.\" $FreeBSD$ 26.\" 27.Dd October 28, 2022 28.Dt RELEASE 7 29.Os 30.Sh NAME 31.Nm release 32.Nd "release building infrastructure" 33.Sh DESCRIPTION 34.Fx 35provides a complete build environment suitable for users to make 36full releases of the 37.Fx 38operating system. 39All of the tools necessary to build a release are available from the 40.Fx 41source code repository in 42.Pa src/release . 43A complete release can be built with only a single command, 44including the creation of ISO images suitable for burning to CD-ROM, 45memory stick images, and a network install directory. 46This command is aptly named 47.Dq Li "make release" . 48.Pp 49For some users, it may be desirable to provide an absolutely clean 50build environment, with no local modifications to the source tree or to 51.Xr make.conf 5 , 52and with clean checkouts of specific versions of the doc, src, and ports 53trees. 54For this purpose, a script 55.Pq Pa src/release/release.sh 56is provided to automate these checkouts and then execute 57.Dq Li "make release" 58in a clean 59.Xr chroot 8 . 60.Pp 61Before attempting to build a release, the user is expected to be 62familiar with the contents of 63.Xr build 7 , 64and should have experience upgrading systems from source. 65.Pp 66The release build process requires that 67.Pa /usr/obj 68be populated with the output of 69.Dq Li "make buildworld" 70and 71.Dq Li "make buildkernel" . 72This is necessary to provide the object files for the release or, when 73using 74.Pa release.sh , 75so that the object files for a complete system can be installed into a clean 76.Xr chroot 8 77environment. 78.Pp 79If the target release build is for a different architecture or machine type, 80the 81.Va TARGET 82and 83.Va TARGET_ARCH 84variables must be used. 85See the supported 86.Fa release.conf 87variables for more information. 88.Pp 89The release procedure on some architectures may also require that the 90.Xr md 4 91(memory disk) device driver be present in the kernel 92.Pq either by being compiled in or available as a module . 93.Pp 94This document does not cover source code management, quality 95assurance, or other aspects of the release engineering process. 96.Sh CLEAN RELEASE GENERATION 97Official releases of 98.Fx 99are produced in a clean environment to 100ensure consistency between the versions of the src, ports, and doc trees 101and to avoid contamination from the host system 102.Po such as local patches, changes 103to 104.Xr make.conf 5 , 105etc. 106.Pc . 107This is accomplished using the wrapper script 108.Pa src/release/release.sh . 109.Pp 110.Ic release.sh 111.Op Fl c Ar release.conf 112.Pp 113.Ic release.sh 114checks out the 115.Li src/ , 116.Li ports/ , 117and 118.Li doc/ 119trees to 120.Va CHROOTDIR , 121then calls 122.Dq Li "make buildworld" 123and 124.Dq Li "make installworld" 125to generate a 126.Xr chroot 8 127environment. 128Next, 129.Dq Li "make release" 130is run within the 131.Xr chroot 8 132environment and places the result in 133.Pa $CHROOTDIR/R . 134.Pp 135The optional 136.Fa release.conf 137configuration file supports the following variables: 138.Bl -tag -width Ev 139.It Va CHROOTDIR 140The directory within which the release will be built. 141.It Va CHROOT_MAKEENV 142Additional 143.Xr make 1 144arguments to pass through, which directly affect the 145tuning of the build chroot. 146.It Va NOGIT 147Do not explicitly require the 148.Xr git 1 149port to be installed. 150.It Va GITROOT 151The 152.Xr git 1 153host used to check out the various trees. 154Defaults to 155.Pa https://git.FreeeBSD.org . 156.It Va SRCBRANCH 157The 158.Li src/ 159branch to use. 160Defaults to 161.Fl b Va main . 162.It Va PORTBRANCH 163The 164.Li ports/ 165branch to use. 166Defaults to 167.Va head/@rHEAD . 168.It Va TARGET 169The target machine type for cross-building a release. 170.It Va TARGET_ARCH 171The target machine architecture for cross-building a release. 172.Pp 173For the supported list of 174.Va TARGET 175and 176.Va TARGET_ARCH 177combinations, consult the output of 178.Dq make targets 179as documented in 180.Xr build 7 . 181.It Va KERNEL 182The target kernel configuration to use. 183Defaults to 184.Va GENERIC . 185Multiple 186.Va KERNEL 187entries may be specified. 188.It Va MAKE_CONF 189The 190.Xr make.conf 5 191to use for the release build. 192Defaults to 193.Fa /dev/null 194to prevent polluting the release with local system changes. 195.It Va SRC_CONF 196The 197.Xr src.conf 5 198to use for the release build. 199Defaults to 200.Fa /dev/null 201to prevent polluting the release with local system changes. 202.It Va MAKE_FLAGS 203Additional flags to pass to 204.Xr make 1 . 205.It Va WORLD_FLAGS 206Additional flags to pass to 207.Xr make 1 208during the 209.Dq buildworld 210phase. 211Defaults to setting the number of 212.Xr make 1 213jobs 214.Pq Ar -j 215to the number of CPUs available on a SMP-capable system. 216.It Va KERNEL_FLAGS 217Additional flags to pass to 218.Xr make 1 219during the 220.Dq buildkernel 221phase. 222Defaults to setting the number of 223.Xr make 1 224jobs 225.Pq Ar -j 226to half the number of CPUs available on a SMP-capable system. 227.It Va NOPORTS 228Set to a non-empty value to skip the 229.Li ports/ 230tree checkout. 231When set, 232.Va NOPORTS 233will prevent the 234.Fa ports.txz 235distribution package from being created. 236.It Va WITH_DVD 237Set to a non-empty value to include the 238.Cm dvdrom 239target. 240.It Va WITH_COMPRESSED_IMAGES 241Set to a non-empty value to compress the release images with 242.Xr xz 1 . 243The original 244.Pq uncompressed 245images are not removed. 246.It Va XZ_THREADS Pq Vt int 247Set to the number of threads 248.Xr xz 1 249should use when compressing images. 250By default, 251.Va XZ_THREADS 252is set to 253.Va 0 , 254which uses all available cores on the system. 255.It Va VCSCMD 256The command run to obtain the source trees. 257Defaults to 258.Qq Cm git clone Fl q . 259.It Va CHROOTBUILD_SKIP 260If defined, the 261.Li buildworld , 262.Li installworld , 263and 264.Li distribution 265stages of the 266.Xr chroot 8 267build environment setup are skipped. 268This is intended solely for cases where the 269.Xr chroot 8 270userland are provided by alternate means. 271.It Va SRC_UPDATE_SKIP 272Set to a non-empty value to prevent checkout or update of 273.Fa /usr/src 274within the 275.Xr chroot 8 . 276This is intended for use only when 277.Fa /usr/src 278is expected to exist by alternative means. 279.It Va PORTS_UPDATE_SKIP 280Set to a non-empty value to prevent checkout or update of 281.Fa /usr/ports 282within the 283.Xr chroot 8 . 284This is intended for use only when 285.Fa /usr/ports 286is expected to exist by alternative means. 287.El 288.Sh EMBEDDED BUILDS 289The following 290.Fa release.conf 291variables are relevant only to release builds for embedded systems: 292.Bl -tag -width Ev 293.It Va EMBEDDEDBUILD 294Set to a non-null value to enable functionality for embedded device 295release builds. 296.Pp 297When set, 298.Va WITH_DVD 299is unset. 300Additionally, 301.Va EMBEDDED_TARGET 302and 303.Va EMBEDDED_TARGET_ARCH 304must also be defined. 305When the build environment is created, 306.Fa release.sh 307runs a separate build script located in an architecture-specific 308directory in 309.Pa src/release/${EMBEDDED_TARGET}/ . 310.It Va EMBEDDEDPORTS 311Set to the list of any ports that are required for the target device 312in the format of 313.Fa category/port . 314.It Va EMBEDDED_TARGET 315When set, its value is passed to 316.Xr make 1 317to set the 318.Va TARGET 319.Pq value of Cm uname Fl m 320to cross build the target userland. 321.It Va EMBEDDED_TARGET_ARCH 322When set, its value is passed to 323.Xr make 1 324to set the 325.Va TARGET_ARCH 326.Pq value of Cm uname Fl p 327to cross build the target userland. 328.El 329.Sh VIRTUAL MACHINE DISK IMAGES 330The following 331.Fa release.conf 332variables are relevant only to virtual machine disk image builds: 333.Bl -tag -width Ev 334.It Va WITH_VMIMAGES 335Set to a non-null value to build virtual machine disk images as part 336of the release build. 337.Va WITH_VMIMAGES 338may also be specified as an environment variable passed to 339.Xr make 1 . 340.It Va WITH_COMPRESSED_VMIMAGES 341Set to a non-null value to compress the virtual machine disk images with 342.Xr xz 1 343as part of the 344.Cm install 345.Xr make 1 346target. 347Note that compressing virtual machine disk images may take a very long 348time on some systems. 349.It Va VMBASE 350Set to change the name of the resulting virtual machine disk image file. 351The default value is 352.Va vm . 353.It Va VMSIZE 354Set to change the size of the virtual machine disk capacity. 355The default value is 356.Va 20g . 357See 358.Xr makefs 8 359for valid values. 360.Pp 361Virtual machine disk images are, by default, created as sparse images. 362When 363.Va WITH_COMPRESSED_VMIMAGES 364is used, the resulting files compressed with 365.Xr xz 1 366compress to roughly the same size, regardless of the specified disk image 367size. 368.It Va VMFS 369(Deprecated.) 370Set to specify which of the filesystem(s) listed in 371.Va VMFSLIST 372is linked to the historical non-filesystem-labelled file name. 373Valid values are 374.Va ufs 375and 376.Va zfs . 377The default value is 378.Va ufs . 379.It Va VMFSLIST 380Set to specify the list of file system types to build images for. 381Valid values are one or both of 382.Va ufs 383and 384.Va zfs . 385The default value is 386.Va ufs zfs . 387.It Va VMFORMATS 388Set to the target virtual disk image format(s) to create. 389By default, the 390.Va vhdf , Va vmdk , Va qcow2 , 391and 392.Va raw 393formats are created. 394See 395.Xr mkimg 1 396for valid format values. 397.El 398.Pp 399For a list of supported 400.Va VMFORMATS 401values 402.Pq including cloud hosting provider formats 403along with a brief description, run: 404.Bd -literal -offset indent 405cd /usr/src 406make -C release list-vmtargets 407.Ed 408.Sh CLOUD HOSTING MACHINE IMAGES 409The 410.Fx 411release build tools support building virtual machine images for various 412cloud hosting providers, each with their own specific configuration to 413include support for each hosting provider by default. 414.Pp 415The following 416.Xr make 1 417environment variables are supported: 418.Bl -tag -width Ev 419.It Va CLOUDWARE 420Set to a list of one or more cloud hosting providers, enclosed in quotes. 421Requires 422.Va WITH_CLOUDWARE 423to also be set. 424.It Va WITH_CLOUDWARE 425Set to a non-empty value to enable building virtual machine images 426for various cloud hosting providers. 427Requires 428.Va CLOUDWARE 429to also be set. 430.El 431.Pp 432Additionally, the 433.Va CLOUDWARE 434and 435.Va WITH_CLOUDWARE 436variables can be added to 437.Pa release.conf , 438and used in conjunction with 439.Pa release.sh . 440.Pp 441For a list of supported 442.Va CLOUDWARE 443values, run: 444.Bd -literal -offset indent 445cd /usr/src 446make -C release list-cloudware 447.Ed 448.Sh MAKEFILE TARGETS 449The release makefile 450.Pq Pa src/release/Makefile 451is fairly abstruse. 452Most developers will only be concerned with the 453.Cm release 454and 455.Cm install 456targets. 457.\" XXX: Some sort of introduction to this list? All the others have one. 458.Bl -tag -width ".Cm packagesystem" 459.It Cm release 460Meta-target to build all release media and distributions applicable to this 461platform. 462.It Cm install 463Copy all produced release media to 464.Pa ${DESTDIR} . 465.It Cm cdrom 466Builds installation CD-ROM images. 467This may require the 468.Xr md 4 469(memory disk) device driver be present in the kernel 470(either by being compiled in or available as a module). 471This target produces files called 472.Pa disc1.iso 473and 474.Pa bootonly.iso 475as its output. 476.It Cm dvdrom 477Builds installation DVD-ROM images. 478This may require the 479.Xr md 4 480(memory disk) device driver be present in the kernel 481(either by being compiled in or available as a module). 482This target produces the 483.Pa dvd1.iso 484file as its output. 485.It Cm memstick 486Builds an installation memory stick image named 487.Pa memstick.img . 488Not applicable on all platforms. 489Requires that the 490.Xr md 4 491.Pq memory disk 492device driver be present in the kernel 493.Pq either by being compiled in or available as a module . 494.It Cm mini-memstick 495Similar to 496.Cm memstick , 497with the exception that the installation distribution sets 498are not included. 499.It Cm ftp 500Creates a directory named 501.Pa ftp 502containing the distribution files used in network installations 503and suitable for upload to an FTP mirror. 504.It Cm vm-image 505Creates virtual machine disk images in various formats. 506The 507.Cm vm-image 508target requires the 509.Va WITH_VMIMAGES 510.Xr make 1 511environment variable to be set to a non-null value. 512.It Cm vm-cloudware 513Builds 514.Fx 515virtual machine images for various cloud hosting providers. 516See 517.Qq CLOUD HOSTING MACHINE IMAGES 518for implementation details. 519.It Cm list-cloudware 520Displays the list of valid 521.Va CLOUDWARE 522values. 523.It Cm list-vmtargets 524Displays the list of valid 525.Va VMFORMATS 526and 527.Va CLOUDWARE 528values. 529.El 530.Pp 531Major subtargets called by targets above: 532.Bl -tag -width ".Cm packagesystem" 533.It Cm packagesystem 534Generates all the distribution archives 535.Pq base, kernel, ports, doc 536applicable on this platform. 537.It Cm disc1 538Builds a bootable installation system containing all the distribution files 539packaged by the 540.Cm packagesystem 541target, and suitable for imaging by the 542.Cm cdrom , 543.Cm dvdrom 544and 545.Cm memstick 546targets. 547.It Cm reldoc 548Builds the release documentation. 549This includes the release notes, 550hardware guide, and installation instructions. 551Other documentation, such as the Handbook, 552is built during the 553.Cm base.txz 554target invoked by 555.Cm packagesystem . 556.El 557.Sh ENVIRONMENT 558Optional variables: 559.Bl -tag -width ".Ev TARGET_ARCH" 560.It Ev OSRELEASE 561Optional base name for generated media images when invoking the 562.Cm install 563target 564.Pq e.g., FreeBSD-12.1-RELEASE-amd64 . 565Defaults to the output of 566.Ic `uname -s`-`uname -r`-`uname -p` 567within the chroot. 568.It Ev WORLDDIR 569Location of a directory containing the src tree. 570By default, the directory 571above the one containing the makefile 572.Pq Pa src . 573.It Ev PORTSDIR 574Location of a directory containing the ports tree. 575By default, 576.Pa /usr/ports . 577If it is unset or cannot be found, ports will not be included in the release. 578.It Ev NOPORTS 579If defined, the Ports Collection will be omitted from the release. 580.It Ev NOSRC 581If set, do not include system source code in the release. 582.It Ev TARGET 583The target hardware platform. 584This is analogous to the 585.Dq Nm uname Fl m 586output. 587This is necessary to cross-build some target architectures. 588For example, cross-building for ARM64 machines requires 589.Ev TARGET_ARCH Ns = Ns Li aarch64 590and 591.Ev TARGET Ns = Ns Li arm64 . 592If not set, 593.Ev TARGET 594defaults to the current hardware platform. 595.It Ev TARGET_ARCH 596The target machine processor architecture. 597This is analogous to the 598.Dq Nm uname Fl p 599output. 600Set this to cross-build for a different architecture. 601If not set, 602.Ev TARGET_ARCH 603defaults to the current machine architecture, unless 604.Ev TARGET 605is also set, in which case it defaults to the appropriate 606value for that platform. 607Typically, one only needs to set 608.Ev TARGET . 609.El 610.Sh FILES 611.Bl -tag -compact -width Pa 612.It Pa /usr/doc/Makefile 613.It Pa /usr/doc/share/mk/doc.project.mk 614.It Pa /usr/ports/Mk/bsd.port.mk 615.It Pa /usr/ports/Mk/bsd.sites.mk 616.It Pa /usr/share/examples/etc/make.conf 617.It Pa /usr/src/Makefile 618.It Pa /usr/src/Makefile.inc1 619.It Pa /usr/src/release/Makefile 620.It Pa /usr/src/release/Makefile.vm 621.It Pa /usr/src/release/release.sh 622.It Pa /usr/src/release/release.conf.sample 623.It Pa /usr/src/release/tools/*.conf 624.It Pa /usr/src/release/tools/vmimage.subr 625.El 626.Sh EXAMPLES 627The following sequence of commands can be used to build a 628.Dq "-CURRENT snapshot": 629.Bd -literal -offset indent 630cd /usr 631git clone -b main https://git.freebsd.org/src.git src 632cd src 633make buildworld buildkernel 634cd release 635make obj 636make release 637make install DESTDIR=/var/freebsd-snapshot 638.Ed 639.Pp 640After running these commands, all produced distribution files (tarballs 641for FTP, CD-ROM images, etc.) are available in the 642.Pa /var/freebsd-snapshot 643directory. 644.Pp 645The following sequence of commands can be used to build a 646.Dq "-CURRENT snapshot" 647in a clean environment, including ports and documentation: 648.Bd -literal -offset indent 649cd /usr/src/release 650sh release.sh 651.Ed 652.Pp 653Optionally, a configuration file can be used to customize the release build: 654.Bd -literal -offset indent 655cd /usr/src/release 656sh release.sh -c $HOME/release.conf 657.Ed 658.Pp 659Configuration files specific to various supported embedded systems, such as 660the Raspberry Pi, exist in the directory corresponding to the 661.Va TARGET 662.Xr make 1 663variable. 664For example, to build an image for the Raspberry Pi: 665.Bd -literal -offset indent 666cd /usr/src/release 667sh release.sh -c arm/RPI-B.conf 668.Ed 669.Pp 670To build an image for the Raspberry Pi 3: 671.Bd -literal -offset indent 672cd /usr/src/release 673sh release.sh -c arm64/RPI3.conf 674.Ed 675.Pp 676After running these commands, all prepared release files are available in the 677.Pa /scratch 678directory. 679The target directory can be changed by specifying the 680.Va CHROOTDIR 681variable in 682.Li release.conf . 683.Sh COMPATIBILITY 684The reldoc target was removed in commit f61e92ca5a23, and 685.Ev DOCDIR , 686.Ev DOCBRANCH , 687.Ev DOC_UPDATE_SKIP , 688and 689.Ev NODOC 690are therefore no longer supported. 691.Sh SEE ALSO 692.Xr cc 1 , 693.Xr git 1 Pq Pa ports/devel/git , 694.Xr install 1 , 695.Xr make 1 , 696.Xr mkimg 1 , 697.Xr uname 1 , 698.Xr md 4 , 699.Xr make.conf 5 , 700.Xr build 7 , 701.Xr ports 7 , 702.Xr chroot 8 , 703.Xr mtree 8 , 704.Xr sysctl 8 705.Rs 706.%T "FreeBSD Release Engineering" 707.%U https://docs.freebsd.org/en/articles/freebsd-releng/ 708.Re 709.Rs 710.%T "FreeBSD Developers' Handbook" 711.%U https://docs.freebsd.org/en/books/developers-handbook/ 712.Re 713.Sh HISTORY 714.Fx 7151.x 716used a manual checklist, compiled by 717.An Rod Grimes , 718to produce a release. 719Apart from being incomplete, the list put a lot of specific demands on 720available file systems and was quite torturous to execute. 721.Pp 722As part of the 723.Fx 2.0 724release engineering effort, significant 725effort was spent getting 726.Pa src/release/Makefile 727into a shape where it could at least automate most of the tediousness 728of building a release in a sterile environment. 729.Pp 730For the 731.Fx 9.0 732release, 733.Pa src/release/Makefile 734was overhauled and the wrapper script 735.Pa src/release/generate-release.sh 736introduced to support the introduction of a new installer. 737.Pp 738For the 739.Fx 9.2 740release, 741.Pa src/release/release.sh 742was introduced to support per-build configuration files. 743.Pa src/release/release.sh 744is heavily based on the 745.Pa src/release/generate-release.sh 746script. 747.Pp 748At near 1000 revisions spread over multiple branches, the 749.Xr git 1 750log of 751.Pa src/release/Makefile 752contains a vivid historical record of some 753of the hardships release engineers go through. 754.Sh AUTHORS 755.Pa src/release/Makefile 756was originally written by 757.An -nosplit 758.An Rod Grimes , 759.An Jordan Hubbard , 760and 761.An Poul-Henning Kamp . 762.Pp 763This manual page was originally written by 764.An Murray Stokely Aq Mt murray@FreeBSD.org . 765.Pp 766It was updated by 767.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org 768to include the 769.Fa generate-release.sh 770script used for the 771.Fx 9.0 772release cycle. 773.Pp 774It was later updated by 775.An Glen Barber Aq Mt gjb@FreeBSD.org 776to include the 777.Fa release.sh 778script used for the 779.Fx 9.2 780release cycle. 781