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