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 February 20, 2015 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 actually be built with only a single command, 44including the creation of ISO images suitable for burning to CD-ROM, 45memory stick images, and an FTP 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 totally 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 SVNROOT 147The 148.Xr svn 1 149host used to check out the various trees. 150Defaults to 151.Pa svn://svn.FreeeBSD.org . 152.It Va SRCBRANCH 153The 154.Li src/ 155branch to use. 156Defaults to 157.Va head/@rHEAD . 158.It Va DOCBRANCH 159The 160.Li doc/ 161branch to use. 162Defaults to 163.Va head/@rHEAD . 164.It Va PORTBRANCH 165The 166.Li ports/ 167branch to use. 168Defaults to 169.Va head/@rHEAD . 170.It Va TARGET 171The target machine type for cross-building a release. 172.It Va TARGET_ARCH 173The target machine architecture for cross-building a release. 174.Pp 175For the supported list of 176.Va TARGET 177and 178.Va TARGET_ARCH 179combinations, consult the output of 180.Dq make targets 181as documented in 182.Xr build 7 . 183.It Va KERNEL 184The target kernel configuration to use. 185Defaults to 186.Va GENERIC . 187Multiple 188.Va KERNEL 189entries may be specified. 190.It Va MAKE_CONF 191The 192.Xr make.conf 5 193to use for the release build. 194Defaults to 195.Fa /dev/null 196to prevent polluting the release with local system changes. 197.It Va SRC_CONF 198The 199.Xr src.conf 5 200to use for the release build. 201Defaults to 202.Fa /dev/null 203to prevent polluting the release with local system changes. 204.It Va MAKE_FLAGS 205Additional flags to pass to 206.Xr make 1 . 207.It Va WORLD_FLAGS 208Additional flags to pass to 209.Xr make 1 210during the 211.Dq buildworld 212phase. 213Defaults to setting the number of 214.Xr make 1 215jobs 216.Pq Ar -j 217to the number of CPUs available on a SMP-capable system. 218.It Va KERNEL_FLAGS 219Additional flags to pass to 220.Xr make 1 221during the 222.Dq buildkernel 223phase. 224Defaults to setting the number of 225.Xr make 1 226jobs 227.Pq Ar -j 228to half the number of CPUs available on a SMP-capable system. 229.It Va NODOC 230Set to a non-empty value to skip the 231.Li doc/ 232tree checkout. 233When set, 234.Va NODOC 235will prevent the 236.Fa doc.txz 237distribution package from being created. 238.It Va NOPORTS 239Set to a non-empty value to skip the 240.Li ports/ 241tree checkout. 242When set, 243.Va NOPORTS 244will prevent the 245.Fa ports.txz 246distribution package from being created. 247Setting this also sets 248.Va NODOC . 249.It Va WITH_DVD 250Set to a non-empty value to include the 251.Cm dvdrom 252target. 253.It Va WITH_COMPRESSED_IMAGES 254Set to a non-empty value to compress the release images with 255.Xr xz 1 . 256The original 257.Pq uncompressed 258images are not removed. 259.It Va XZ_THREADS Pq Vt int 260Set to the number of threads 261.Xr xz 1 262should use when compressing images. 263By default, 264.Va XZ_THREADS 265is set to 266.Va 0 , 267which uses all available cores on the system. 268.It Va VCSCMD 269The command run to obtain the source trees. 270Defaults to 271.Qq Cm svn checkout . 272.It Va CHROOTBUILD_SKIP 273If defined, the 274.Li buildworld , 275.Li installworld , 276and 277.Li distribution 278stages of the 279.Xr chroot 8 280build environment setup are skipped. 281This is intended solely for cases where the 282.Xr chroot 8 283userland are provided by alternate means. 284.It Va SRC_UPDATE_SKIP 285Set to a non-empty value to prevent checkout or update of 286.Fa /usr/src 287within the 288.Xr chroot 8 . 289This is intended for use only when 290.Fa /usr/src 291is expected to exist by alternative means. 292.It Va DOC_UPDATE_SKIP 293Set to a non-empty value to prevent checkout or update of 294.Fa /usr/doc 295within the 296.Xr chroot 8 . 297This is intended for use only when 298.Fa /usr/doc 299is expected to exist by alternative means. 300.It Va PORTS_UPDATE_SKIP 301Set to a non-empty value to prevent checkout or update of 302.Fa /usr/ports 303within the 304.Xr chroot 8 . 305This is intended for use only when 306.Fa /usr/ports 307is expected to exist by alternative means. 308.El 309.Sh EMBEDDED BUILDS 310The following 311.Fa release.conf 312variables are relevant only to release builds for embedded systems: 313.Bl -tag -width Ev 314.It Va EMBEDDEDBUILD 315Set to a non-null value to enable functionality for embedded device 316release builds. 317.Pq This option is considered highly experimental. 318.Pp 319When set, 320.Va WITH_DVD 321is unset, and 322.Va NODOC 323is defined. 324Additionally, 325.Va XDEV 326and 327.Va XDEV_ARCH 328must also be defined. 329When the build environment is created, 330.Fa release.sh 331runs a separate build script located in an architecture-specific 332directory in 333.Pa src/release/${XDEV}/ . 334.It Va EMBEDDEDPORTS 335Set to the list of any ports that are required for the target device 336in the format of 337.Fa category/port . 338The 339.Fa devel/subversion 340port is built by default. 341.It Va CROCHETSRC 342Set to the source URL for the Crochet build tool. 343.It Va CROCHETBRANCH 344Set to the subversion branch from 345.Va ${CROCHETSRC} 346to use. 347Defaults to 348.Pa trunk . 349.It Va UBOOTSRC 350Set to the source URL of u-boot, if required. 351.It Va UBOOTBRANCH 352Set to the subversion branch from 353.Va ${UBOOTSRC} 354to use. 355Defaults to 356.Pa trunk . 357.It Va UBOOTDIR 358Set to the target directory within 359.Va ${CHROOTDIR} 360to check out 361.Va ${UBOOTSRC}/${UBOOTBRANCH} . 362.El 363.Sh VIRTUAL MACHINE DISK IMAGES 364The following 365.Fa release.conf 366variables are relevant only to virtual machine disk image builds: 367.Bl -tag -width Ev 368.It Va WITH_VMIMAGES 369Set to a non-null value to build virtual machine disk images as part 370of the release build. 371.Va WITH_VMIMAGES 372may also be specified as an envirionment variable passed to 373.Xr make 1 . 374.Pp 375The option requires 376.Xr mkimg 1 377version 20140927 or later. 378.It Va WITH_COMPRESSED_VMIMAGES 379Set to a non-null value to compress the virtual machine disk images with 380.Xr xz 1 381as part of the 382.Cm install 383.Xr make 1 384target. 385Note that compressing virtual machine disk images may take a very long 386time on some systems. 387.It Va VMBASE 388Set to change the name of the resulting virtual machine disk image file. 389The default value is 390.Va vm . 391.It Va VMSIZE 392Set to change the size of the virtual machine disk capacity. 393The default value is 394.Va 20G . 395See 396.Xr truncate 1 397for valid values. 398.Pp 399Virtual machine disk images are, by default, created as sparse images. 400When 401.Va WITH_COMPRESSED_VMIMAGES 402is used, the resulting files compressed with 403.Xr xz 1 404compress to roughly the same size, regardless of the specified disk image 405size. 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.Pq requires version 20140927 or later . 417.El 418.Pp 419For a list of supported 420.Va VMFORMATS 421values 422.Pq including cloud hosting provider formats 423along with a brief description, run: 424.Bd -literal -offset indent 425cd /usr/src 426make -C release list-vmtargets 427.Ed 428.Sh CLOUD HOSTING MACHINE IMAGES 429The 430.Fx 431release build tools support building virtual machine images for various 432cloud hosting providers, each with their own specific configuration to 433include support for each hosting provider by default. 434.Pp 435The following 436.Xr make 1 437environment variables are supported: 438.Pp 439.Bl -tag -width Ev 440.It Va CLOUDWARE 441Set to a list of one or more cloud hosting providers, enclosed in quotes. 442Requires 443.Va WITH_CLOUDWARE 444to also be set. 445.It Va WITH_CLOUDWARE 446Set to a non-empty value to enable building virtual machine images 447for various cloud hosting providers. 448Requires 449.Va CLOUDWARE 450to also be set. 451.El 452.Pp 453Additionally, the 454.Va CLOUDWARE 455and 456.Va WITH_CLOUDWARE 457variables can be added to 458.Pa release.conf , 459and used in conjunction with 460.Pa release.sh . 461.Pp 462For a list of supported 463.Va CLOUDWARE 464values, run: 465.Bd -literal -offset indent 466cd /usr/src 467make -C release list-cloudware 468.Ed 469.Sh MAKEFILE TARGETS 470The release makefile 471.Pq Pa src/release/Makefile 472is fairly abstruse. 473Most developers will only be concerned with the 474.Cm release 475and 476.Cm install 477targets. 478.\" XXX: Some sort of introduction to this list? All the others have one. 479.Bl -tag -width ".Cm packagesystem" 480.It Cm release 481Meta-target to build all release media and distributions applicable to this 482platform. 483.It Cm install 484Copy all produced release media to 485.Pa ${DESTDIR} . 486.It Cm cdrom 487Builds installation CD-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 files called 493.Pa disc1.iso 494and 495.Pa bootonly.iso 496as its output. 497.It Cm dvdrom 498Builds installation DVD-ROM images. 499This may require the 500.Xr md 4 501(memory disk) device driver be present in the kernel 502(either by being compiled in or available as a module). 503This target produces the 504.Pa dvd1.iso 505file as its output. 506.It Cm memstick 507Builds an installation memory stick image named 508.Pa memstick.img . 509Not applicable on all platforms. 510Requires that the 511.Xr md 4 512.Pq memory disk 513device driver be present in the kernel 514.Pq either by being compiled in or available as a module . 515.It Cm mini-memstick 516Similar to 517.Cm memstick , 518with the exception that the installation distribution sets 519are not included. 520.It Cm ftp 521Creates a directory named 522.Pa ftp 523containing the distribution files used in network installations 524and suitable for upload to an FTP mirror. 525.It Cm vm-image 526Creates virtual machine disk images in various formats. 527The 528.Cm vm-image 529target requires the 530.Va WITH_VMIMAGES 531.Xr make 1 532envirionment variable to be set to a non-null value. 533.It Cm vm-cloudware 534Builds 535.Fx 536virtual machine images for various cloud hosting providers. 537See 538.Qq CLOUD HOSTING MACHINE IMAGES 539for implementation details. 540.It Cm list-cloudware 541Displays the list of valid 542.Va CLOUDWARE 543values. 544.It Cm list-vmtargets 545Displays the list of valid 546.Va VMFORMAT 547and 548.Va CLOUDWARE 549values. 550.El 551.Pp 552Major subtargets called by targets above: 553.Bl -tag -width ".Cm packagesystem" 554.It Cm packagesystem 555Generates all the distribution archives 556.Pq base, kernel, ports, doc 557applicable on this platform. 558.It Cm disc1 559Builds a bootable installation system containing all the distribution files 560packaged by the 561.Cm packagesystem 562target, and suitable for imaging by the 563.Cm cdrom , 564.Cm dvdrom 565and 566.Cm memstick 567targets. 568.It Cm reldoc 569Builds the release documentation. 570This includes the release notes, 571hardware guide, and installation instructions. 572Other documentation, such as the Handbook, 573is built during the 574.Cm base.txz 575target invoked by 576.Cm packagesystem . 577.El 578.Sh ENVIRONMENT 579Optional variables: 580.Bl -tag -width ".Ev TARGET_ARCH" 581.It Ev OSRELEASE 582Optional base name for generated media images 583.Pq e.g., FreeBSD-9.0-RC2-amd64 . 584Defaults to the output of 585.Ic `uname -s`-`uname -r`-`uname -p` 586within the chroot. 587.It Ev WORLDDIR 588Location of a directory containing the src tree. 589By default, the directory 590above the one containing the makefile 591.Pq Pa src . 592.It Ev PORTSDIR 593Location of a directory containing the ports tree. 594By default, 595.Pa /usr/ports . 596If it is unset or cannot be found, ports will not be included in the release. 597.It Ev DOCDIR 598Location of a directory containing the doc tree. 599By default, 600.Pa /usr/doc . 601If it is unset or cannot be found, most documentation will not be included in 602the release; see 603.Ev NODOC 604below. 605.It Ev NOPORTS 606If defined, the Ports Collection will be omitted from the release. 607.It Ev NOSRC 608If set, do not include system source code in the release. 609.It Ev NODOC 610If defined, the XML-based documentation from the 611.Fx 612Documentation Project will not be built. 613However, the 614.Dq doc 615distribution will still be created with the minimal documentation set 616provided in 617.Pa src/share/doc . 618.It Ev TARGET 619The target hardware platform. 620This is analogous to the 621.Dq Nm uname Fl m 622output. 623This is necessary to cross-build some target architectures. 624For example, cross-building for PC98 machines requires 625.Ev TARGET_ARCH Ns = Ns Li i386 626and 627.Ev TARGET Ns = Ns Li pc98 . 628If not set, 629.Ev TARGET 630defaults to the current hardware platform. 631.It Ev TARGET_ARCH 632The target machine processor architecture. 633This is analogous to the 634.Dq Nm uname Fl p 635output. 636Set this to cross-build for a different architecture. 637If not set, 638.Ev TARGET_ARCH 639defaults to the current machine architecture, unless 640.Ev TARGET 641is also set, in which case it defaults to the appropriate 642value for that platform. 643Typically, one only needs to set 644.Ev TARGET . 645.El 646.Sh FILES 647.Bl -tag -compact -width Pa 648.It Pa /usr/doc/Makefile 649.It Pa /usr/doc/share/mk/doc.project.mk 650.It Pa /usr/ports/Mk/bsd.port.mk 651.It Pa /usr/ports/Mk/bsd.sites.mk 652.It Pa /usr/share/examples/etc/make.conf 653.It Pa /usr/src/Makefile 654.It Pa /usr/src/Makefile.inc1 655.It Pa /usr/src/release/Makefile 656.It Pa /usr/src/release/Makefile.vm 657.It Pa /usr/src/release/release.sh 658.It Pa /usr/src/release/release.conf.sample 659.It Pa /usr/src/release/tools/*.conf 660.It Pa /usr/src/release/tools/vmimage.subr 661.El 662.Sh EXAMPLES 663The following sequence of commands can be used to build a 664.Dq "-CURRENT snapshot": 665.Bd -literal -offset indent 666cd /usr 667svn co svn://svn.freebsd.org/base/head src 668cd src 669make buildworld buildkernel 670cd release 671make release 672make install DESTDIR=/var/freebsd-snapshot 673.Ed 674.Pp 675After running these commands, all produced distribution files (tarballs 676for FTP, CD-ROM images, etc.) are available in the 677.Pa /var/freebsd-snapshot 678directory. 679.Pp 680The following sequence of commands can be used to build a 681.Dq "-CURRENT snapshot" 682in a clean environment, including ports and documentation: 683.Bd -literal -offset indent 684cd /usr/src/release 685sh release.sh 686.Ed 687.Pp 688Optionally, a configuration file can be used customize the release build, 689such as the subversion revision to use, the branch of the subversion tree for 690.Li src/ , 691.Li ports/ , 692and 693.Li doc/ . 694.Bd -literal -offset indent 695cd /usr/src/release 696sh release.sh -c $HOME/release.conf 697.Ed 698.Pp 699After running these commands, all prepared release files are available in the 700.Pa /scratch 701directory. 702The target directory can be changed by specifying the 703.Va CHROOTDIR 704variable in 705.Li release.conf . 706.Sh SEE ALSO 707.Xr cc 1 , 708.Xr install 1 , 709.Xr make 1 , 710.Xr svn 1 Pq Pa ports/devel/subversion , 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 http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 722.Re 723.Rs 724.%T "FreeBSD Release Engineering of Third Party Packages" 725.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 726.Re 727.Rs 728.%T "FreeBSD Developers' Handbook" 729.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 730.Re 731.Sh HISTORY 732.Fx 7331.x 734used a manual checklist, compiled by 735.An Rod Grimes , 736to produce a release. 737Apart from being incomplete, the list put a lot of specific demands on 738available file systems and was quite torturous to execute. 739.Pp 740As part of the 741.Fx 2.0 742release engineering effort, significant 743effort was spent getting 744.Pa src/release/Makefile 745into a shape where it could at least automate most of the tediousness 746of building a release in a sterile environment. 747.Pp 748For the 749.Fx 9.0 750release, 751.Pa src/release/Makefile 752was overhauled and the wrapper script 753.Pa src/release/generate-release.sh 754introduced to support the introduction of a new installer. 755.Pp 756For the 757.Fx 9.2 758release, 759.Pa src/release/release.sh 760was introduced to support per-build configuration files. 761.Pa src/release/release.sh 762is heavily based on the 763.Pa src/release/generate-release.sh 764script. 765.Pp 766At near 1000 revisions spread over multiple branches, the 767.Xr svn 1 768log of 769.Pa src/release/Makefile 770contains a vivid historical record of some 771of the hardships release engineers go through. 772.Sh AUTHORS 773.Pa src/release/Makefile 774was originally written by 775.An -nosplit 776.An Rod Grimes , 777.An Jordan Hubbard , 778and 779.An Poul-Henning Kamp . 780.Pp 781This manual page was originally written by 782.An Murray Stokely Aq Mt murray@FreeBSD.org . 783.Pp 784It was updated by 785.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org 786to include the 787.Fa generate-release.sh 788script used for the 789.Fx 9.0 790release cycle. 791.Pp 792It was later updated by 793.An Glen Barber Aq Mt gjb@FreeBSD.org 794to include the 795.Fa release.sh 796script used for the 797.Fx 9.2 798release cycle. 799