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 February 3, 2013
  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 Once the various source trees have been obtained, it executes
 110 .Dq Li "make release"
 111 within the
 112 .Xr chroot 8
 113 environment and places the result in
 114 .Pa $scratch-dir/R .
 115 Note that because this uses a chroot, it cannot be used to cross-build
 116 .Fx
 117 release media.
 118 .Pp
 119 Optional environment variables:
 120 .Bl -tag -width ".Cm WORLD_FLAGS"
 121 .It Ev WORLD_FLAGS
 122 This environment variable can be set to pass flags (e.g. -j) to
 123 .Xr make 1
 124 when invoked to build a world by the script.
 125 .It Ev KERNEL_FLAGS
 126 This environment variable can be set to pass flags (e.g. -j) to
 127 .Xr make 1
 128 when invoked to build a kernel by the script.
 129 .It Ev SVNROOTBASE
 130 The base part of URL of the FreeBSD SVN repositories.
 131 Defaults to
 132 .Pa svn://svn.freebsd.org .
 133 .It Ev SVNROOTSRC
 134 The URL of the FreeBSD SVN source repository.
 135 Defaults to
 136 .Pa ${SVNROOTBASE}/base .
 137 .It Ev SVNROOTDOC
 138 The URL of the FreeBSD SVN doc repository.
 139 Defaults to
 140 .Pa ${SVNROOTBASE}/doc .
 141 .It Ev SVNROOTPORTS
 142 The URL of the FreeBSD SVN ports repository.
 143 Defaults to
 144 .Pa ${SVNROOTBASE}/ports .
 145 .It Ev BRANCHDOC
 146 The branch name of the FreeBSD SVN doc repository.
 147 Defaults to
 148 .Pa head .
 149 .It Ev BRANCHPORTS
 150 The branch name of the FreeBSD SVN ports repository.
 151 Defaults to
 152 .Pa head .
 153 .El
 154 .Sh MAKEFILE TARGETS
 155 The release makefile
 156 .Pq Pa src/release/Makefile
 157 is fairly abstruse.
 158 Most developers will only be concerned with the
 159 .Cm release
 160 and
 161 .Cm install
 162 targets.
 163 .\" XXX: Some sort of introduction to this list?  All the others have one.
 164 .Bl -tag -width ".Cm packagesystem"
 165 .It Cm release
 166 Meta-target to build all release media and distributions applicable to this
 167 platform.
 168 .It Cm install
 169 Copy all produced release media to
 170 .Pa ${DESTDIR} .
 171 .It Cm cdrom
 172 Builds installation CD-ROM images.
 173 This 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).
 177 This target produces files called
 178 .Pa release.iso
 179 and
 180 .Pa bootonly.iso
 181 as its output.
 182 .It Cm memstick
 183 Builds an installation memory stick image named
 184 .Pa memstick .
 185 Not applicable on all platforms.
 186 Requires that the
 187 .Xr md 4
 188 (memory disk) device driver be present in the kernel
 189 (either by being compiled in or available as a module).
 190 .It Cm ftp
 191 Creates a directory named
 192 .Pa ftp
 193 containing the distribution files used in network installations
 194 and suitable for upload to an FTP mirror.
 195 .El
 196 .Pp
 197 Major subtargets called by targets above:
 198 .Bl -tag -width ".Cm packagesystem"
 199 .It Cm packagesystem
 200 Generates all the distribution archives (e.g. base, kernel, ports, doc)
 201 applicable on this platform.
 202 .It Cm system
 203 Builds a bootable installation system containing all the distribution files
 204 packaged by the
 205 .Cm packagesystem
 206 target, and suitable for imaging by the
 207 .Cm cdrom
 208 and
 209 .Cm memstick
 210 targets.
 211 .It Cm reldoc
 212 Builds the release documentation.
 213 This includes the release notes,
 214 hardware guide, and installation instructions. Other documentation (e.g.
 215 the Handbook) is built during the
 216 .Cm base.txz
 217 target invoked by
 218 .Cm packagesystem .
 219 .El
 220 .Sh ENVIRONMENT
 221 Optional variables:
 222 .Bl -tag -width ".Ev TARGET_ARCH"
 223 .It Ev OSRELEASE
 224 Optional base name for generated media images (e.g. FreeBSD-9.0-RC2-amd64).
 225 Defaults to the output of
 226 .Ic `uname -s`-`uname -r`-`uname -p`
 227 within the chroot.
 228 .It Ev WORLDDIR
 229 Location of a directory containing the src tree. By default, the directory
 230 above the one containing the makefile
 231 .Pq Pa src .
 232 .It Ev PORTSDIR
 233 Location of a directory containing the ports tree. By default,
 234 .Pa /usr/ports .
 235 If it is unset or cannot be found, ports will not be included in the release.
 236 .It Ev DOCDIR
 237 Location of a directory containing the doc tree. By default,
 238 .Pa /usr/doc .
 239 If it is unset or cannot be found, most documentation will not be included in
 240 the release; see
 241 .Ev NODOC
 242 below.
 243 .It Ev NOPORTS
 244 If defined, the Ports Collection will be omitted from the release.
 245 .It Ev NOSRC
 246 If set, do not include system source code in the release.
 247 .It Ev NODOC
 248 If defined, the XML-based documentation from the
 249 .Fx
 250 Documentation Project will not be built.
 251 However, the
 252 .Dq doc
 253 distribution will still be created with the minimal documentation set
 254 provided in
 255 .Pa src/share/doc .
 256 .It Ev TARGET
 257 The target hardware platform.
 258 This is analogous to the
 259 .Dq Nm uname Fl m
 260 output.
 261 This is necessary to cross-build some target architectures.
 262 For example, cross-building for PC98 machines requires
 263 .Ev TARGET_ARCH Ns = Ns Li i386
 264 and
 265 .Ev TARGET Ns = Ns Li pc98 .
 266 If not set,
 267 .Ev TARGET
 268 defaults to the current hardware platform.
 269 .It Ev TARGET_ARCH
 270 The target machine processor architecture.
 271 This is analogous to the
 272 .Dq Nm uname Fl p
 273 output.
 274 Set this to cross-build for a different architecture.
 275 If not set,
 276 .Ev TARGET_ARCH
 277 defaults to the current machine architecture, unless
 278 .Ev TARGET
 279 is also set, in which case it defaults to the appropriate
 280 value for that platform.
 281 Typically, one only needs to set
 282 .Ev TARGET .
 283 .El
 284 .Sh FILES
 285 .Bl -tag -compact -width Pa
 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
 294 .It Pa /usr/src/release/generate-release.sh
 295 .El
 296 .Sh EXAMPLES
 297 The following sequence of commands can be used to build a
 298 .Dq "-CURRENT snapshot":
 299 .Bd -literal -offset indent
 300 cd /usr
 301 svn co svn://svn.freebsd.org/base/head src
 302 cd src
 303 make buildworld buildkernel
 304 cd release
 305 make release
 306 make install DESTDIR=/var/freebsd-snapshot
 307 .Ed
 308 .Pp
 309 After running these commands, all produced distribution files (tarballs
 310 for FTP, CD-ROM images, etc.) are available in the
 311 .Pa /var/freebsd-snapshot
 312 directory.
 313 .Pp
 314 The following sequence of commands can be used to build a
 315 .Dq "-CURRENT snapshot"
 316 in a clean environment, including ports and documentation:
 317 .Bd -literal -offset indent
 318 cd /usr/src/release
 319 sh generate-release.sh head /local3/release
 320 .Ed
 321 .Pp
 322 After running these commands, all prepared release files are available in the
 323 .Pa /local3/release/R
 324 directory.
 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 ,
 333 .Xr build 7 ,
 334 .Xr ports 7 ,
 335 .Xr chroot 8 ,
 336 .Xr mtree 8 ,
 337 .Xr sysctl 8
 338 .Rs
 339 .%T "FreeBSD Release Engineering"
 340 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
 341 .Re
 342 .Rs
 343 .%T "FreeBSD Release Engineering of Third Party Packages"
 344 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
 345 .Re
 346 .Rs
 347 .%T "FreeBSD Developers' Handbook"
 348 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
 349 .Re
 350 .Sh HISTORY
 351 .Fx
 352 1.x
 353 used a manual checklist, compiled by
 354 .An Rod Grimes ,
 355 to produce a release.
 356 Apart from being incomplete, the list put a lot of specific demands on
 357 available file systems and was quite torturous to execute.
 358 .Pp
 359 As part of the
 360 .Fx 2.0
 361 release engineering effort, significant
 362 effort was spent getting
 363 .Pa src/release/Makefile
 364 into a shape where it could at least automate most of the tediousness
 365 of building a release in a sterile environment.
 366 .Pp
 367 For the
 368 .Fx 9.0
 369 release,
 370 .Pa src/release/Makefile
 371 was overhauled and the wrapper script
 372 .Pa src/release/generate-release.sh
 373 introduced to support the introduction of a new installer.
 374 .Pp
 375 At near 1000 revisions spread over multiple branches, the
 376 .Xr svn 1
 377 log of
 378 .Pa src/release/Makefile
 379 contains a vivid historical record of some
 380 of the hardships release engineers go through.
 381 .Sh AUTHORS
 382 .Pa src/release/Makefile
 383 was originally written by
 384 .An -nosplit
 385 .An Rod Grimes ,
 386 .An Jordan Hubbard ,
 387 and
 388 .An Poul-Henning Kamp .
 389 This manual page was written by
 390 .An Murray Stokely Aq murray@FreeBSD.org .