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