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 2, 2014 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 VCSCMD 260The command run to obtain the source trees. 261Defaults to 262.Qq Cm svn checkout . 263.It Va CHROOTBUILD_SKIP 264If defined, the 265.Li buildworld , 266.Li installworld , 267and 268.Li distribution 269stages of the 270.Xr chroot 8 271build environment setup are skipped. 272This is intended solely for cases where the 273.Xr chroot 8 274userland are provided by alternate means. 275.It Va SRC_UPDATE_SKIP 276Set to a non-empty value to prevent checkout or update of 277.Fa /usr/src 278within the 279.Xr chroot 8 . 280This is intended for use only when 281.Fa /usr/src 282is expected to exist by alternative means. 283.It Va DOC_UPDATE_SKIP 284Set to a non-empty value to prevent checkout or update of 285.Fa /usr/doc 286within the 287.Xr chroot 8 . 288This is intended for use only when 289.Fa /usr/doc 290is expected to exist by alternative means. 291.It Va PORTS_UPDATE_SKIP 292Set to a non-empty value to prevent checkout or update of 293.Fa /usr/ports 294within the 295.Xr chroot 8 . 296This is intended for use only when 297.Fa /usr/ports 298is expected to exist by alternative means. 299.El 300.Sh EMBEDDED BUILDS 301The following 302.Fa release.conf 303variables are relevant only to release builds for embedded systems: 304.Bl -tag -width Ev 305.It Va EMBEDDEDBUILD 306Set to a non-null value to enable functionality for embedded device 307release builds. 308.Pq This option is considered highly experimental. 309.Pp 310When set, 311.Va WITH_DVD 312is unset, and 313.Va NODOC 314is defined. 315Additionally, 316.Va XDEV 317and 318.Va XDEV_ARCH 319must also be defined. 320When the build environment is created, 321.Fa release.sh 322runs a separate build script located in an architecture-specific 323directory in 324.Pa src/release/${XDEV}/ . 325.It Va EMBEDDEDPORTS 326Set to the list of any ports that are required for the target device 327in the format of 328.Fa category/port . 329The 330.Fa devel/subversion 331port is built by default. 332.It Va CROCHETSRC 333Set to the source URL for the Crochet build tool. 334.It Va CROCHETBRANCH 335Set to the subversion branch from 336.Va ${CROCHETSRC} 337to use. 338Defaults to 339.Pa trunk . 340.It Va UBOOTSRC 341Set to the source URL of u-boot, if required. 342.It Va UBOOTBRANCH 343Set to the subversion branch from 344.Va ${UBOOTSRC} 345to use. 346Defaults to 347.Pa trunk . 348.It Va UBOOTDIR 349Set to the target directory within 350.Va ${CHROOTDIR} 351to check out 352.Va ${UBOOTSRC}/${UBOOTBRANCH} . 353.El 354.Sh VIRTUAL MACHINE DISK IMAGES 355The following 356.Fa release.conf 357variables are relevant only to virtual machine disk image builds: 358.Bl -tag -width Ev 359.It Va WITH_VMIMAGES 360Set to a non-null value to build virtual machine disk images as part 361of the release build. 362.Va WITH_VMIMAGES 363may also be specified as an envirionment variable passed to 364.Xr make 1 . 365.Pp 366The option requires 367.Xr mkimg 1 368version 20140927 or later. 369.It Va WITH_COMPRESSED_VMIMAGES 370Set to a non-null value to compress the virtual machine disk images with 371.Xr xz 1 372as part of the 373.Cm install 374.Xr make 1 375target. 376Note that compressing virtual machine disk images may take a very long 377time on some systems. 378.It Va VMBASE 379Set to change the name of the resulting virtual machine disk image file. 380The default value is 381.Va vm . 382.It Va VMSIZE 383Set to change the size of the virtual machine disk capacity. 384The default value is 385.Va 20G . 386See 387.Xr truncate 1 388for valid values. 389.Pp 390Virtual machine disk images are, by default, created as sparse images. 391When 392.Va WITH_COMPRESSED_VMIMAGES 393is used, the resulting files compressed with 394.Xr xz 1 395compress to roughly the same size, regardless of the specified disk image 396size. 397.It Va VMFORMATS 398Set to the target virtual disk image format(s) to create. 399By default, the 400.Va vhdf , Va vmdk , Va qcow2 , 401and 402.Va raw 403formats are created. 404See 405.Xr mkimg 1 406for valid format values 407.Pq requires version 20140927 or later . 408.El 409.Sh MAKEFILE TARGETS 410The release makefile 411.Pq Pa src/release/Makefile 412is fairly abstruse. 413Most developers will only be concerned with the 414.Cm release 415and 416.Cm install 417targets. 418.\" XXX: Some sort of introduction to this list? All the others have one. 419.Bl -tag -width ".Cm packagesystem" 420.It Cm release 421Meta-target to build all release media and distributions applicable to this 422platform. 423.It Cm install 424Copy all produced release media to 425.Pa ${DESTDIR} . 426.It Cm cdrom 427Builds installation CD-ROM images. 428This may require the 429.Xr md 4 430(memory disk) device driver be present in the kernel 431(either by being compiled in or available as a module). 432This target produces files called 433.Pa disc1.iso 434and 435.Pa bootonly.iso 436as its output. 437.It Cm dvdrom 438Builds installation DVD-ROM images. 439This may require the 440.Xr md 4 441(memory disk) device driver be present in the kernel 442(either by being compiled in or available as a module). 443This target produces the 444.Pa dvd1.iso 445file as its output. 446.It Cm memstick 447Builds an installation memory stick image named 448.Pa memstick.img . 449Not applicable on all platforms. 450Requires that the 451.Xr md 4 452.Pq memory disk 453device driver be present in the kernel 454.Pq either by being compiled in or available as a module . 455.It Cm mini-memstick 456Similar to 457.Cm memstick , 458with the exception that the installation distribution sets 459are not included. 460.It Cm ftp 461Creates a directory named 462.Pa ftp 463containing the distribution files used in network installations 464and suitable for upload to an FTP mirror. 465.It Cm vm-image 466Creates virtual machine disk images in various formats. 467The 468.Cm vm-image 469target requires the 470.Va WITH_VMIMAGES 471.Xr make 1 472envirionment variable to be set to a non-null value. 473.El 474.Pp 475Major subtargets called by targets above: 476.Bl -tag -width ".Cm packagesystem" 477.It Cm packagesystem 478Generates all the distribution archives 479.Pq base, kernel, ports, doc 480applicable on this platform. 481.It Cm system 482Builds a bootable installation system containing all the distribution files 483packaged by the 484.Cm packagesystem 485target, and suitable for imaging by the 486.Cm cdrom , 487.Cm dvdrom 488and 489.Cm memstick 490targets. 491.It Cm reldoc 492Builds the release documentation. 493This includes the release notes, 494hardware guide, and installation instructions. 495Other documentation, such as the Handbook, 496is built during the 497.Cm base.txz 498target invoked by 499.Cm packagesystem . 500.El 501.Sh ENVIRONMENT 502Optional variables: 503.Bl -tag -width ".Ev TARGET_ARCH" 504.It Ev OSRELEASE 505Optional base name for generated media images 506.Pq e.g., FreeBSD-9.0-RC2-amd64 . 507Defaults to the output of 508.Ic `uname -s`-`uname -r`-`uname -p` 509within the chroot. 510.It Ev WORLDDIR 511Location of a directory containing the src tree. 512By default, the directory 513above the one containing the makefile 514.Pq Pa src . 515.It Ev PORTSDIR 516Location of a directory containing the ports tree. 517By default, 518.Pa /usr/ports . 519If it is unset or cannot be found, ports will not be included in the release. 520.It Ev DOCDIR 521Location of a directory containing the doc tree. 522By default, 523.Pa /usr/doc . 524If it is unset or cannot be found, most documentation will not be included in 525the release; see 526.Ev NODOC 527below. 528.It Ev NOPORTS 529If defined, the Ports Collection will be omitted from the release. 530.It Ev NOSRC 531If set, do not include system source code in the release. 532.It Ev NODOC 533If defined, the XML-based documentation from the 534.Fx 535Documentation Project will not be built. 536However, the 537.Dq doc 538distribution will still be created with the minimal documentation set 539provided in 540.Pa src/share/doc . 541.It Ev TARGET 542The target hardware platform. 543This is analogous to the 544.Dq Nm uname Fl m 545output. 546This is necessary to cross-build some target architectures. 547For example, cross-building for PC98 machines requires 548.Ev TARGET_ARCH Ns = Ns Li i386 549and 550.Ev TARGET Ns = Ns Li pc98 . 551If not set, 552.Ev TARGET 553defaults to the current hardware platform. 554.It Ev TARGET_ARCH 555The target machine processor architecture. 556This is analogous to the 557.Dq Nm uname Fl p 558output. 559Set this to cross-build for a different architecture. 560If not set, 561.Ev TARGET_ARCH 562defaults to the current machine architecture, unless 563.Ev TARGET 564is also set, in which case it defaults to the appropriate 565value for that platform. 566Typically, one only needs to set 567.Ev TARGET . 568.El 569.Sh FILES 570.Bl -tag -compact -width Pa 571.It Pa /usr/doc/Makefile 572.It Pa /usr/doc/share/mk/doc.project.mk 573.It Pa /usr/ports/Mk/bsd.port.mk 574.It Pa /usr/ports/Mk/bsd.sites.mk 575.It Pa /usr/share/examples/etc/make.conf 576.It Pa /usr/src/Makefile 577.It Pa /usr/src/Makefile.inc1 578.It Pa /usr/src/release/Makefile 579.It Pa /usr/src/release/release.sh 580.It Pa /usr/src/release/release.conf.sample 581.El 582.Sh EXAMPLES 583The following sequence of commands can be used to build a 584.Dq "-CURRENT snapshot": 585.Bd -literal -offset indent 586cd /usr 587svn co svn://svn.freebsd.org/base/head src 588cd src 589make buildworld buildkernel 590cd release 591make release 592make install DESTDIR=/var/freebsd-snapshot 593.Ed 594.Pp 595After running these commands, all produced distribution files (tarballs 596for FTP, CD-ROM images, etc.) are available in the 597.Pa /var/freebsd-snapshot 598directory. 599.Pp 600The following sequence of commands can be used to build a 601.Dq "-CURRENT snapshot" 602in a clean environment, including ports and documentation: 603.Bd -literal -offset indent 604cd /usr/src/release 605sh release.sh 606.Ed 607.Pp 608Optionally, a configuration file can be used customize the release build, 609such as the subversion revision to use, the branch of the subversion tree for 610.Li src/ , 611.Li ports/ , 612and 613.Li doc/ . 614.Bd -literal -offset indent 615cd /usr/src/release 616sh release.sh -c $HOME/release.conf 617.Ed 618.Pp 619After running these commands, all prepared release files are available in the 620.Pa /scratch 621directory. 622The target directory can be changed by specifying the 623.Va CHROOTDIR 624variable in 625.Li release.conf . 626.Sh SEE ALSO 627.Xr cc 1 , 628.Xr install 1 , 629.Xr make 1 , 630.Xr svn 1 Pq Pa ports/devel/subversion , 631.Xr uname 1 , 632.Xr md 4 , 633.Xr make.conf 5 , 634.Xr build 7 , 635.Xr ports 7 , 636.Xr chroot 8 , 637.Xr mtree 8 , 638.Xr sysctl 8 639.Rs 640.%T "FreeBSD Release Engineering" 641.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 642.Re 643.Rs 644.%T "FreeBSD Release Engineering of Third Party Packages" 645.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 646.Re 647.Rs 648.%T "FreeBSD Developers' Handbook" 649.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 650.Re 651.Sh HISTORY 652.Fx 6531.x 654used a manual checklist, compiled by 655.An Rod Grimes , 656to produce a release. 657Apart from being incomplete, the list put a lot of specific demands on 658available file systems and was quite torturous to execute. 659.Pp 660As part of the 661.Fx 2.0 662release engineering effort, significant 663effort was spent getting 664.Pa src/release/Makefile 665into a shape where it could at least automate most of the tediousness 666of building a release in a sterile environment. 667.Pp 668For the 669.Fx 9.0 670release, 671.Pa src/release/Makefile 672was overhauled and the wrapper script 673.Pa src/release/generate-release.sh 674introduced to support the introduction of a new installer. 675.Pp 676For the 677.Fx 9.2 678release, 679.Pa src/release/release.sh 680was introduced to support per-build configuration files. 681.Pa src/release/release.sh 682is heavily based on the 683.Pa src/release/generate-release.sh 684script. 685.Pp 686At near 1000 revisions spread over multiple branches, the 687.Xr svn 1 688log of 689.Pa src/release/Makefile 690contains a vivid historical record of some 691of the hardships release engineers go through. 692.Sh AUTHORS 693.Pa src/release/Makefile 694was originally written by 695.An -nosplit 696.An Rod Grimes , 697.An Jordan Hubbard , 698and 699.An Poul-Henning Kamp . 700.Pp 701This manual page was originally written by 702.An Murray Stokely Aq Mt murray@FreeBSD.org . 703.Pp 704It was updated by 705.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org 706to include the 707.Fa generate-release.sh 708script used for the 709.Fx 9.0 710release cycle. 711.Pp 712It was later updated by 713.An Glen Barber Aq Mt gjb@FreeBSD.org 714to include the 715.Fa release.sh 716script used for the 717.Fx 9.2 718release cycle. 719