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.\"
| 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: head/share/man/man7/release.7 262499 2014-02-25 22:13:48Z gjb $
| 25.\" $FreeBSD: head/share/man/man7/release.7 262810 2014-03-05 23:17:53Z gjb $
|
26.\"
| 26.\"
|
27.Dd February 25, 2014
| 27.Dd March 5, 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.
| 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.
|
141.It Va SVNROOT 142The 143.Xr svn 1 144host used to check out the various trees. 145Defaults to 146.Pa svn://svn.FreeeBSD.org . 147.It Va SRCBRANCH 148The 149.Li src/ 150branch to use. 151Defaults to 152.Va head/@rHEAD . 153.It Va DOCBRANCH 154The 155.Li doc/ 156branch to use. 157Defaults to 158.Va head/@rHEAD . 159.It Va PORTBRANCH 160The 161.Li ports/ 162branch to use. 163Defaults to 164.Va head/@rHEAD . 165.It Va TARGET 166The target machine type for cross-building a release. 167.It Va TARGET_ARCH 168The target machine architecture for cross-building a release. 169.Pp 170For the supported list of 171.Va TARGET 172and 173.Va TARGET_ARCH 174combinations, consult the output of 175.Dq make targets 176as documented in 177.Xr build 7 . 178.It Va KERNEL 179The target kernel configuration to use. 180Defaults to 181.Va GENERIC . 182Multiple 183.Va KERNEL 184entries may be specified. 185.It Va MAKE_CONF 186The 187.Xr make.conf 5 188to use for the release build. 189Defaults to 190.Fa /dev/null 191to prevent polluting the release with local system changes. 192.It Va SRC_CONF 193The 194.Xr src.conf 5 195to use for the release build. 196Defaults to 197.Fa /dev/null 198to prevent polluting the release with local system changes. 199.It Va MAKE_FLAGS 200Additional flags to pass to 201.Xr make 1 . 202.It Va WORLD_FLAGS 203Additional flags to pass to 204.Xr make 1 205during the 206.Dq buildworld 207phase. 208Defaults to setting the number of 209.Xr make 1 210jobs 211.Pq Ar -j 212to the number of CPUs available on a SMP-capable system. 213.It Va KERNEL_FLAGS 214Additional flags to pass to 215.Xr make 1 216during the 217.Dq buildkernel 218phase. 219Defaults to setting the number of 220.Xr make 1 221jobs 222.Pq Ar -j 223to half the number of CPUs available on a SMP-capable system. 224.It Va NODOC 225Set to a non-empty value to skip the 226.Li doc/ 227tree checkout. 228When set, 229.Va NODOC 230will prevent the 231.Fa doc.txz 232distribution package from being created. 233.It Va NOPORTS 234Set to a non-empty value to skip the 235.Li ports/ 236tree checkout. 237When set, 238.Va NOPORTS 239will prevent the 240.Fa ports.txz 241distribution package from being created. 242Setting this also sets 243.Va NODOC . 244.It Va WITH_DVD 245Set to a non-empty value to include the 246.Cm dvdrom 247target. 248.It Va VCSCMD 249The command run to obtain the source trees. 250Defaults to 251.Qq Cm svn checkout .
| 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 VCSCMD 254The command run to obtain the source trees. 255Defaults to 256.Qq Cm svn checkout .
|
| 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.
|
252.El
| 269.El
|
| 270.Sh EMBEDDED BUILDS 271The following 272.Fa release.conf 273variables are relevant only to release builds for embedded systems: 274.Bl -tag -width Ev 275.It Va EMBEDDEDBUILD 276Set to a non-null value to enable functionality for embedded device 277release builds. 278.Pq This option is considered highly experimental. 279.Pp 280When set, 281.Va WITH_DVD 282is unset, and 283.Va NODOC 284is defined. 285Additionally, 286.Va XDEV 287and 288.Va XDEV_ARCH 289must also be defined. 290When the build environment is created, 291.Fa release.sh 292runs a separate build script located in an architecture-specific 293directory in 294.Pa src/release/${XDEV}/ . 295.It Va EMBEDDEDPORTS 296Set to the list of any ports that are required for the target device 297in the format of 298.Fa category/port . 299The 300.Fa devel/subversion 301port is built by default. 302.It Va CROCHETSRC 303Set to the source URL for the Crochet build tool. 304.It Va CROCHETBRANCH 305Set to the subversion branch from 306.Va ${CROCHETSRC} 307to use. 308Defaults to 309.Pa trunk . 310.It Va UBOOTSRC 311Set to the source URL of u-boot, if required. 312.It Va UBOOTBRANCH 313Set to the subversion branch from 314.Va ${UBOOTSRC} 315to use. 316Defaults to 317.Pa trunk . 318.It Va UBOOTDIR 319Set to the target directory within 320.Va ${CHROOTDIR} 321to check out 322.Va ${UBOOTSRC}/${UBOOTBRANCH} . 323.El
|
253.Sh MAKEFILE TARGETS 254The release makefile 255.Pq Pa src/release/Makefile 256is fairly abstruse. 257Most developers will only be concerned with the 258.Cm release 259and 260.Cm install 261targets. 262.\" XXX: Some sort of introduction to this list? All the others have one. 263.Bl -tag -width ".Cm packagesystem" 264.It Cm release 265Meta-target to build all release media and distributions applicable to this 266platform. 267.It Cm install 268Copy all produced release media to 269.Pa ${DESTDIR} . 270.It Cm cdrom 271Builds installation CD-ROM images. 272This may require the 273.Xr md 4 274(memory disk) device driver be present in the kernel 275(either by being compiled in or available as a module). 276This target produces files called 277.Pa disc1.iso 278and 279.Pa bootonly.iso 280as its output. 281.It Cm dvdrom 282Builds installation DVD-ROM images. 283This may require the 284.Xr md 4 285(memory disk) device driver be present in the kernel 286(either by being compiled in or available as a module). 287This target produces the 288.Pa dvd1.iso 289file as its output. 290.It Cm memstick 291Builds an installation memory stick image named 292.Pa memstick.img . 293Not applicable on all platforms. 294Requires that the 295.Xr md 4 296.Pq memory disk 297device driver be present in the kernel 298.Pq either by being compiled in or available as a module . 299.It Cm mini-memstick 300Similar to 301.Cm memstick , 302with the exception that the installation distribution sets 303are not included. 304.It Cm ftp 305Creates a directory named 306.Pa ftp 307containing the distribution files used in network installations 308and suitable for upload to an FTP mirror. 309.El 310.Pp 311Major subtargets called by targets above: 312.Bl -tag -width ".Cm packagesystem" 313.It Cm packagesystem 314Generates all the distribution archives 315.Pq base, kernel, ports, doc 316applicable on this platform. 317.It Cm system 318Builds a bootable installation system containing all the distribution files 319packaged by the 320.Cm packagesystem 321target, and suitable for imaging by the 322.Cm cdrom , 323.Cm dvdrom 324and 325.Cm memstick 326targets. 327.It Cm reldoc 328Builds the release documentation. 329This includes the release notes, 330hardware guide, and installation instructions. 331Other documentation, such as the Handbook, 332is built during the 333.Cm base.txz 334target invoked by 335.Cm packagesystem . 336.El 337.Sh ENVIRONMENT 338Optional variables: 339.Bl -tag -width ".Ev TARGET_ARCH" 340.It Ev OSRELEASE 341Optional base name for generated media images 342.Pq e.g., FreeBSD-9.0-RC2-amd64 . 343Defaults to the output of 344.Ic `uname -s`-`uname -r`-`uname -p` 345within the chroot. 346.It Ev WORLDDIR 347Location of a directory containing the src tree. 348By default, the directory 349above the one containing the makefile 350.Pq Pa src . 351.It Ev PORTSDIR 352Location of a directory containing the ports tree. 353By default, 354.Pa /usr/ports . 355If it is unset or cannot be found, ports will not be included in the release. 356.It Ev DOCDIR 357Location of a directory containing the doc tree. 358By default, 359.Pa /usr/doc . 360If it is unset or cannot be found, most documentation will not be included in 361the release; see 362.Ev NODOC 363below. 364.It Ev NOPORTS 365If defined, the Ports Collection will be omitted from the release. 366.It Ev NOSRC 367If set, do not include system source code in the release. 368.It Ev NODOC 369If defined, the XML-based documentation from the 370.Fx 371Documentation Project will not be built. 372However, the 373.Dq doc 374distribution will still be created with the minimal documentation set 375provided in 376.Pa src/share/doc . 377.It Ev TARGET 378The target hardware platform. 379This is analogous to the 380.Dq Nm uname Fl m 381output. 382This is necessary to cross-build some target architectures. 383For example, cross-building for PC98 machines requires 384.Ev TARGET_ARCH Ns = Ns Li i386 385and 386.Ev TARGET Ns = Ns Li pc98 . 387If not set, 388.Ev TARGET 389defaults to the current hardware platform. 390.It Ev TARGET_ARCH 391The target machine processor architecture. 392This is analogous to the 393.Dq Nm uname Fl p 394output. 395Set this to cross-build for a different architecture. 396If not set, 397.Ev TARGET_ARCH 398defaults to the current machine architecture, unless 399.Ev TARGET 400is also set, in which case it defaults to the appropriate 401value for that platform. 402Typically, one only needs to set 403.Ev TARGET . 404.El 405.Sh FILES 406.Bl -tag -compact -width Pa 407.It Pa /usr/doc/Makefile 408.It Pa /usr/doc/share/mk/doc.project.mk 409.It Pa /usr/ports/Mk/bsd.port.mk 410.It Pa /usr/ports/Mk/bsd.sites.mk 411.It Pa /usr/share/examples/etc/make.conf 412.It Pa /usr/src/Makefile 413.It Pa /usr/src/Makefile.inc1 414.It Pa /usr/src/release/Makefile 415.It Pa /usr/src/release/release.sh 416.It Pa /usr/src/release/release.conf.sample 417.El 418.Sh EXAMPLES 419The following sequence of commands can be used to build a 420.Dq "-CURRENT snapshot": 421.Bd -literal -offset indent 422cd /usr 423svn co svn://svn.freebsd.org/base/head src 424cd src 425make buildworld buildkernel 426cd release 427make release 428make install DESTDIR=/var/freebsd-snapshot 429.Ed 430.Pp 431After running these commands, all produced distribution files (tarballs 432for FTP, CD-ROM images, etc.) are available in the 433.Pa /var/freebsd-snapshot 434directory. 435.Pp 436The following sequence of commands can be used to build a 437.Dq "-CURRENT snapshot" 438in a clean environment, including ports and documentation: 439.Bd -literal -offset indent 440cd /usr/src/release 441sh release.sh 442.Ed 443.Pp 444Optionally, a configuration file can be used customize the release build, 445such as the subversion revision to use, the branch of the subversion tree for 446.Li src/ , 447.Li ports/ , 448and 449.Li doc/ . 450.Bd -literal -offset indent 451cd /usr/src/release 452sh release.sh -c $HOME/release.conf 453.Ed 454.Pp 455After running these commands, all prepared release files are available in the 456.Pa /scratch 457directory. 458The target directory can be changed by specifying the 459.Va CHROOTDIR 460variable in 461.Li release.conf . 462.Sh SEE ALSO 463.Xr cc 1 , 464.Xr install 1 , 465.Xr make 1 , 466.Xr svn 1 Pq Pa ports/devel/subversion , 467.Xr uname 1 , 468.Xr md 4 , 469.Xr make.conf 5 , 470.Xr build 7 , 471.Xr ports 7 , 472.Xr chroot 8 , 473.Xr mtree 8 , 474.Xr sysctl 8 475.Rs 476.%T "FreeBSD Release Engineering" 477.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 478.Re 479.Rs 480.%T "FreeBSD Release Engineering of Third Party Packages" 481.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 482.Re 483.Rs 484.%T "FreeBSD Developers' Handbook" 485.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 486.Re 487.Sh HISTORY 488.Fx 4891.x 490used a manual checklist, compiled by 491.An Rod Grimes , 492to produce a release. 493Apart from being incomplete, the list put a lot of specific demands on 494available file systems and was quite torturous to execute. 495.Pp 496As part of the 497.Fx 2.0 498release engineering effort, significant 499effort was spent getting 500.Pa src/release/Makefile 501into a shape where it could at least automate most of the tediousness 502of building a release in a sterile environment. 503.Pp 504For the 505.Fx 9.0 506release, 507.Pa src/release/Makefile 508was overhauled and the wrapper script 509.Pa src/release/generate-release.sh 510introduced to support the introduction of a new installer. 511.Pp 512For the 513.Fx 9.2 514release, 515.Pa src/release/release.sh 516was introduced to support per-build configuration files. 517.Pa src/release/release.sh 518is heavily based on the 519.Pa src/release/generate-release.sh 520script. 521.Pp 522At near 1000 revisions spread over multiple branches, the 523.Xr svn 1 524log of 525.Pa src/release/Makefile 526contains a vivid historical record of some 527of the hardships release engineers go through. 528.Sh AUTHORS 529.Pa src/release/Makefile 530was originally written by 531.An -nosplit 532.An Rod Grimes , 533.An Jordan Hubbard , 534and 535.An Poul-Henning Kamp . 536.Pp 537This manual page was originally written by 538.An Murray Stokely Aq murray@FreeBSD.org . 539.Pp 540It was updated by 541.An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org 542to include the 543.Fa generate-release.sh 544script used for the 545.Fx 9.0 546release cycle. 547.Pp 548It was later updated by 549.An Glen Barber Aq gjb@FreeBSD.org 550to include the 551.Fa release.sh 552script used for the 553.Fx 9.2 554release cycle.
| 324.Sh MAKEFILE TARGETS 325The release makefile 326.Pq Pa src/release/Makefile 327is fairly abstruse. 328Most developers will only be concerned with the 329.Cm release 330and 331.Cm install 332targets. 333.\" XXX: Some sort of introduction to this list? All the others have one. 334.Bl -tag -width ".Cm packagesystem" 335.It Cm release 336Meta-target to build all release media and distributions applicable to this 337platform. 338.It Cm install 339Copy all produced release media to 340.Pa ${DESTDIR} . 341.It Cm cdrom 342Builds installation CD-ROM images. 343This may require the 344.Xr md 4 345(memory disk) device driver be present in the kernel 346(either by being compiled in or available as a module). 347This target produces files called 348.Pa disc1.iso 349and 350.Pa bootonly.iso 351as its output. 352.It Cm dvdrom 353Builds installation DVD-ROM images. 354This may require the 355.Xr md 4 356(memory disk) device driver be present in the kernel 357(either by being compiled in or available as a module). 358This target produces the 359.Pa dvd1.iso 360file as its output. 361.It Cm memstick 362Builds an installation memory stick image named 363.Pa memstick.img . 364Not applicable on all platforms. 365Requires that the 366.Xr md 4 367.Pq memory disk 368device driver be present in the kernel 369.Pq either by being compiled in or available as a module . 370.It Cm mini-memstick 371Similar to 372.Cm memstick , 373with the exception that the installation distribution sets 374are not included. 375.It Cm ftp 376Creates a directory named 377.Pa ftp 378containing the distribution files used in network installations 379and suitable for upload to an FTP mirror. 380.El 381.Pp 382Major subtargets called by targets above: 383.Bl -tag -width ".Cm packagesystem" 384.It Cm packagesystem 385Generates all the distribution archives 386.Pq base, kernel, ports, doc 387applicable on this platform. 388.It Cm system 389Builds a bootable installation system containing all the distribution files 390packaged by the 391.Cm packagesystem 392target, and suitable for imaging by the 393.Cm cdrom , 394.Cm dvdrom 395and 396.Cm memstick 397targets. 398.It Cm reldoc 399Builds the release documentation. 400This includes the release notes, 401hardware guide, and installation instructions. 402Other documentation, such as the Handbook, 403is built during the 404.Cm base.txz 405target invoked by 406.Cm packagesystem . 407.El 408.Sh ENVIRONMENT 409Optional variables: 410.Bl -tag -width ".Ev TARGET_ARCH" 411.It Ev OSRELEASE 412Optional base name for generated media images 413.Pq e.g., FreeBSD-9.0-RC2-amd64 . 414Defaults to the output of 415.Ic `uname -s`-`uname -r`-`uname -p` 416within the chroot. 417.It Ev WORLDDIR 418Location of a directory containing the src tree. 419By default, the directory 420above the one containing the makefile 421.Pq Pa src . 422.It Ev PORTSDIR 423Location of a directory containing the ports tree. 424By default, 425.Pa /usr/ports . 426If it is unset or cannot be found, ports will not be included in the release. 427.It Ev DOCDIR 428Location of a directory containing the doc tree. 429By default, 430.Pa /usr/doc . 431If it is unset or cannot be found, most documentation will not be included in 432the release; see 433.Ev NODOC 434below. 435.It Ev NOPORTS 436If defined, the Ports Collection will be omitted from the release. 437.It Ev NOSRC 438If set, do not include system source code in the release. 439.It Ev NODOC 440If defined, the XML-based documentation from the 441.Fx 442Documentation Project will not be built. 443However, the 444.Dq doc 445distribution will still be created with the minimal documentation set 446provided in 447.Pa src/share/doc . 448.It Ev TARGET 449The target hardware platform. 450This is analogous to the 451.Dq Nm uname Fl m 452output. 453This is necessary to cross-build some target architectures. 454For example, cross-building for PC98 machines requires 455.Ev TARGET_ARCH Ns = Ns Li i386 456and 457.Ev TARGET Ns = Ns Li pc98 . 458If not set, 459.Ev TARGET 460defaults to the current hardware platform. 461.It Ev TARGET_ARCH 462The target machine processor architecture. 463This is analogous to the 464.Dq Nm uname Fl p 465output. 466Set this to cross-build for a different architecture. 467If not set, 468.Ev TARGET_ARCH 469defaults to the current machine architecture, unless 470.Ev TARGET 471is also set, in which case it defaults to the appropriate 472value for that platform. 473Typically, one only needs to set 474.Ev TARGET . 475.El 476.Sh FILES 477.Bl -tag -compact -width Pa 478.It Pa /usr/doc/Makefile 479.It Pa /usr/doc/share/mk/doc.project.mk 480.It Pa /usr/ports/Mk/bsd.port.mk 481.It Pa /usr/ports/Mk/bsd.sites.mk 482.It Pa /usr/share/examples/etc/make.conf 483.It Pa /usr/src/Makefile 484.It Pa /usr/src/Makefile.inc1 485.It Pa /usr/src/release/Makefile 486.It Pa /usr/src/release/release.sh 487.It Pa /usr/src/release/release.conf.sample 488.El 489.Sh EXAMPLES 490The following sequence of commands can be used to build a 491.Dq "-CURRENT snapshot": 492.Bd -literal -offset indent 493cd /usr 494svn co svn://svn.freebsd.org/base/head src 495cd src 496make buildworld buildkernel 497cd release 498make release 499make install DESTDIR=/var/freebsd-snapshot 500.Ed 501.Pp 502After running these commands, all produced distribution files (tarballs 503for FTP, CD-ROM images, etc.) are available in the 504.Pa /var/freebsd-snapshot 505directory. 506.Pp 507The following sequence of commands can be used to build a 508.Dq "-CURRENT snapshot" 509in a clean environment, including ports and documentation: 510.Bd -literal -offset indent 511cd /usr/src/release 512sh release.sh 513.Ed 514.Pp 515Optionally, a configuration file can be used customize the release build, 516such as the subversion revision to use, the branch of the subversion tree for 517.Li src/ , 518.Li ports/ , 519and 520.Li doc/ . 521.Bd -literal -offset indent 522cd /usr/src/release 523sh release.sh -c $HOME/release.conf 524.Ed 525.Pp 526After running these commands, all prepared release files are available in the 527.Pa /scratch 528directory. 529The target directory can be changed by specifying the 530.Va CHROOTDIR 531variable in 532.Li release.conf . 533.Sh SEE ALSO 534.Xr cc 1 , 535.Xr install 1 , 536.Xr make 1 , 537.Xr svn 1 Pq Pa ports/devel/subversion , 538.Xr uname 1 , 539.Xr md 4 , 540.Xr make.conf 5 , 541.Xr build 7 , 542.Xr ports 7 , 543.Xr chroot 8 , 544.Xr mtree 8 , 545.Xr sysctl 8 546.Rs 547.%T "FreeBSD Release Engineering" 548.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 549.Re 550.Rs 551.%T "FreeBSD Release Engineering of Third Party Packages" 552.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 553.Re 554.Rs 555.%T "FreeBSD Developers' Handbook" 556.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 557.Re 558.Sh HISTORY 559.Fx 5601.x 561used a manual checklist, compiled by 562.An Rod Grimes , 563to produce a release. 564Apart from being incomplete, the list put a lot of specific demands on 565available file systems and was quite torturous to execute. 566.Pp 567As part of the 568.Fx 2.0 569release engineering effort, significant 570effort was spent getting 571.Pa src/release/Makefile 572into a shape where it could at least automate most of the tediousness 573of building a release in a sterile environment. 574.Pp 575For the 576.Fx 9.0 577release, 578.Pa src/release/Makefile 579was overhauled and the wrapper script 580.Pa src/release/generate-release.sh 581introduced to support the introduction of a new installer. 582.Pp 583For the 584.Fx 9.2 585release, 586.Pa src/release/release.sh 587was introduced to support per-build configuration files. 588.Pa src/release/release.sh 589is heavily based on the 590.Pa src/release/generate-release.sh 591script. 592.Pp 593At near 1000 revisions spread over multiple branches, the 594.Xr svn 1 595log of 596.Pa src/release/Makefile 597contains a vivid historical record of some 598of the hardships release engineers go through. 599.Sh AUTHORS 600.Pa src/release/Makefile 601was originally written by 602.An -nosplit 603.An Rod Grimes , 604.An Jordan Hubbard , 605and 606.An Poul-Henning Kamp . 607.Pp 608This manual page was originally written by 609.An Murray Stokely Aq murray@FreeBSD.org . 610.Pp 611It was updated by 612.An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org 613to include the 614.Fa generate-release.sh 615script used for the 616.Fx 9.0 617release cycle. 618.Pp 619It was later updated by 620.An Glen Barber Aq gjb@FreeBSD.org 621to include the 622.Fa release.sh 623script used for the 624.Fx 9.2 625release cycle.
|