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 18, 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.
  54 For this purpose, a script
  55 .Pq Pa src/release/release.sh
  56 is provided to automate these checkouts and then execute
  57 .Dq Li "make release"
  58 in a clean
  59 .Xr chroot 8 .
  60 .Pp
  61 Before attempting to build a release, the user is expected to be
  62 familiar with the contents of
  63 .Xr build 7 ,
  64 and should have experience upgrading systems from source.
  65 .Pp
  66 The release build process requires that
  67 .Pa /usr/obj
  68 be populated with the output of
  69 .Dq Li "make buildworld"
  70 and
  71 .Dq Li "make buildkernel" .
  72 This is necessary to provide the object files for the release or, when
  73 using
  74 .Pa release.sh ,
  75 so that the object files for a complete system can be installed into a clean
  76 .Xr chroot 8
  77 environment.
  78 .Pp
  79 If the target release build is for a different architecture or machine type,
  80 the
  81 .Va TARGET
  82 and
  83 .Va TARGET_ARCH
  84 variables must be used.
  85 See the supported
  86 .Fa release.conf
  87 variables for more information.
  88 .Pp
  89 The release procedure on some architectures may also require that the
  90 .Xr md 4
  91 (memory disk) device driver be present in the kernel
  92 .Pq either by being compiled in or available as a module .
  93 .Pp
  94 This document does not cover source code management, quality
  95 assurance, or other aspects of the release engineering process.
  96 .Sh CLEAN RELEASE GENERATION
  97 Official releases of
  98 .Fx
  99 are produced in a totally clean environment to
 100 ensure consistency between the versions of the src, ports, and doc trees
 101 and to avoid contamination from the host system
 102 .Po such as local patches, changes
 103 to
 104 .Xr make.conf 5 ,
 105 etc.
 106 .Pc .
 107 This is accomplished using the wrapper script
 108 .Pa src/release/release.sh .
 109 .Pp
 110 .Ic release.sh
 111 .Op Fl c Ar release.conf
 112 .Pp
 113 .Ic release.sh
 114 checks out the
 115 .Li src/ ,
 116 .Li ports/ ,
 117 and
 118 .Li doc/
 119 trees to
 120 .Va CHROOTDIR ,
 121 then calls
 122 .Dq Li "make buildworld"
 123 and
 124 .Dq Li "make installworld"
 125 to generate a
 126 .Xr chroot 8
 127 environment.
 128 Next,
 129 .Dq Li "make release"
 130 is run within the
 131 .Xr chroot 8
 132 environment and places the result in
 133 .Pa $CHROOTDIR/R .
 134 .Pp
 135 The optional
 136 .Fa release.conf
 137 configuration file supports the following variables:
 138 .Bl -tag -width Ev
 139 .It Va CHROOTDIR
 140 The directory within which the release will be built.
 141 .It Va SVNROOT
 142 The
 143 .Xr svn 1
 144 host used to check out the various trees.
 145 Defaults to
 146 .Pa svn://svn.FreeeBSD.org .
 147 .It Va SRCBRANCH
 148 The
 149 .Li src/
 150 branch to use.
 151 Defaults to
 152 .Va head/@rHEAD .
 153 .It Va DOCBRANCH
 154 The
 155 .Li doc/
 156 branch to use.
 157 Defaults to
 158 .Va head/@rHEAD .
 159 .It Va PORTBRANCH
 160 The
 161 .Li ports/
 162 branch to use.
 163 Defaults to
 164 .Va head/@rHEAD .
 165 .It Va TARGET
 166 The target machine type for cross-building a release.
 167 .It Va TARGET_ARCH
 168 The target machine architecture for cross-building a release.
 169 .Pp
 170 For the supported list of
 171 .Va TARGET
 172 and
 173 .Va TARGET_ARCH
 174 combinations, consult the output of
 175 .Dq make targets
 176 as documented in
 177 .Xr build 7 .
 178 .It Va KERNEL
 179 The target kernel configuration to use.
 180 Defaults to
 181 .Va GENERIC .
 182 Multiple
 183 .Va KERNEL
 184 entries may be specified.
 185 .It Va MAKE_CONF
 186 The
 187 .Xr make.conf 5
 188 to use for the release build.
 189 Defaults to
 190 .Fa /dev/null
 191 to prevent polluting the release with local system changes.
 192 .It Va SRC_CONF
 193 The
 194 .Xr src.conf 5
 195 to use for the release build.
 196 Defaults to
 197 .Fa /dev/null
 198 to prevent polluting the release with local system changes.
 199 .It Va MAKE_FLAGS
 200 Additional flags to pass to
 201 .Xr make 1 .
 202 .It Va WORLD_FLAGS
 203 Additional flags to pass to
 204 .Xr make 1
 205 during the
 206 .Dq buildworld
 207 phase.
 208 Defaults to setting the number of
 209 .Xr make 1
 210 jobs
 211 .Pq Ar -j
 212 to the number of CPUs available on a SMP-capable system.
 213 .It Va KERNEL_FLAGS
 214 Additional flags to pass to
 215 .Xr make 1
 216 during the
 217 .Dq buildkernel
 218 phase.
 219 Defaults to setting the number of
 220 .Xr make 1
 221 jobs
 222 .Pq Ar -j
 223 to half the number of CPUs available on a SMP-capable system.
 224 .It Va NODOC
 225 Set to a non-empty value to skip the
 226 .Li doc/
 227 tree checkout.
 228 When set,
 229 .Va NODOC
 230 will prevent the
 231 .Fa doc.txz
 232 distribution package from being created.
 233 .It Va NODVD
 234 Set to a non-empty value to skip the
 235 .Cm dvdrom
 236 target.
 237 .It Va NOPORTS
 238 Set to a non-empty value to skip the
 239 .Li ports/
 240 tree checkout.
 241 When set,
 242 .Va NOPORTS
 243 will prevent the
 244 .Fa ports.txz
 245 distribution package from being created.
 246 Setting this also sets
 247 .Va NODOC .
 248 .El
 249 .Sh MAKEFILE TARGETS
 250 The release makefile
 251 .Pq Pa src/release/Makefile
 252 is fairly abstruse.
 253 Most developers will only be concerned with the
 254 .Cm release
 255 and
 256 .Cm install
 257 targets.
 258 .\" XXX: Some sort of introduction to this list?  All the others have one.
 259 .Bl -tag -width ".Cm packagesystem"
 260 .It Cm release
 261 Meta-target to build all release media and distributions applicable to this
 262 platform.
 263 .It Cm install
 264 Copy all produced release media to
 265 .Pa ${DESTDIR} .
 266 .It Cm cdrom
 267 Builds installation CD-ROM images.
 268 This may require the
 269 .Xr md 4
 270 (memory disk) device driver be present in the kernel
 271 (either by being compiled in or available as a module).
 272 This target produces files called
 273 .Pa disc1.iso
 274 and
 275 .Pa bootonly.iso
 276 as its output.
 277 .It Cm dvdrom
 278 Builds installation DVD-ROM images.
 279 This may require the
 280 .Xr md 4
 281 (memory disk) device driver be present in the kernel
 282 (either by being compiled in or available as a module).
 283 This target produces the
 284 .Pa dvd1.iso
 285 file as its output.
 286 .It Cm memstick
 287 Builds an installation memory stick image named
 288 .Pa memstick.img .
 289 Not applicable on all platforms.
 290 Requires that the
 291 .Xr md 4
 292 .Pq memory disk
 293 device driver be present in the kernel
 294 .Pq either by being compiled in or available as a module .
 295 .It Cm ftp
 296 Creates a directory named
 297 .Pa ftp
 298 containing the distribution files used in network installations
 299 and suitable for upload to an FTP mirror.
 300 .El
 301 .Pp
 302 Major subtargets called by targets above:
 303 .Bl -tag -width ".Cm packagesystem"
 304 .It Cm packagesystem
 305 Generates all the distribution archives
 306 .Pq base, kernel, ports, doc
 307 applicable on this platform.
 308 .It Cm system
 309 Builds a bootable installation system containing all the distribution files
 310 packaged by the
 311 .Cm packagesystem
 312 target, and suitable for imaging by the
 313 .Cm cdrom ,
 314 .Cm dvdrom
 315 and
 316 .Cm memstick
 317 targets.
 318 .It Cm reldoc
 319 Builds the release documentation.
 320 This includes the release notes,
 321 hardware guide, and installation instructions.
 322 Other documentation, such as the Handbook,
 323 is built during the
 324 .Cm base.txz
 325 target invoked by
 326 .Cm packagesystem .
 327 .El
 328 .Sh ENVIRONMENT
 329 Optional variables:
 330 .Bl -tag -width ".Ev TARGET_ARCH"
 331 .It Ev OSRELEASE
 332 Optional base name for generated media images
 333 .Pq e.g., FreeBSD-9.0-RC2-amd64 .
 334 Defaults to the output of
 335 .Ic `uname -s`-`uname -r`-`uname -p`
 336 within the chroot.
 337 .It Ev WORLDDIR
 338 Location of a directory containing the src tree.
 339 By default, the directory
 340 above the one containing the makefile
 341 .Pq Pa src .
 342 .It Ev PORTSDIR
 343 Location of a directory containing the ports tree.
 344 By default,
 345 .Pa /usr/ports .
 346 If it is unset or cannot be found, ports will not be included in the release.
 347 .It Ev DOCDIR
 348 Location of a directory containing the doc tree.
 349 By default,
 350 .Pa /usr/doc .
 351 If it is unset or cannot be found, most documentation will not be included in
 352 the release; see
 353 .Ev NODOC
 354 below.
 355 .It Ev NOPORTS
 356 If defined, the Ports Collection will be omitted from the release.
 357 .It Ev NOSRC
 358 If set, do not include system source code in the release.
 359 .It Ev NODOC
 360 If defined, the XML-based documentation from the
 361 .Fx
 362 Documentation Project will not be built.
 363 However, the
 364 .Dq doc
 365 distribution will still be created with the minimal documentation set
 366 provided in
 367 .Pa src/share/doc .
 368 .It Ev TARGET
 369 The target hardware platform.
 370 This is analogous to the
 371 .Dq Nm uname Fl m
 372 output.
 373 This is necessary to cross-build some target architectures.
 374 For example, cross-building for PC98 machines requires
 375 .Ev TARGET_ARCH Ns = Ns Li i386
 376 and
 377 .Ev TARGET Ns = Ns Li pc98 .
 378 If not set,
 379 .Ev TARGET
 380 defaults to the current hardware platform.
 381 .It Ev TARGET_ARCH
 382 The target machine processor architecture.
 383 This is analogous to the
 384 .Dq Nm uname Fl p
 385 output.
 386 Set this to cross-build for a different architecture.
 387 If not set,
 388 .Ev TARGET_ARCH
 389 defaults to the current machine architecture, unless
 390 .Ev TARGET
 391 is also set, in which case it defaults to the appropriate
 392 value for that platform.
 393 Typically, one only needs to set
 394 .Ev TARGET .
 395 .El
 396 .Sh FILES
 397 .Bl -tag -compact -width Pa
 398 .It Pa /usr/doc/Makefile
 399 .It Pa /usr/doc/share/mk/doc.project.mk
 400 .It Pa /usr/ports/Mk/bsd.port.mk
 401 .It Pa /usr/ports/Mk/bsd.sites.mk
 402 .It Pa /usr/share/examples/etc/make.conf
 403 .It Pa /usr/src/Makefile
 404 .It Pa /usr/src/Makefile.inc1
 405 .It Pa /usr/src/release/Makefile
 406 .It Pa /usr/src/release/release.sh
 407 .It Pa /usr/src/release/release.conf.sample
 408 .El
 409 .Sh EXAMPLES
 410 The following sequence of commands can be used to build a
 411 .Dq "-CURRENT snapshot":
 412 .Bd -literal -offset indent
 413 cd /usr
 414 svn co svn://svn.freebsd.org/base/head src
 415 cd src
 416 make buildworld buildkernel
 417 cd release
 418 make release
 419 make install DESTDIR=/var/freebsd-snapshot
 420 .Ed
 421 .Pp
 422 After running these commands, all produced distribution files (tarballs
 423 for FTP, CD-ROM images, etc.) are available in the
 424 .Pa /var/freebsd-snapshot
 425 directory.
 426 .Pp
 427 The following sequence of commands can be used to build a
 428 .Dq "-CURRENT snapshot"
 429 in a clean environment, including ports and documentation:
 430 .Bd -literal -offset indent
 431 cd /usr/src/release
 432 sh release.sh
 433 .Ed
 434 .Pp
 435 Optionally, a configuration file can be used customize the release build,
 436 such as the subversion revision to use, the branch of the subversion tree for
 437 .Li src/ ,
 438 .Li ports/ ,
 439 and
 440 .Li doc/ .
 441 .Bd -literal -offset indent
 442 cd /usr/src/release
 443 sh release.sh -c $HOME/release.conf
 444 .Ed
 445 .Pp
 446 After running these commands, all prepared release files are available in the
 447 .Pa /scratch
 448 directory.
 449 The target directory can be changed by specifying the
 450 .Va CHROOTDIR
 451 variable in
 452 .Li release.conf .
 453 .Sh SEE ALSO
 454 .Xr cc 1 ,
 455 .Xr install 1 ,
 456 .Xr make 1 ,
 457 .Xr svn 1 Pq Pa ports/devel/subversion ,
 458 .Xr uname 1 ,
 459 .Xr md 4 ,
 460 .Xr make.conf 5 ,
 461 .Xr build 7 ,
 462 .Xr ports 7 ,
 463 .Xr chroot 8 ,
 464 .Xr mtree 8 ,
 465 .Xr sysctl 8
 466 .Rs
 467 .%T "FreeBSD Release Engineering"
 468 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
 469 .Re
 470 .Rs
 471 .%T "FreeBSD Release Engineering of Third Party Packages"
 472 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
 473 .Re
 474 .Rs
 475 .%T "FreeBSD Developers' Handbook"
 476 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
 477 .Re
 478 .Sh HISTORY
 479 .Fx
 480 1.x
 481 used a manual checklist, compiled by
 482 .An Rod Grimes ,
 483 to produce a release.
 484 Apart from being incomplete, the list put a lot of specific demands on
 485 available file systems and was quite torturous to execute.
 486 .Pp
 487 As part of the
 488 .Fx 2.0
 489 release engineering effort, significant
 490 effort was spent getting
 491 .Pa src/release/Makefile
 492 into a shape where it could at least automate most of the tediousness
 493 of building a release in a sterile environment.
 494 .Pp
 495 For the
 496 .Fx 9.0
 497 release,
 498 .Pa src/release/Makefile
 499 was overhauled and the wrapper script
 500 .Pa src/release/generate-release.sh
 501 introduced to support the introduction of a new installer.
 502 .Pp
 503 For the
 504 .Fx 9.2
 505 release,
 506 .Pa src/release/release.sh
 507 was introduced to support per-build configuration files.
 508 .Pa src/release/release.sh
 509 is heavily based on the
 510 .Pa src/release/generate-release.sh
 511 script.
 512 .Pp
 513 At near 1000 revisions spread over multiple branches, the
 514 .Xr svn 1
 515 log of
 516 .Pa src/release/Makefile
 517 contains a vivid historical record of some
 518 of the hardships release engineers go through.
 519 .Sh AUTHORS
 520 .Pa src/release/Makefile
 521 was originally written by
 522 .An -nosplit
 523 .An Rod Grimes ,
 524 .An Jordan Hubbard ,
 525 and
 526 .An Poul-Henning Kamp .
 527 .Pp
 528 This manual page was originally written by
 529 .An Murray Stokely Aq murray@FreeBSD.org .
 530 .Pp
 531 It was updated by
 532 .An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org
 533 to include the
 534 .Fa generate-release.sh
 535 script used for the
 536 .Fx 9.0
 537 release cycle.
 538 .Pp
 539 It was later updated by
 540 .An Glen Barber Aq gjb@FreeBSD.org
 541 to include the
 542 .Fa release.sh
 543 script used for the
 544 .Fx 9.2
 545 release cycle.