share/man/man7/release.7

   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 January 14, 2012
  28 .Dt RELEASE 7
  29 .Os
  30 .Sh NAME
  31 .Nm release
  32 .Nd "release building infrastructure"
  33 .Sh DESCRIPTION
  34 .Fx
  35 provides a complete build environment suitable for users to make
  36 full releases of the
  37 .Fx
  38 operating system.
  39 All of the tools necessary to build a release are available from the
  40 .Fx
  41 source code repository in
  42 .Pa src/release .
  43 A complete release can actually be built with only a single command,
  44 including the creation of ISO images suitable for burning to CD-ROM,
  45 memory stick images, and an FTP install directory.
  46 This command is aptly named
  47 .Dq Li "make release" .
  48 .Pp
  49 For some users, it may be desirable to provide an absolutely clean
  50 build environment, with no local modifications to the source tree or to
  51 .Xr make.conf 5 ,
  52 and with clean checkouts of specific versions of the doc, src, and ports
  53 trees. For this purpose, a script
  54 .Pq Pa src/release/generate-release.sh
  55 is provided to automate these checkouts and then execute
  56 .Dq Li "make release"
  57 in a clean
  58 .Xr chroot 8 .
  59 .Pp
  60 Before attempting to build a release, the user is expected to be
  61 familiar with the contents of
  62 .Xr build 7 ,
  63 and should have experience upgrading systems from source.
  64 .Pp
  65 The release build process requires that
  66 .Pa /usr/obj
  67 be populated with the output of
  68 .Dq Li "make buildworld"
  69 and
  70 .Dq Li "make buildkernel" .
  71 This is necessary to provide the object files for the release or, when
  72 using
  73 .Pa generate-release.sh ,
  74 so that the object files for a complete system can be installed into a clean
  75 .Xr chroot 8
  76 environment. In this second case, the built world must be capable of running
  77 on the build system (i.e. it must be for the same architecture and be
  78 compatible with the installed kernel).
  79 The release procedure on some architectures may also require that the
  80 .Xr md 4
  81 (memory disk) device driver be present in the kernel
  82 (either by being compiled in or available as a module).
  83 .Pp
  84 This document does not cover source code management, quality
  85 assurance, or other aspects of the release engineering process.
  86 .Sh CLEAN RELEASE GENERATION
  87 Official releases of FreeBSD are produced in a totally clean environment to
  88 ensure consistency between the versions of the src, ports, and doc trees
  89 and to avoid contamination from the host system (e.g. local patches, changes
  90 to
  91 .Xr make.conf 5 ,
  92 etc.). This is accomplished using the wrapper script
  93 .Pa src/release/generate-release.sh .
  94 .Pp
  95 .Ic generate-release.sh
  96 svn-branch scratch-dir
  97 .Pp
  98 .Ic generate-release.sh
  99 calls
 100 .Dq Li "make installworld"
 101 to generate a
 102 .Xr chroot 8
 103 environment in
 104 .Ar scratch-dir .
 105 It then checks out the src tree specified by
 106 .Ar svn-branch
 107 using
 108 .Xr svn 1
 109 and (optionally) the ports and documentation trees using
 110 .Xr csup 1
 111 or
 112 .Xr cvs 1 .
 113 Once the various source trees have been obtained, it executes
 114 .Dq Li "make release"
 115 within the
 116 .Xr chroot 8
 117 environment and places the result in
 118 .Pa $scratch-dir/R .
 119 Note that because this uses a chroot, it cannot be used to cross-build
 120 .Fx
 121 release media.
 122 .Pp
 123 Environment variables:
 124 .Bl -tag -width ".Cm MAKE_FLAGS"
 125 .It Ev CVSUP_HOST
 126 The CVSUP server to use for the doc and ports trees. One of
 127 .Ev CVSUP_HOST
 128 or
 129 .Ev CVSROOT
 130 must be specified for ports and documentation to be included in the release.
 131 .It Ev CVSROOT
 132 The location of the
 133 .Fx
 134 CVS repository to use for the doc and ports trees. One of
 135 .Ev CVSUP_HOST
 136 or
 137 .Ev CVSROOT
 138 must be specified for ports and documentation to be included in the release.
 139 .It Ev CVS_TAG
 140 If the variable
 141 .Ev CVS_TAG
 142 is set, that tag will be used for CVS checkouts (doc and ports), otherwise
 143 .Ic generate-release.sh
 144 will use HEAD.
 145 .It Ev MAKE_FLAGS
 146 This environment variable can be set to pass flags (e.g. -j) to
 147 .Xr make 1
 148 when invoked by the script.
 149 .It Ev SVNROOT
 150 The location of the FreeBSD SVN source repository. Defaults to
 151 .Pa svn://svn.freebsd.org/base .
 152 .It Ev RELSTRING
 153 Optional base name for generated media images (e.g. FreeBSD-9.0-RC2-amd64).
 154 Defaults to the output of
 155 .Ic `uname -s`-`uname -r`-`uname -p`
 156 within the chroot.
 157 .El
 158 .Sh MAKEFILE TARGETS
 159 The release makefile
 160 .Pq Pa src/release/Makefile
 161 is fairly abstruse.
 162 Most developers will only be concerned with the
 163 .Cm release
 164 and
 165 .Cm install
 166 targets.
 167 .\" XXX: Some sort of introduction to this list?  All the others have one.
 168 .Bl -tag -width ".Cm packagesystem"
 169 .It Cm release
 170 Meta-target to build all release media and distributions applicable to this
 171 platform.
 172 .It Cm install
 173 Copy all produced release media to
 174 .Pa ${DESTDIR} .
 175 .It Cm cdrom
 176 Builds installation CD-ROM images. On some systems, this may require that
 177 .Xr mkisofs 8
 178 be installed
 179 .Pq Pa sysutils/cdrtools
 180 and possibly that the
 181 .Xr md 4
 182 (memory disk) device driver be present in the kernel
 183 (either by being compiled in or available as a module). This target
 184 produces files called
 185 .Pa release.iso
 186 and
 187 .Pa bootonly.iso
 188 as its output.
 189 .It Cm memstick
 190 Builds an installation memory stick image named
 191 .Pa memstick .
 192 Not applicable on all platforms. Requires that the
 193 .Xr md 4
 194 (memory disk) device driver be present in the kernel
 195 (either by being compiled in or available as a module).
 196 .It Cm ftp
 197 Creates a directory named
 198 .Pa ftp
 199 containing the distribution files used in network installations
 200 and suitable for upload to an FTP mirror.
 201 .El
 202 .Pp
 203 Major subtargets called by targets above:
 204 .Bl -tag -width ".Cm packagesystem"
 205 .It Cm packagesystem
 206 Generates all the distribution archives (e.g. base, kernel, ports, doc)
 207 applicable on this platform.
 208 .It Cm system
 209 Builds a bootable installation system containing all the distribution files
 210 packaged by the
 211 .Cm packagesystem
 212 target, and suitable for imaging by the
 213 .Cm cdrom
 214 and
 215 .Cm memstick
 216 targets.
 217 .It Cm reldoc
 218 Builds the release documentation.
 219 This includes the release notes,
 220 hardware guide, and installation instructions. Other documentation (e.g.
 221 the Handbook) is built during the
 222 .Cm base.txz
 223 target invoked by
 224 .Cm packagesystem.
 225 .El
 226 .Sh ENVIRONMENT
 227 Optional variables:
 228 .Bl -tag -width ".Va TARGET_ARCH"
 229 .It Va WORLDDIR
 230 Location of a directory containing the src tree. By default, the directory
 231 above the one containing the makefile
 232 .Pq Pa src .
 233 .It Va PORTSDIR
 234 Location of a directory containing the ports tree. By default,
 235 .Pa /usr/ports .
 236 If it is unset or cannot be found, ports will not be included in the release.
 237 .It Va DOCDIR
 238 Location of a directory containing the doc tree. By default,
 239 .Pa /usr/doc .
 240 If it is unset or cannot be found, most documentation will not be included in
 241 the release; see
 242 .Ev NODOC
 243 below.
 244 .It Va NOPORTS
 245 If defined, the Ports Collection will be omitted from the release.
 246 .It Va NOSRC
 247 If set, do not include system source code in the release.
 248 .It Va NODOC
 249 If defined, the SGML-based documentation from the
 250 .Fx
 251 Documentation Project will not be built.
 252 However, the
 253 .Dq doc
 254 distribution will still be created with the minimal documentation set
 255 provided in
 256 .Pa src/share/doc .
 257 .It Va TARGET
 258 The target hardware platform.
 259 This is analogous to the
 260 .Dq Nm uname Fl m
 261 output.
 262 This is necessary to cross-build some target architectures.
 263 For example, cross-building for PC98 machines requires
 264 .Va TARGET_ARCH Ns = Ns Li i386
 265 and
 266 .Va TARGET Ns = Ns Li pc98 .
 267 If not set,
 268 .Va TARGET
 269 defaults to the current hardware platform.
 270 .It Va TARGET_ARCH
 271 The target machine processor architecture.
 272 This is analogous to the
 273 .Dq Nm uname Fl p
 274 output.
 275 Set this to cross-build for a different architecture.
 276 If not set,
 277 .Va TARGET_ARCH
 278 defaults to the current machine architecture, unless
 279 .Va TARGET
 280 is also set, in which case it defaults to the appropriate
 281 value for that platform.
 282 Typically, one only needs to set
 283 .Va TARGET .
 284 .El
 285 .Sh FILES
 286 .Bl -tag -compact
 287 .It Pa /usr/doc/Makefile
 288 .It Pa /usr/doc/share/mk/doc.project.mk
 289 .It Pa /usr/ports/Mk/bsd.port.mk
 290 .It Pa /usr/ports/Mk/bsd.sites.mk
 291 .It Pa /usr/share/examples/etc/make.conf
 292 .It Pa /usr/src/Makefile
 293 .It Pa /usr/src/Makefile.inc1
 294 .It Pa /usr/src/release/Makefile
 295 .It Pa /usr/src/release/generate-release.sh
 296 .El
 297 .Sh EXAMPLES
 298 The following sequence of commands can be used to build a
 299 .Dq "-CURRENT snapshot":
 300 .Bd -literal -offset indent
 301 cd /usr
 302 svn co svn://svn.freebsd.org/base/head src
 303 cd src
 304 make buildworld buildkernel
 305 cd release
 306 make release
 307 make install DESTDIR=/var/freebsd-snapshot
 308 .Ed
 309 .Pp
 310 After running these commands, all produced distribution files (tarballs
 311 for FTP, CD-ROM images, etc.) are available in the
 312 .Pa /var/freebsd-snapshot
 313 directory.
 314 .Pp
 315 The following sequence of commands can be used to build a
 316 .Dq "-CURRENT snapshot"
 317 in a clean environment, including ports and documentation:
 318 .Bd -literal -offset indent
 319 cd /usr/src/release
 320 export CVSUP_HOST=cvsupN.freebsd.org
 321 sh generate-release.sh head /local3/release
 322 .Ed
 323 .Pp
 324 After running these commands, all prepared release files are available in the
 325 .Pa /local3/release/R
 326 directory.
 327 .Sh SEE ALSO
 328 .Xr cc 1 ,
 329 .Xr cvs 1 ,
 330 .Xr install 1 ,
 331 .Xr make 1 ,
 332 .Xr svn 1 Pq Pa ports/devel/subversion-freebsd ,
 333 .Xr uname 1 ,
 334 .Xr md 4 ,
 335 .Xr make.conf 5 ,
 336 .Xr build 7 ,
 337 .Xr ports 7 ,
 338 .Xr chroot 8 ,
 339 .Xr mtree 8 ,
 340 .Xr sysctl 8
 341 .Rs
 342 .%T "FreeBSD Release Engineering"
 343 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
 344 .Re
 345 .Rs
 346 .%T "FreeBSD Release Engineering of Third Party Packages"
 347 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
 348 .Re
 349 .Rs
 350 .%T "FreeBSD Developers' Handbook"
 351 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
 352 .Re
 353 .Sh HISTORY
 354 .Fx
 355 1.x
 356 used a manual checklist, compiled by
 357 .An Rod Grimes ,
 358 to produce a release.
 359 Apart from being incomplete, the list put a lot of specific demands on
 360 available file systems and was quite torturous to execute.
 361 .Pp
 362 As part of the
 363 .Fx 2.0
 364 release engineering effort, significant
 365 effort was spent getting
 366 .Pa src/release/Makefile
 367 into a shape where it could at least automate most of the tediousness
 368 of building a release in a sterile environment.
 369 .Pp
 370 For the
 371 .Fx 9.0
 372 release,
 373 .Pa src/release/Makefile
 374 was overhauled and the wrapper script
 375 .Pa src/release/generate-release.sh
 376 introduced to support the introduction of a new installer.
 377 .Pp
 378 At near 1000 revisions spread over multiple branches, the
 379 .Xr cvs 1
 380 log of
 381 .Pa src/release/Makefile
 382 contains a vivid historical record of some
 383 of the hardships release engineers go through.
 384 .Sh AUTHORS
 385 .Pa src/release/Makefile
 386 was originally written by
 387 .An -nosplit
 388 .An Rod Grimes ,
 389 .An Jordan Hubbard ,
 390 and
 391 .An Poul-Henning Kamp .
 392 This manual page was written by
 393 .An Murray Stokely Aq murray@FreeBSD.org .