| release.7 (246283) | release.7 (254224) |
|---|---|
| 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. --- 8 unchanged lines hidden (view full) --- 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. --- 8 unchanged lines hidden (view full) --- 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 246283 2013-02-03 10:26:24Z hrs $ | 25.\" $FreeBSD: head/share/man/man7/release.7 254224 2013-08-11 18:57:27Z gjb $ |
| 26.\" | 26.\" |
| 27.Dd February 3, 2013 | 27.Dd August 11, 2013 |
| 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 --- 9 unchanged lines hidden (view full) --- 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 | 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 --- 9 unchanged lines hidden (view full) --- 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. For this purpose, a script 54.Pq Pa src/release/generate-release.sh | 53trees. 54For this purpose, a script 55.Pq Pa src/release/release.sh |
| 55is provided to automate these checkouts and then execute 56.Dq Li "make release" 57in a clean 58.Xr chroot 8 . 59.Pp 60Before attempting to build a release, the user is expected to be 61familiar with the contents of 62.Xr build 7 , 63and should have experience upgrading systems from source. 64.Pp 65The release build process requires that 66.Pa /usr/obj 67be populated with the output of 68.Dq Li "make buildworld" 69and 70.Dq Li "make buildkernel" . 71This is necessary to provide the object files for the release or, when 72using | 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 |
| 73.Pa generate-release.sh , | 74.Pa release.sh , |
| 74so that the object files for a complete system can be installed into a clean 75.Xr chroot 8 | 75so that the object files for a complete system can be installed into a clean 76.Xr chroot 8 |
| 76environment. In this second case, the built world must be capable of running 77on the build system (i.e. it must be for the same architecture and be 78compatible with the installed kernel). | 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 |
| 79The release procedure on some architectures may also require that the 80.Xr md 4 81(memory disk) device driver be present in the kernel | 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 |
| 82(either by being compiled in or available as a module). | 92.Pq either by being compiled in or available as a module . |
| 83.Pp 84This document does not cover source code management, quality 85assurance, or other aspects of the release engineering process. 86.Sh CLEAN RELEASE GENERATION | 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 |
| 87Official releases of FreeBSD are produced in a totally clean environment to | 97Official releases of 98.Fx 99are produced in a totally clean environment to |
| 88ensure consistency between the versions of the src, ports, and doc trees | 100ensure consistency between the versions of the src, ports, and doc trees |
| 89and to avoid contamination from the host system (e.g. local patches, changes | 101and to avoid contamination from the host system 102.Po such as local patches, changes |
| 90to 91.Xr make.conf 5 , | 103to 104.Xr make.conf 5 , |
| 92etc.). This is accomplished using the wrapper script 93.Pa src/release/generate-release.sh . | 105etc. 106.Pc . 107This is accomplished using the wrapper script 108.Pa src/release/release.sh . |
| 94.Pp | 109.Pp |
| 95.Ic generate-release.sh 96svn-branch scratch-dir | 110.Ic release.sh 111.Op Fl c Ar release.conf |
| 97.Pp | 112.Pp |
| 98.Ic generate-release.sh 99calls | 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 |
| 100.Dq Li "make installworld" 101to generate a 102.Xr chroot 8 | 124.Dq Li "make installworld" 125to generate a 126.Xr chroot 8 |
| 103environment in 104.Ar scratch-dir . 105It then checks out the src tree specified by 106.Ar svn-branch 107using 108.Xr svn 1 . 109Once the various source trees have been obtained, it executes | 127environment. 128Next, |
| 110.Dq Li "make release" | 129.Dq Li "make release" |
| 111within the | 130is run within the |
| 112.Xr chroot 8 113environment and places the result in | 131.Xr chroot 8 132environment and places the result in |
| 114.Pa $scratch-dir/R . 115Note that because this uses a chroot, it cannot be used to cross-build 116.Fx 117release media. | 133.Pa $CHROOTDIR/R . |
| 118.Pp | 134.Pp |
| 119Optional environment variables: 120.Bl -tag -width ".Cm WORLD_FLAGS" 121.It Ev WORLD_FLAGS 122This environment variable can be set to pass flags (e.g. -j) to 123.Xr make 1 124when invoked to build a world by the script. 125.It Ev KERNEL_FLAGS 126This environment variable can be set to pass flags (e.g. -j) to 127.Xr make 1 128when invoked to build a kernel by the script. 129.It Ev SVNROOTBASE 130The base part of URL of the FreeBSD SVN repositories. | 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 SVNROOT 142The 143.Xr svn 1 144host used to check out the various trees. |
| 131Defaults to | 145Defaults to |
| 132.Pa svn://svn.freebsd.org . 133.It Ev SVNROOTSRC 134The URL of the FreeBSD SVN source repository. | 146.Pa svn://svn.FreeeBSD.org . 147.It Va SRCBRANCH 148The 149.Li src/ 150branch to use. |
| 135Defaults to | 151Defaults to |
| 136.Pa ${SVNROOTBASE}/base . 137.It Ev SVNROOTDOC 138The URL of the FreeBSD SVN doc repository. | 152.Va head/ . 153.It Va DOCBRANCH 154The 155.Li doc/ 156branch to use. |
| 139Defaults to | 157Defaults to |
| 140.Pa ${SVNROOTBASE}/doc . 141.It Ev SVNROOTPORTS 142The URL of the FreeBSD SVN ports repository. | 158.Va head/ . 159.It Va PORTBRANCH 160The 161.Li ports/ 162branch to use. |
| 143Defaults to | 163Defaults to |
| 144.Pa ${SVNROOTBASE}/ports . 145.It Ev BRANCHDOC 146The branch name of the FreeBSD SVN doc repository. | 164.Va head/ . 165.It Va SRCREVISION 166The revision of the 167.Li src/ 168tree to use. 169Defaults to the current top of tree revision. 170.It Va DOCREVISION 171The revision of the 172.Li doc/ 173tree to use. 174Defaults to the current top of tree revision. 175.It Va PORTREVISION 176The revision of the 177.Li ports/ 178tree to use. 179Defaults to the current top of tree revision. 180.It Va TARGET 181The target machine type for the release. 182Defaults to the current machine type. 183.It Va TARGET_ARCH 184The target machine architecture for the release. 185Defaults to the value of 186.Va TARGET . 187.Pp 188For the supported list of 189.Va TARGET 190and 191.Va TARGET_ARCH 192combinations, consult the output of 193.Dq make targets 194as documented in 195.Xr build 7 . 196.It Va KERNEL 197The target kernel configuration to use. |
| 147Defaults to | 198Defaults to |
| 148.Pa head . 149.It Ev BRANCHPORTS 150The branch name of the FreeBSD SVN ports repository. | 199.Va GENERIC . 200Multiple 201.Va KERNEL 202entries may be specified. 203.It Va MAKE_CONF 204The 205.Xr make.conf 5 206to use for the release build. |
| 151Defaults to | 207Defaults to |
| 152.Pa head . | 208.Fa /dev/null 209to prevent polluting the release with local system changes. 210.It Va SRC_CONF 211The 212.Xr src.conf 5 213to use for the release build. 214Defaults to 215.Fa /dev/null 216to prevent polluting the release with local system changes. 217.It Va MAKE_FLAGS 218Additional flags to pass to 219.Xr make 1 . 220.It Va WORLD_FLAGS 221Additional flags to pass to 222.Xr make 1 223during the 224.Dq buildworld 225phase. 226Defaults to setting the number of 227.Xr make 1 228jobs 229.Pq Ar -j 230to the number of CPUs available on the system. 231.It Va KERNEL_FLAGS 232Additional flags to pass to 233.Xr make 1 234during the 235.Dq buildkernel 236phase. 237Defaults to setting the number of 238.Xr make 1 239jobs 240.Pq Ar -j 241to half the number of CPUs available on the system. 242.It Va NODOC 243Set to a non-empty value to skip the 244.Li doc/ 245tree checkout. 246When set, 247.Va NODOC 248will prevent the 249.Fa doc.txz 250distribution package from being created. 251.It Va NOPORTS 252Set to a non-empty value to skip the 253.Li ports/ 254tree checkout. 255When set, 256.Va NOPORTS 257will prevent the 258.Fa ports.txz 259distribution package from being created. 260Setting this also sets 261.Va NODOC . |
| 153.El 154.Sh MAKEFILE TARGETS 155The release makefile 156.Pq Pa src/release/Makefile 157is fairly abstruse. 158Most developers will only be concerned with the 159.Cm release 160and --- 9 unchanged lines hidden (view full) --- 170.Pa ${DESTDIR} . 171.It Cm cdrom 172Builds installation CD-ROM images. 173This may require the 174.Xr md 4 175(memory disk) device driver be present in the kernel 176(either by being compiled in or available as a module). 177This target produces files called | 262.El 263.Sh MAKEFILE TARGETS 264The release makefile 265.Pq Pa src/release/Makefile 266is fairly abstruse. 267Most developers will only be concerned with the 268.Cm release 269and --- 9 unchanged lines hidden (view full) --- 279.Pa ${DESTDIR} . 280.It Cm cdrom 281Builds installation CD-ROM images. 282This may require the 283.Xr md 4 284(memory disk) device driver be present in the kernel 285(either by being compiled in or available as a module). 286This target produces files called |
| 178.Pa release.iso | 287.Pa disc1.iso |
| 179and 180.Pa bootonly.iso 181as its output. 182.It Cm memstick 183Builds an installation memory stick image named | 288and 289.Pa bootonly.iso 290as its output. 291.It Cm memstick 292Builds an installation memory stick image named |
| 184.Pa memstick . | 293.Pa memstick.img . |
| 185Not applicable on all platforms. 186Requires that the 187.Xr md 4 | 294Not applicable on all platforms. 295Requires that the 296.Xr md 4 |
| 188(memory disk) device driver be present in the kernel 189(either by being compiled in or available as a module). | 297.Pq memory disk 298device driver be present in the kernel 299.Pq either by being compiled in or available as a module . |
| 190.It Cm ftp 191Creates a directory named 192.Pa ftp 193containing the distribution files used in network installations 194and suitable for upload to an FTP mirror. 195.El 196.Pp 197Major subtargets called by targets above: 198.Bl -tag -width ".Cm packagesystem" 199.It Cm packagesystem | 300.It Cm ftp 301Creates a directory named 302.Pa ftp 303containing the distribution files used in network installations 304and suitable for upload to an FTP mirror. 305.El 306.Pp 307Major subtargets called by targets above: 308.Bl -tag -width ".Cm packagesystem" 309.It Cm packagesystem |
| 200Generates all the distribution archives (e.g. base, kernel, ports, doc) | 310Generates all the distribution archives 311.Pq base, kernel, ports, doc |
| 201applicable on this platform. 202.It Cm system 203Builds a bootable installation system containing all the distribution files 204packaged by the 205.Cm packagesystem 206target, and suitable for imaging by the 207.Cm cdrom 208and 209.Cm memstick 210targets. 211.It Cm reldoc 212Builds the release documentation. 213This includes the release notes, | 312applicable on this platform. 313.It Cm system 314Builds a bootable installation system containing all the distribution files 315packaged by the 316.Cm packagesystem 317target, and suitable for imaging by the 318.Cm cdrom 319and 320.Cm memstick 321targets. 322.It Cm reldoc 323Builds the release documentation. 324This includes the release notes, |
| 214hardware guide, and installation instructions. Other documentation (e.g. 215the Handbook) is built during the | 325hardware guide, and installation instructions. 326Other documentation, such as the Handbook, 327is built during the |
| 216.Cm base.txz 217target invoked by 218.Cm packagesystem . 219.El 220.Sh ENVIRONMENT 221Optional variables: 222.Bl -tag -width ".Ev TARGET_ARCH" 223.It Ev OSRELEASE | 328.Cm base.txz 329target invoked by 330.Cm packagesystem . 331.El 332.Sh ENVIRONMENT 333Optional variables: 334.Bl -tag -width ".Ev TARGET_ARCH" 335.It Ev OSRELEASE |
| 224Optional base name for generated media images (e.g. FreeBSD-9.0-RC2-amd64). | 336Optional base name for generated media images 337.Pq e.g., FreeBSD-9.0-RC2-amd64 . |
| 225Defaults to the output of 226.Ic `uname -s`-`uname -r`-`uname -p` 227within the chroot. 228.It Ev WORLDDIR | 338Defaults to the output of 339.Ic `uname -s`-`uname -r`-`uname -p` 340within the chroot. 341.It Ev WORLDDIR |
| 229Location of a directory containing the src tree. By default, the directory | 342Location of a directory containing the src tree. 343By default, the directory |
| 230above the one containing the makefile 231.Pq Pa src . 232.It Ev PORTSDIR | 344above the one containing the makefile 345.Pq Pa src . 346.It Ev PORTSDIR |
| 233Location of a directory containing the ports tree. By default, | 347Location of a directory containing the ports tree. 348By default, |
| 234.Pa /usr/ports . 235If it is unset or cannot be found, ports will not be included in the release. 236.It Ev DOCDIR | 349.Pa /usr/ports . 350If it is unset or cannot be found, ports will not be included in the release. 351.It Ev DOCDIR |
| 237Location of a directory containing the doc tree. By default, | 352Location of a directory containing the doc tree. 353By default, |
| 238.Pa /usr/doc . 239If it is unset or cannot be found, most documentation will not be included in 240the release; see 241.Ev NODOC 242below. 243.It Ev NOPORTS 244If defined, the Ports Collection will be omitted from the release. 245.It Ev NOSRC --- 40 unchanged lines hidden (view full) --- 286.It Pa /usr/doc/Makefile 287.It Pa /usr/doc/share/mk/doc.project.mk 288.It Pa /usr/ports/Mk/bsd.port.mk 289.It Pa /usr/ports/Mk/bsd.sites.mk 290.It Pa /usr/share/examples/etc/make.conf 291.It Pa /usr/src/Makefile 292.It Pa /usr/src/Makefile.inc1 293.It Pa /usr/src/release/Makefile | 354.Pa /usr/doc . 355If it is unset or cannot be found, most documentation will not be included in 356the release; see 357.Ev NODOC 358below. 359.It Ev NOPORTS 360If defined, the Ports Collection will be omitted from the release. 361.It Ev NOSRC --- 40 unchanged lines hidden (view full) --- 402.It Pa /usr/doc/Makefile 403.It Pa /usr/doc/share/mk/doc.project.mk 404.It Pa /usr/ports/Mk/bsd.port.mk 405.It Pa /usr/ports/Mk/bsd.sites.mk 406.It Pa /usr/share/examples/etc/make.conf 407.It Pa /usr/src/Makefile 408.It Pa /usr/src/Makefile.inc1 409.It Pa /usr/src/release/Makefile |
| 294.It Pa /usr/src/release/generate-release.sh | 410.It Pa /usr/src/release/release.sh 411.It Pa /usr/src/release/release.conf.sample |
| 295.El 296.Sh EXAMPLES 297The following sequence of commands can be used to build a 298.Dq "-CURRENT snapshot": 299.Bd -literal -offset indent 300cd /usr 301svn co svn://svn.freebsd.org/base/head src 302cd src --- 8 unchanged lines hidden (view full) --- 311.Pa /var/freebsd-snapshot 312directory. 313.Pp 314The following sequence of commands can be used to build a 315.Dq "-CURRENT snapshot" 316in a clean environment, including ports and documentation: 317.Bd -literal -offset indent 318cd /usr/src/release | 412.El 413.Sh EXAMPLES 414The following sequence of commands can be used to build a 415.Dq "-CURRENT snapshot": 416.Bd -literal -offset indent 417cd /usr 418svn co svn://svn.freebsd.org/base/head src 419cd src --- 8 unchanged lines hidden (view full) --- 428.Pa /var/freebsd-snapshot 429directory. 430.Pp 431The following sequence of commands can be used to build a 432.Dq "-CURRENT snapshot" 433in a clean environment, including ports and documentation: 434.Bd -literal -offset indent 435cd /usr/src/release |
| 319sh generate-release.sh head /local3/release | 436sh release.sh |
| 320.Ed 321.Pp | 437.Ed 438.Pp |
| 439Optionally, a configuration file can be used customize the release build, 440such as the subversion revision to use, the branch of the subversion tree for 441.Li src/ , 442.Li ports/ , 443and 444.Li doc/ . 445.Bd -literal -offset indent 446cd /usr/src/release 447sh release.sh -c $HOME/release.conf 448.Ed 449.Pp |
|
| 322After running these commands, all prepared release files are available in the | 450After running these commands, all prepared release files are available in the |
| 323.Pa /local3/release/R | 451.Pa /scratch |
| 324directory. | 452directory. |
| 453The target directory can be changed by specifying the 454.Va CHROOTDIR 455variable in 456.Li release.conf . |
|
| 325.Sh SEE ALSO 326.Xr cc 1 , 327.Xr install 1 , 328.Xr make 1 , 329.Xr svn 1 Pq Pa ports/devel/subversion , 330.Xr uname 1 , 331.Xr md 4 , 332.Xr make.conf 5 , --- 34 unchanged lines hidden (view full) --- 367For the 368.Fx 9.0 369release, 370.Pa src/release/Makefile 371was overhauled and the wrapper script 372.Pa src/release/generate-release.sh 373introduced to support the introduction of a new installer. 374.Pp | 457.Sh SEE ALSO 458.Xr cc 1 , 459.Xr install 1 , 460.Xr make 1 , 461.Xr svn 1 Pq Pa ports/devel/subversion , 462.Xr uname 1 , 463.Xr md 4 , 464.Xr make.conf 5 , --- 34 unchanged lines hidden (view full) --- 499For the 500.Fx 9.0 501release, 502.Pa src/release/Makefile 503was overhauled and the wrapper script 504.Pa src/release/generate-release.sh 505introduced to support the introduction of a new installer. 506.Pp |
| 507For the 508.Fx 9.2 509release, 510.Pa src/release/release.sh 511was introduced to support per-build configuration files. 512.Pa src/release/release.sh 513is heavily based on the 514.Pa src/release/generate-release.sh 515script. 516.Pp |
|
| 375At near 1000 revisions spread over multiple branches, the 376.Xr svn 1 377log of 378.Pa src/release/Makefile 379contains a vivid historical record of some 380of the hardships release engineers go through. 381.Sh AUTHORS 382.Pa src/release/Makefile 383was originally written by 384.An -nosplit 385.An Rod Grimes , 386.An Jordan Hubbard , 387and 388.An Poul-Henning Kamp . | 517At near 1000 revisions spread over multiple branches, the 518.Xr svn 1 519log of 520.Pa src/release/Makefile 521contains a vivid historical record of some 522of the hardships release engineers go through. 523.Sh AUTHORS 524.Pa src/release/Makefile 525was originally written by 526.An -nosplit 527.An Rod Grimes , 528.An Jordan Hubbard , 529and 530.An Poul-Henning Kamp . |
| 389This manual page was written by | 531.Pp 532This manual page was originally written by |
| 390.An Murray Stokely Aq murray@FreeBSD.org . | 533.An Murray Stokely Aq murray@FreeBSD.org . |
| 534.Pp 535It was updated by 536.An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org 537to include the 538.Fa generate-release.sh 539script used for the 540.Fx 9.0 541release cycle. 542.Pp 543It was later updated by 544.An Glen Barber Aq gjb@FreeBSD.org 545to include the 546.Fa release.sh 547script used for the 548.Fx 9.2 549release cycle. |
|