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