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 March 18, 2011
  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 .El
 153 .Sh MAKEFILE TARGETS
 154 The release makefile
 155 .Pq Pa src/release/Makefile
 156 is fairly abstruse.
 157 Most developers will only be concerned with the
 158 .Cm release
 159 and
 160 .Cm install
 161 targets.
 162 .\" XXX: Some sort of introduction to this list?  All the others have one.
 163 .Bl -tag -width ".Cm packagesystem"
 164 .It Cm release
 165 Meta-target to build all release media and distributions applicable to this
 166 platform.
 167 .It Cm install
 168 Copy all produced release media to
 169 .Pa ${DESTDIR} .
 170 .It Cm cdrom
 171 Builds installation CD-ROM images. On some systems, this may require that
 172 .Xr mkisofs 8
 173 be installed
 174 .Pq Pa sysutils/cdrtools
 175 and possibly that the
 176 .Xr md 4
 177 (memory disk) device driver be present in the kernel
 178 (either by being compiled in or available as a module). This target
 179 produces files called
 180 .Pa release.iso
 181 and
 182 .Pa bootonly.iso
 183 as its output.
 184 .It Cm memstick
 185 Builds an installation memory stick image named
 186 .Pa memstick .
 187 Not applicable on all platforms. Requires that the
 188 .Xr md 4
 189 (memory disk) device driver be present in the kernel
 190 (either by being compiled in or available as a module).
 191 .It Cm ftp
 192 Creates a directory named
 193 .Pa ftp
 194 containing the distribution files used in network installations
 195 and suitable for upload to an FTP mirror.
 196 .El
 197 .Pp
 198 Major subtargets called by targets above:
 199 .Bl -tag -width ".Cm packagesystem"
 200 .It Cm packagesystem
 201 Generates all the distribution archives (e.g. base, kernel, ports, doc)
 202 applicable on this platform.
 203 .It Cm system
 204 Builds a bootable installation system containing all the distribution files
 205 packaged by the
 206 .Cm packagesystem
 207 target, and suitable for imaging by the
 208 .Cm cdrom
 209 and
 210 .Cm memstick
 211 targets.
 212 .It Cm reldoc
 213 Builds the release documentation.
 214 This includes the release notes,
 215 hardware guide, and installation instructions. Other documentation (e.g.
 216 the Handbook) is built during the
 217 .Cm base.txz
 218 target invoked by
 219 .Cm packagesystem.
 220 .El
 221 .Sh ENVIRONMENT
 222 Optional variables:
 223 .Bl -tag -width ".Va TARGET_ARCH"
 224 .It Va WORLDDIR
 225 Location of a directory containing the src tree. By default, the directory
 226 above the one containing the makefile
 227 .Pq Pa src .
 228 .It Va PORTSDIR
 229 Location of a directory containing the ports tree. By default,
 230 .Pa /usr/ports .
 231 If it is unset or cannot be found, ports will not be included in the release.
 232 .It Va DOCDIR
 233 Location of a directory containing the doc tree. By default,
 234 .Pa /usr/doc .
 235 If it is unset or cannot be found, most documentation will not be included in
 236 the release; see
 237 .Ev NODOC
 238 below.
 239 .It Va NOPORTS
 240 If defined, the Ports Collection will be omitted from the release.
 241 .It Va NOSRC
 242 If set, do not include system source code in the release.
 243 .It Va NODOC
 244 If defined, the SGML-based documentation from the
 245 .Fx
 246 Documentation Project will not be built.
 247 However, the
 248 .Dq doc
 249 distribution will still be created with the minimal documentation set
 250 provided in
 251 .Pa src/share/doc .
 252 .It Va TARGET
 253 The target hardware platform.
 254 This is analogous to the
 255 .Dq Nm uname Fl m
 256 output.
 257 This is necessary to cross-build some target architectures.
 258 For example, cross-building for PC98 machines requires
 259 .Va TARGET_ARCH Ns = Ns Li i386
 260 and
 261 .Va TARGET Ns = Ns Li pc98 .
 262 If not set,
 263 .Va TARGET
 264 defaults to the current hardware platform.
 265 .It Va TARGET_ARCH
 266 The target machine processor architecture.
 267 This is analogous to the
 268 .Dq Nm uname Fl p
 269 output.
 270 Set this to cross-build for a different architecture.
 271 If not set,
 272 .Va TARGET_ARCH
 273 defaults to the current machine architecture, unless
 274 .Va TARGET
 275 is also set, in which case it defaults to the appropriate
 276 value for that platform.
 277 Typically, one only needs to set
 278 .Va TARGET .
 279 .El
 280 .Sh FILES
 281 .Bl -tag -compact
 282 .It Pa /usr/doc/Makefile
 283 .It Pa /usr/doc/share/mk/doc.project.mk
 284 .It Pa /usr/ports/Mk/bsd.port.mk
 285 .It Pa /usr/ports/Mk/bsd.sites.mk
 286 .It Pa /usr/share/examples/etc/make.conf
 287 .It Pa /usr/src/Makefile
 288 .It Pa /usr/src/Makefile.inc1
 289 .It Pa /usr/src/release/Makefile
 290 .It Pa /usr/src/release/generate-release.sh
 291 .El
 292 .Sh EXAMPLES
 293 The following sequence of commands can be used to build a
 294 .Dq "-CURRENT snapshot":
 295 .Bd -literal -offset indent
 296 cd /usr
 297 svn co svn://svn.freebsd.org/base/head src
 298 cd src
 299 make buildworld buildkernel
 300 cd release
 301 make release
 302 make install DESTDIR=/var/freebsd-snapshot
 303 .Ed
 304 .Pp
 305 After running these commands, all produced distribution files (tarballs
 306 for FTP, CD-ROM images, etc.) are available in the
 307 .Pa /var/freebsd-snapshot
 308 directory.
 309 .Pp
 310 The following sequence of commands can be used to build a
 311 .Dq "-CURRENT snapshot"
 312 in a clean environment, including ports and documentation:
 313 .Bd -literal -offset indent
 314 cd /usr/src
 315 make buildworld
 316 cd release
 317 export CVSUP_HOST=cvsupN.freebsd.org
 318 sh generate-release.sh head /local3/release
 319 .Ed
 320 .Pp
 321 After running these commands, all prepared release files are available in the
 322 .Pa /local3/release/R
 323 directory.
 324 .Sh SEE ALSO
 325 .Xr cc 1 ,
 326 .Xr cvs 1 ,
 327 .Xr install 1 ,
 328 .Xr make 1 ,
 329 .Xr svn 1 Pq Pa ports/devel/subversion-freebsd ,
 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 cvs 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 .