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 December 2, 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 NOPORTS
 234 Set to a non-empty value to skip the
 235 .Li ports/
 236 tree checkout.
 237 When set,
 238 .Va NOPORTS
 239 will prevent the
 240 .Fa ports.txz
 241 distribution package from being created.
 242 Setting this also sets
 243 .Va NODOC .
 244 .It Va WITH_DVD
 245 Set to a non-empty value to include the
 246 .Cm dvdrom
 247 target.
 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 mini-memstick
 296 Similar to
 297 .Cm memstick ,
 298 with the exception that the installation distribution sets
 299 are not included.
 300 .It Cm ftp
 301 Creates a directory named
 302 .Pa ftp
 303 containing the distribution files used in network installations
 304 and suitable for upload to an FTP mirror.
 305 .El
 306 .Pp
 307 Major subtargets called by targets above:
 308 .Bl -tag -width ".Cm packagesystem"
 309 .It Cm packagesystem
 310 Generates all the distribution archives
 311 .Pq base, kernel, ports, doc
 312 applicable on this platform.
 313 .It Cm system
 314 Builds a bootable installation system containing all the distribution files
 315 packaged by the
 316 .Cm packagesystem
 317 target, and suitable for imaging by the
 318 .Cm cdrom ,
 319 .Cm dvdrom
 320 and
 321 .Cm memstick
 322 targets.
 323 .It Cm reldoc
 324 Builds the release documentation.
 325 This includes the release notes,
 326 hardware guide, and installation instructions.
 327 Other documentation, such as the Handbook,
 328 is built during the
 329 .Cm base.txz
 330 target invoked by
 331 .Cm packagesystem .
 332 .El
 333 .Sh ENVIRONMENT
 334 Optional variables:
 335 .Bl -tag -width ".Ev TARGET_ARCH"
 336 .It Ev OSRELEASE
 337 Optional base name for generated media images
 338 .Pq e.g., FreeBSD-9.0-RC2-amd64 .
 339 Defaults to the output of
 340 .Ic `uname -s`-`uname -r`-`uname -p`
 341 within the chroot.
 342 .It Ev WORLDDIR
 343 Location of a directory containing the src tree.
 344 By default, the directory
 345 above the one containing the makefile
 346 .Pq Pa src .
 347 .It Ev PORTSDIR
 348 Location of a directory containing the ports tree.
 349 By default,
 350 .Pa /usr/ports .
 351 If it is unset or cannot be found, ports will not be included in the release.
 352 .It Ev DOCDIR
 353 Location of a directory containing the doc tree.
 354 By default,
 355 .Pa /usr/doc .
 356 If it is unset or cannot be found, most documentation will not be included in
 357 the release; see
 358 .Ev NODOC
 359 below.
 360 .It Ev NOPORTS
 361 If defined, the Ports Collection will be omitted from the release.
 362 .It Ev NOSRC
 363 If set, do not include system source code in the release.
 364 .It Ev NODOC
 365 If defined, the XML-based documentation from the
 366 .Fx
 367 Documentation Project will not be built.
 368 However, the
 369 .Dq doc
 370 distribution will still be created with the minimal documentation set
 371 provided in
 372 .Pa src/share/doc .
 373 .It Ev TARGET
 374 The target hardware platform.
 375 This is analogous to the
 376 .Dq Nm uname Fl m
 377 output.
 378 This is necessary to cross-build some target architectures.
 379 For example, cross-building for PC98 machines requires
 380 .Ev TARGET_ARCH Ns = Ns Li i386
 381 and
 382 .Ev TARGET Ns = Ns Li pc98 .
 383 If not set,
 384 .Ev TARGET
 385 defaults to the current hardware platform.
 386 .It Ev TARGET_ARCH
 387 The target machine processor architecture.
 388 This is analogous to the
 389 .Dq Nm uname Fl p
 390 output.
 391 Set this to cross-build for a different architecture.
 392 If not set,
 393 .Ev TARGET_ARCH
 394 defaults to the current machine architecture, unless
 395 .Ev TARGET
 396 is also set, in which case it defaults to the appropriate
 397 value for that platform.
 398 Typically, one only needs to set
 399 .Ev TARGET .
 400 .El
 401 .Sh FILES
 402 .Bl -tag -compact -width Pa
 403 .It Pa /usr/doc/Makefile
 404 .It Pa /usr/doc/share/mk/doc.project.mk
 405 .It Pa /usr/ports/Mk/bsd.port.mk
 406 .It Pa /usr/ports/Mk/bsd.sites.mk
 407 .It Pa /usr/share/examples/etc/make.conf
 408 .It Pa /usr/src/Makefile
 409 .It Pa /usr/src/Makefile.inc1
 410 .It Pa /usr/src/release/Makefile
 411 .It Pa /usr/src/release/release.sh
 412 .It Pa /usr/src/release/release.conf.sample
 413 .El
 414 .Sh EXAMPLES
 415 The following sequence of commands can be used to build a
 416 .Dq "-CURRENT snapshot":
 417 .Bd -literal -offset indent
 418 cd /usr
 419 svn co svn://svn.freebsd.org/base/head src
 420 cd src
 421 make buildworld buildkernel
 422 cd release
 423 make release
 424 make install DESTDIR=/var/freebsd-snapshot
 425 .Ed
 426 .Pp
 427 After running these commands, all produced distribution files (tarballs
 428 for FTP, CD-ROM images, etc.) are available in the
 429 .Pa /var/freebsd-snapshot
 430 directory.
 431 .Pp
 432 The following sequence of commands can be used to build a
 433 .Dq "-CURRENT snapshot"
 434 in a clean environment, including ports and documentation:
 435 .Bd -literal -offset indent
 436 cd /usr/src/release
 437 sh release.sh
 438 .Ed
 439 .Pp
 440 Optionally, a configuration file can be used customize the release build,
 441 such as the subversion revision to use, the branch of the subversion tree for
 442 .Li src/ ,
 443 .Li ports/ ,
 444 and
 445 .Li doc/ .
 446 .Bd -literal -offset indent
 447 cd /usr/src/release
 448 sh release.sh -c $HOME/release.conf
 449 .Ed
 450 .Pp
 451 After running these commands, all prepared release files are available in the
 452 .Pa /scratch
 453 directory.
 454 The target directory can be changed by specifying the
 455 .Va CHROOTDIR
 456 variable in
 457 .Li release.conf .
 458 .Sh SEE ALSO
 459 .Xr cc 1 ,
 460 .Xr install 1 ,
 461 .Xr make 1 ,
 462 .Xr svn 1 Pq Pa ports/devel/subversion ,
 463 .Xr uname 1 ,
 464 .Xr md 4 ,
 465 .Xr make.conf 5 ,
 466 .Xr build 7 ,
 467 .Xr ports 7 ,
 468 .Xr chroot 8 ,
 469 .Xr mtree 8 ,
 470 .Xr sysctl 8
 471 .Rs
 472 .%T "FreeBSD Release Engineering"
 473 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
 474 .Re
 475 .Rs
 476 .%T "FreeBSD Release Engineering of Third Party Packages"
 477 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
 478 .Re
 479 .Rs
 480 .%T "FreeBSD Developers' Handbook"
 481 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
 482 .Re
 483 .Sh HISTORY
 484 .Fx
 485 1.x
 486 used a manual checklist, compiled by
 487 .An Rod Grimes ,
 488 to produce a release.
 489 Apart from being incomplete, the list put a lot of specific demands on
 490 available file systems and was quite torturous to execute.
 491 .Pp
 492 As part of the
 493 .Fx 2.0
 494 release engineering effort, significant
 495 effort was spent getting
 496 .Pa src/release/Makefile
 497 into a shape where it could at least automate most of the tediousness
 498 of building a release in a sterile environment.
 499 .Pp
 500 For the
 501 .Fx 9.0
 502 release,
 503 .Pa src/release/Makefile
 504 was overhauled and the wrapper script
 505 .Pa src/release/generate-release.sh
 506 introduced to support the introduction of a new installer.
 507 .Pp
 508 For the
 509 .Fx 9.2
 510 release,
 511 .Pa src/release/release.sh
 512 was introduced to support per-build configuration files.
 513 .Pa src/release/release.sh
 514 is heavily based on the
 515 .Pa src/release/generate-release.sh
 516 script.
 517 .Pp
 518 At near 1000 revisions spread over multiple branches, the
 519 .Xr svn 1
 520 log of
 521 .Pa src/release/Makefile
 522 contains a vivid historical record of some
 523 of the hardships release engineers go through.
 524 .Sh AUTHORS
 525 .Pa src/release/Makefile
 526 was originally written by
 527 .An -nosplit
 528 .An Rod Grimes ,
 529 .An Jordan Hubbard ,
 530 and
 531 .An Poul-Henning Kamp .
 532 .Pp
 533 This manual page was originally written by
 534 .An Murray Stokely Aq murray@FreeBSD.org .
 535 .Pp
 536 It was updated by
 537 .An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org
 538 to include the
 539 .Fa generate-release.sh
 540 script used for the
 541 .Fx 9.0
 542 release cycle.
 543 .Pp
 544 It was later updated by
 545 .An Glen Barber Aq gjb@FreeBSD.org
 546 to include the
 547 .Fa release.sh
 548 script used for the
 549 .Fx 9.2
 550 release cycle.