| release.7 (92220) | release.7 (92258) |
|---|---|
| 1.\" Copyright (c) 2002 2.\" Murray Stokely <murray@FreeBSD.org> | 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 --- 6 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.\" | 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 --- 6 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 92220 2002-03-13 09:54:31Z murray $ | 25.\" $FreeBSD: head/share/man/man7/release.7 92258 2002-03-14 04:21:50Z murray $ |
| 26.\" 27.Dd March 12, 2002 28.Dt RELEASE 7 29.Os 30.Sh NAME 31.Nm release | 26.\" 27.Dd March 12, 2002 28.Dt RELEASE 7 29.Os 30.Sh NAME 31.Nm release |
| 32.Nd release building infrastructure | 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 40CVS repository in 41.Pa src/release . 42A complete release can actually be built with only a single command, 43including the creation of ISO images suitable for burning to CDROM, 44installation floppies, and an FTP install directory. 45This command is aptly named | 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 40CVS repository in 41.Pa src/release . 42A complete release can actually be built with only a single command, 43including the creation of ISO images suitable for burning to CDROM, 44installation floppies, and an FTP install directory. 45This command is aptly named |
| 46.Dq make release . | 46.Dq Li "make release" . |
| 47.Pp 48Before attempting to build a release, the user is expected to be 49familiar with the contents of 50.Xr build 7 , 51and should have experience upgrading systems from source with | 47.Pp 48Before attempting to build a release, the user is expected to be 49familiar with the contents of 50.Xr build 7 , 51and should have experience upgrading systems from source with |
| 52.Dq make world . | 52.Dq Li "make world" . |
| 53The release build process requires that 54.Pa /usr/obj 55be populated with the output of | 53The release build process requires that 54.Pa /usr/obj 55be populated with the output of |
| 56.Dq make buildworld . | 56.Dq Li "make buildworld" . |
| 57This is necessary so that the object files for a complete system can 58be installed into a clean 59.Xr chroot 8 60environment. 61The release procedure also requires that the 62.Xr md 4 63(memory disk) device driver be present in the kernel 64(either by being compiled in or loaded as a module). 65.Pp 66This document does not cover source code management, quality 67assurance, or other aspects of the release engineering process. 68.Sh TARGETS 69The release makefile 70.Pq Pa src/release/Makefile 71is fairly abstruse. 72Most developers will only be concerned with the | 57This is necessary so that the object files for a complete system can 58be installed into a clean 59.Xr chroot 8 60environment. 61The release procedure also requires that the 62.Xr md 4 63(memory disk) device driver be present in the kernel 64(either by being compiled in or loaded as a module). 65.Pp 66This document does not cover source code management, quality 67assurance, or other aspects of the release engineering process. 68.Sh TARGETS 69The release makefile 70.Pq Pa src/release/Makefile 71is fairly abstruse. 72Most developers will only be concerned with the |
| 73.Ar release | 73.Cm release |
| 74target. 75.\" XXX: Some sort of introduction to this list? All the others have one. | 74target. 75.\" XXX: Some sort of introduction to this list? All the others have one. |
| 76.Bl -tag -width rerelease 77.It Ar release | 76.Bl -tag -width ".Cm rerelease" 77.It Cm release |
| 78Uses | 78Uses |
| 79.Dq make installworld | 79.Dq Li "make installworld" |
| 80to install a clean system into a 81.Xr chroot 8 82environment on the filesystem. 83Checks out the specified version of the source code and then rebuilds 84the entire system in the clean environment with | 80to install a clean system into a 81.Xr chroot 8 82environment on the filesystem. 83Checks out the specified version of the source code and then rebuilds 84the entire system in the clean environment with |
| 85.Dq make world . | 85.Dq Li "make world" . |
| 86The detailed steps that follow are then executed to package up the 87different distributions, build the installation floppy disks, build 88release documentation, and so on. | 86The detailed steps that follow are then executed to package up the 87different distributions, build the installation floppy disks, build 88release documentation, and so on. |
| 89.It Ar rerelease | 89.It Cm rerelease |
| 90Assumes that the output of a release build has been manually modified, 91and performs the minimal number of steps to rebuild the release using 92the intermediate output of the previous | 90Assumes that the output of a release build has been manually modified, 91and performs the minimal number of steps to rebuild the release using 92the intermediate output of the previous |
| 93.Dq make release . | 93.Dq Li "make release" . |
| 94.El 95.Pp 96Targets called by | 94.El 95.Pp 96Targets called by |
| 97.Dq make release : 98.Bl -tag -width release.9 99.It Ar release.1 | 97.Dq Li "make release" : 98.Bl -tag -width ".Cm release.9" 99.It Cm release.1 |
| 100Cleans out the 101.Pa ${CHROOTDIR}/R 102directory and uses | 100Cleans out the 101.Pa ${CHROOTDIR}/R 102directory and uses |
| 103.Xr mtree 1 | 103.Xr mtree 8 |
| 104to build the directory hierarchy for the system. | 104to build the directory hierarchy for the system. |
| 105.It Ar release.2 | 105.It Cm release.2 |
| 106Installs the system into the distribution directories. | 106Installs the system into the distribution directories. |
| 107.It Ar release.3 | 107.It Cm release.3 |
| 108.\" XXX: This should either be "GENERIC kernel" (singular) or 109.\" XXX: "GENERIC and <some other> kernels". 110Makes and installs the 111.Pa GENERIC 112kernel. | 108.\" XXX: This should either be "GENERIC kernel" (singular) or 109.\" XXX: "GENERIC and <some other> kernels". 110Makes and installs the 111.Pa GENERIC 112kernel. |
| 113.It Ar release.4 | 113.It Cm release.4 |
| 114Uses 115.Xr crunchgen 1 116to build | 114Uses 115.Xr crunchgen 1 116to build |
| 117.Sq crunched | 117.Dq crunched |
| 118binaries to live on the installation floppies. | 118binaries to live on the installation floppies. |
| 119.It Ar release.5 | 119.It Cm release.5 |
| 120Builds synthetic distributions, and cleans up the previously built 121distribution trees. | 120Builds synthetic distributions, and cleans up the previously built 121distribution trees. |
| 122.It Ar release.6 | 122.It Cm release.6 |
| 123Creates tarballs of the assembled distribution trees. | 123Creates tarballs of the assembled distribution trees. |
| 124.It Ar release.7 | 124.It Cm release.7 |
| 125Makes source distributions. | 125Makes source distributions. |
| 126.It Ar release.8 | 126.It Cm release.8 |
| 127Creates the boot and MFS root floppies. | 127Creates the boot and MFS root floppies. |
| 128.It Ar release.9 | 128.It Cm release.9 |
| 129Creates the fixit floppy. | 129Creates the fixit floppy. |
| 130.It Ar ftp.1 | 130.It Cm ftp.1 |
| 131Sets up a suitable area for FTP installations. | 131Sets up a suitable area for FTP installations. |
| 132.It Ar cdrom.1 | 132.It Cm cdrom.1 |
| 133Sets up a suitable area to build CDROM images. | 133Sets up a suitable area to build CDROM images. |
| 134.It Ar iso.1 | 134.It Cm iso.1 |
| 135Builds two ISO images (installation and | 135Builds two ISO images (installation and |
| 136.Sq live | 136.Dq live |
| 137filesystem) from the CDROM release area 138(Disabled by default, see 139.Pa MAKE_ISOS 140below). | 137filesystem) from the CDROM release area 138(Disabled by default, see 139.Pa MAKE_ISOS 140below). |
| 141.It Ar doc.1 | 141.It Cm doc.1 |
| 142Builds all of the necessary tools to turn the 143.Fx 144Documentation Project source documents (SGML, XML) into HTML 145and text documents that will accompany the release. 146Also, builds and installs the actual user documentation. 147This includes the Handbook, FAQ, articles, and so on. | 142Builds all of the necessary tools to turn the 143.Fx 144Documentation Project source documents (SGML, XML) into HTML 145and text documents that will accompany the release. 146Also, builds and installs the actual user documentation. 147This includes the Handbook, FAQ, articles, and so on. |
| 148.It Ar doc.2 | 148.It Cm doc.2 |
| 149Builds the release documentation. 150This includes the release notes, 151hardware guide, and installation instructions. 152.El 153.Sh ENVIRONMENT 154Variables that must be specified: | 149Builds the release documentation. 150This includes the release notes, 151hardware guide, and installation instructions. 152.El 153.Sh ENVIRONMENT 154Variables that must be specified: |
| 155.Bl -tag -width RELEASETAG | 155.Bl -tag -width ".Va RELEASETAG" |
| 156.It Ev CHROOTDIR 157The directory to be used as the 158.Xr chroot 8 159environment for the entire release build. 160.\" XXX: I recommend against hardcoding specific numbers like "2.3" here; 161.\" XXX: perhaps it should be replaced with something to the effect of 162.\" XXX: "we don't know how much space you'll need, but make sure you have 163.\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number, --- 9 unchanged lines hidden (view full) --- 173which affects the output of 174.Xr uname 1 . 175.It Ev CVSROOT 176The location of the 177.Fx 178CVS repository. 179.It Ev RELEASETAG 180The CVS tag corresponding to the release that is to be built. | 156.It Ev CHROOTDIR 157The directory to be used as the 158.Xr chroot 8 159environment for the entire release build. 160.\" XXX: I recommend against hardcoding specific numbers like "2.3" here; 161.\" XXX: perhaps it should be replaced with something to the effect of 162.\" XXX: "we don't know how much space you'll need, but make sure you have 163.\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number, --- 9 unchanged lines hidden (view full) --- 173which affects the output of 174.Xr uname 1 . 175.It Ev CVSROOT 176The location of the 177.Fx 178CVS repository. 179.It Ev RELEASETAG 180The CVS tag corresponding to the release that is to be built. |
| 181If undefined, the release will be built from the HEAD of the CVS tree | 181If undefined, the release will be built from the 182.Dv HEAD 183of the CVS tree |
| 182(a | 184(a |
| 183.Sq -CURRENT snapshot ) . | 185.Dq -CURRENT snapshot ) . |
| 184.El 185.Pp 186Optional variables: | 186.El 187.Pp 188Optional variables: |
| 187.Bl -tag -width RELEASEDISTFILES | 189.Bl -tag -width ".Ev RELEASEDISTFILES" |
| 188.It Ev LOCAL_PATCHES 189A patch file against 190.Pa /usr/src 191that will be applied in the 192.Xr chroot 8 193environment before the release build begins. 194.It Ev PATCH_FLAGS 195Arguments for the 196.Xr patch 1 197command used to apply | 190.It Ev LOCAL_PATCHES 191A patch file against 192.Pa /usr/src 193that will be applied in the 194.Xr chroot 8 195environment before the release build begins. 196.It Ev PATCH_FLAGS 197Arguments for the 198.Xr patch 1 199command used to apply |
| 198.Ev LOCAL_PATCHES . | 200.Ev LOCAL_PATCHES 201patch file. |
| 199.It Ev MAKE_ISOS 200If defined, bootable ISO CDROM images will be created from the 201contents of the CDROM stage directory. 202.It Ev NODOC 203If set to | 202.It Ev MAKE_ISOS 203If defined, bootable ISO CDROM images will be created from the 204contents of the CDROM stage directory. 205.It Ev NODOC 206If set to |
| 204.Dq YES | 207.Dq Li YES |
| 205then the documentation will not be built. 206Due to the SGML-based 207toolchain and multiple languages supported by the 208.Fx 209Documentation Project, this may speed up the release build considerably. 210.It Ev NOPORTS 211If set to | 208then the documentation will not be built. 209Due to the SGML-based 210toolchain and multiple languages supported by the 211.Fx 212Documentation Project, this may speed up the release build considerably. 213.It Ev NOPORTS 214If set to |
| 212.Dq YES | 215.Dq Li YES |
| 213then the ports tree will be omitted from the release. 214.It Ev RELEASEDISTFILES 215The directory where the distribution files for ports required by the 216release build can be found. 217This may save a significant amount of time over downloading the 218distfiles through a slow link. 219.It Ev RELEASENOUPDATE 220If this variable is defined for | 216then the ports tree will be omitted from the release. 217.It Ev RELEASEDISTFILES 218The directory where the distribution files for ports required by the 219release build can be found. 220This may save a significant amount of time over downloading the 221distfiles through a slow link. 222.It Ev RELEASENOUPDATE 223If this variable is defined for |
| 221.Dq make rerelease , | 224.Dq Li "make rerelease" , |
| 222the source code will not be updated with | 225the source code will not be updated with |
| 223.Dq cvs up . | 226.Dq Li "cvs update" . |
| 224.El 225.Sh FILES 226.Bl -tag -compact 227.It Pa /etc/make.conf 228.It Pa /usr/doc/Makefile 229.It Pa /usr/doc/share/mk/doc.project.mk 230.It Pa /usr/ports/Mk/bsd.port.mk 231.It Pa /usr/ports/Mk/bsd.sites.mk --- 20 unchanged lines hidden (view full) --- 252.Ed 253.Pp 254After running these commands, a complete system suitable for FTP or 255CDROM distribution is available in the 256.Pa /local3/release/R 257directory. 258.Pp 259The following sequence of commands can be used to build a | 227.El 228.Sh FILES 229.Bl -tag -compact 230.It Pa /etc/make.conf 231.It Pa /usr/doc/Makefile 232.It Pa /usr/doc/share/mk/doc.project.mk 233.It Pa /usr/ports/Mk/bsd.port.mk 234.It Pa /usr/ports/Mk/bsd.sites.mk --- 20 unchanged lines hidden (view full) --- 255.Ed 256.Pp 257After running these commands, a complete system suitable for FTP or 258CDROM distribution is available in the 259.Pa /local3/release/R 260directory. 261.Pp 262The following sequence of commands can be used to build a |
| 260.Sq -CURRENT snapshot | 263.Dq -CURRENT snapshot |
| 261of a 262locally modified source tree: 263.Bd -literal -offset indent 264cd /usr/src 265cvs diff -u > /path/to/local.patch 266make buildworld 267cd release 268make release CHROOTDIR=/local3/release BUILDNAME=5.0-SNAPSHOT \\ | 264of a 265locally modified source tree: 266.Bd -literal -offset indent 267cd /usr/src 268cvs diff -u > /path/to/local.patch 269make buildworld 270cd release 271make release CHROOTDIR=/local3/release BUILDNAME=5.0-SNAPSHOT \\ |
| 269 CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch | 272 CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch |
| 270.Ed 271.Sh SEE ALSO 272.Xr cc 1 , 273.Xr crunchgen 1 , | 273.Ed 274.Sh SEE ALSO 275.Xr cc 1 , 276.Xr crunchgen 1 , |
| 277.Xr cvs 1 , |
|
| 274.Xr install 1 , 275.Xr make 1 , | 278.Xr install 1 , 279.Xr make 1 , |
| 276.Xr mtree 1 , | |
| 277.Xr patch 1 , 278.Xr uname 1 , | 280.Xr patch 1 , 281.Xr uname 1 , |
| 282.Xr md 4 , |
|
| 279.Xr make.conf 5 , 280.Xr build 7 , 281.Xr ports 7 , | 283.Xr make.conf 5 , 284.Xr build 7 , 285.Xr ports 7 , |
| 282.Xr chroot 8 | 286.Xr chroot 8 , 287.Xr mtree 8 |
| 283.Rs 284.%T FreeBSD Release Engineering 285.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 286.Re 287.Rs 288.%T FreeBSD Release Engineering of Third Party Packages 289.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 290.Re --- 11 unchanged lines hidden (view full) --- 302As part of the 303.Fx 2.0 304release engineering effort, significant 305effort was spent getting 306.Pa src/release/Makefile 307into a shape where it could at least automate most of the tediousness 308of building a release in a sterile environment. 309.Pp | 288.Rs 289.%T FreeBSD Release Engineering 290.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ 291.Re 292.Rs 293.%T FreeBSD Release Engineering of Third Party Packages 294.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ 295.Re --- 11 unchanged lines hidden (view full) --- 307As part of the 308.Fx 2.0 309release engineering effort, significant 310effort was spent getting 311.Pa src/release/Makefile 312into a shape where it could at least automate most of the tediousness 313of building a release in a sterile environment. 314.Pp |
| 310With its almost 1000 revisions spread over multiple branches, the CVS | 315With its almost 1000 revisions spread over multiple branches, the 316.Xr cvs 1 |
| 311log of 312.Pa src/release/Makefile 313contains a vivid historical record of some 314of the hardships release engineers go through. 315.Sh AUTHORS 316.Pa src/release/Makefile | 317log of 318.Pa src/release/Makefile 319contains a vivid historical record of some 320of the hardships release engineers go through. 321.Sh AUTHORS 322.Pa src/release/Makefile |
| 317was originally written by Rod Grimes, Jordan Hubbard, and Poul-Henning Kamp. | 323was originally written by 324.An -nosplit 325.An Rod Grimes , 326.An Jordan Hubbard , 327and 328.An Poul-Henning Kamp . |
| 318This manual page was written by 319.An Murray Stokely Aq murray@FreeBSD.org . | 329This manual page was written by 330.An Murray Stokely Aq murray@FreeBSD.org . |