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 August 17, 2009
  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 CVS repository in
  41 .Pa src/release .
  42 A complete release can actually be built with only a single command,
  43 including the creation of ISO images suitable for burning to CD-ROM,
  44 installation floppies, and an FTP install directory.
  45 This command is aptly named
  46 .Dq Li "make release" .
  47 .Pp
  48 Before attempting to build a release, the user is expected to be
  49 familiar with the contents of
  50 .Xr build 7 ,
  51 and should have experience upgrading systems from source.
  52 The release build process requires that
  53 .Pa /usr/obj
  54 be populated with the output of
  55 a native
  56 .Dq Li "make buildworld"
  57 compiled from sources matching the currently running kernel.
  58 This is necessary so that the object files for a complete system can
  59 be installed into a clean
  60 .Xr chroot 8
  61 environment.
  62 The release procedure also requires that the
  63 .Xr md 4
  64 (memory disk) device driver be present in the kernel
  65 (either by being compiled in or available as a module).
  66 .Pp
  67 This document does not cover source code management, quality
  68 assurance, or other aspects of the release engineering process.
  69 .Sh TARGETS
  70 The release makefile
  71 .Pq Pa src/release/Makefile
  72 is fairly abstruse.
  73 Most developers will only be concerned with the
  74 .Cm release
  75 target.
  76 .\" XXX: Some sort of introduction to this list?  All the others have one.
  77 .Bl -tag -width ".Cm package-split"
  78 .It Cm release
  79 Uses
  80 .Dq Li "make installworld"
  81 to install a clean system into a
  82 .Xr chroot 8
  83 environment on the file system.
  84 Checks out the specified version of the source code and then rebuilds
  85 the entire system in the clean environment with
  86 .Dq Li "make buildworld" .
  87 The detailed steps that follow are then executed to package up the
  88 different distributions, build the installation floppy disks, build
  89 release documentation, and so on.
  90 .Pp
  91 This target must be built as root with the
  92 .Va kern.securelevel
  93 sysctl set to \-1 (the default).
  94 .It Cm rerelease
  95 Assumes that the output of a release build has been manually modified,
  96 and performs the minimal number of steps to rebuild the release using
  97 the intermediate output of the previous
  98 .Dq Li "make release" .
  99 .It Cm floppies
 100 Generate a new set of boot and fixit floppies.
 101 This will call the
 102 .Cm release.4 ,
 103 .Cm release.8 ,
 104 .Cm floppies.1 ,
 105 .Cm floppies.2 ,
 106 and
 107 .Cm floppies.3
 108 targets to re-generate the floppy images of a previous
 109 .Dq Li "make release" .
 110 This is most often used to build custom boot floppies.
 111 .It Cm package-split
 112 Generates the portions of the disc 1 and disc 2 images related to packages.
 113 It uses the list of desired packages from the
 114 .Pa src/release/scripts/package-split.py
 115 script to pull packages out of a package build provided by the ports team
 116 and organize them appropriately.
 117 The resulting directory can then be passed to
 118 .Dq Li "make release"
 119 via the
 120 .Va CD_PACKAGE_TREE
 121 variable to populate the ISO images built by the
 122 .Cm iso.1
 123 target with the correct package related bits.
 124 .El
 125 .Pp
 126 Targets called by
 127 .Dq Li "make release" :
 128 .Bl -tag -width ".Cm fetch-distfiles"
 129 .It Cm release.1
 130 Cleans out the
 131 .Pa ${CHROOTDIR}/R
 132 directory and uses
 133 .Xr mtree 8
 134 to build the directory hierarchy for the system.
 135 .It Cm release.2
 136 Installs the system into the distribution directories.
 137 .It Cm release.3
 138 Makes and installs the
 139 .Pa GENERIC
 140 kernel as well as any other kernels listed in
 141 .Va KERNELS .
 142 .It Cm release.4
 143 Uses
 144 .Xr crunchgen 1
 145 to build
 146 .Dq crunched
 147 binaries to live on the installation floppies.
 148 .It Cm release.5
 149 Builds synthetic distributions, and cleans up the previously built
 150 distribution trees.
 151 .It Cm release.6
 152 Creates tarballs of the assembled distribution trees.
 153 .It Cm release.7
 154 Makes source distributions.
 155 .It Cm release.8
 156 Creates the MFS root file systems.
 157 .It Cm floppies.1
 158 Creates the boot and kernel floppies.
 159 .It Cm floppies.2
 160 Creates the fixit floppy.
 161 .It Cm floppies.3
 162 Finalizes the
 163 .Pa ${CHROOTDIR}/R/ftp/stage/floppies
 164 staging directory.
 165 .It Cm ftp.1
 166 Sets up a suitable area for FTP installations in
 167 .Pa ${CHROOTDIR}/R/ftp .
 168 .It Cm cdrom.1
 169 Create the layout for the live file system CD-ROM image in
 170 .Pa ${CHROOTDIR}/R/cdrom .
 171 .It Cm cdrom.2
 172 Create the layout for the first and second CD-ROM images.
 173 .It Cm cdrom.3
 174 Create the layout for the boot-only CD-ROM image and the boot-only UFS
 175 miniroot image.
 176 .It Cm iso.1
 177 Builds ISO images (installation and
 178 .Dq live
 179 file system) from the CD-ROM release area
 180 (disabled by default, see
 181 .Va MAKE_ISOS
 182 below).
 183 .It Cm fetch-distfiles
 184 Fetches distfiles needed during the release build that are not already in
 185 .Va RELEASEDISTFILES .
 186 .It Cm doc.1
 187 Builds all of the necessary tools to turn the
 188 .Fx
 189 Documentation Project source documents (SGML, XML) into HTML
 190 and text documents that will accompany the release.
 191 Also, builds and installs the actual user documentation.
 192 This includes the Handbook, FAQ, articles, and so on.
 193 .It Cm doc.2
 194 Builds the release documentation.
 195 This includes the release notes,
 196 hardware guide, and installation instructions.
 197 .El
 198 .Sh ENVIRONMENT
 199 Variables that must be specified:
 200 .Bl -tag -width ".Va CHROOTDIR"
 201 .It Va CHROOTDIR
 202 The directory to be used as the
 203 .Xr chroot 8
 204 environment for the entire release build.
 205 .\" XXX: I recommend against hardcoding specific numbers like "2.3" here;
 206 .\" XXX: perhaps it should be replaced with something to the effect of
 207 .\" XXX: "we do not know how much space you'll need, but make sure you have
 208 .\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number,
 209 .\" XXX: but at least it looks less like a decree and more like an estimate.
 210 This file system should have at least 3.2 gigabytes of free space on the
 211 i386 architecture.
 212 .It Va CVSROOT
 213 The location of the
 214 .Fx
 215 CVS repository.
 216 This path name is in reference to the real system root,
 217 .Em not
 218 the root of the
 219 .Xr chroot 8
 220 directory tree.
 221 .El
 222 .Pp
 223 Optional variables:
 224 .Bl -tag -width ".Va NO_PREFETCHDISTFILES"
 225 .It Va BUILDNAME
 226 The name of the release to be built.
 227 This is used to set the
 228 .Va RELEASE
 229 value in
 230 .Pa sys/conf/newvers.sh ,
 231 which affects the output of
 232 .Xr uname 1 .
 233 If not set, a name with the timestamp and the
 234 .Dq Li -SNAP
 235 suffix will be generated.
 236 .It Va CD_PACKAGE_TREE
 237 A directory containing extra bits for the first and second CD-ROM images.
 238 The extra files for the first disc should be in
 239 .Pa ${CD_PACKAGE_TREE}/disc1
 240 and the extra files for the second disc should be in
 241 .Pa ${CD_PACKAGE_TREE}/disc2 .
 242 Typically, this variable will be set to the output directory of an earlier
 243 invocation of the
 244 .Cm package-split
 245 target.
 246 .It Va CVSARGS
 247 Additional arguments for
 248 .Xr cvs 1
 249 that come before the subcommands such as
 250 .Dq Li "-qR" .
 251 .It Va CVSCMDARGS
 252 Additional arguments for
 253 .Xr cvs 1
 254 .Ic checkout
 255 and
 256 .Ic update
 257 commands.
 258 For example, setting this variable to
 259 .Dq Li "-D '01/01/2002 00:00:00 GMT'"
 260 for
 261 .Dq Li "make release"
 262 or
 263 .Dq Li "make rerelease"
 264 will ask
 265 .Xr cvs 1
 266 to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively.
 267 .It Va DOC_LANG
 268 The list of languages and encodings the SGML-based documentation
 269 should be built for.
 270 If not set, the documentation is built for all available languages.
 271 .It Va DOCRELEASETAG
 272 The CVS tag to use when checking out the documentation tree.
 273 Usually,
 274 the head of the documentation tree is used by default.
 275 If
 276 .Va RELEASETAG
 277 specifies a release tag,
 278 then the associated release version is used as the default instead.
 279 .It Va EXTLOCALDIR
 280 The directory that will be copied to
 281 .Pa ${CHROOTDIR}/usr/local .
 282 .It Va EXTSRCDIR
 283 The directory specified by this variable will be copied into
 284 .Pa ${CHROOTDIR}/usr/src
 285 instead of that directory being populated by a CVS checkout.
 286 For
 287 .Dq Li "rerelease" ,
 288 this will NOT be copied; cvs update will be used instead.
 289 .It Va EXTDOCDIR
 290 The directory specified by this variable will be copied into
 291 .Pa ${CHROOTDIR}/usr/doc .
 292 For
 293 .Dq Li "rerelease" ,
 294 this will NOT be copied again.
 295 .It Va EXTPORTSDIR
 296 The directory specified by this variable will be copied into
 297 .Pa ${CHROOTDIR}/usr/ports .
 298 For
 299 .Dq Li "rerelease" ,
 300 this will do NOTHING.
 301 .It Va KERNEL_FLAGS
 302 The contents of this variable are passed to
 303 .Xr make 1
 304 when building kernels during the release build.
 305 For example, setting this variable to
 306 .Dq Li "-j 4"
 307 will instruct
 308 .Xr make 1
 309 to execute up to four processes at a time.
 310 .It Va KERNELS
 311 Specifies a list of additional kernel configurations to compile and
 312 install into the
 313 .Dq base
 314 distribution.
 315 Each kernel is installed into
 316 .Pa /boot/<config>
 317 so that it can be booted from the loader via
 318 .Dq Li "boot <config>" .
 319 .It Va LOCAL_PATCHES
 320 Patch files against
 321 .Pa /usr/src
 322 that will be applied in the
 323 .Xr chroot 8
 324 environment before the release build begins.
 325 .It Va PATCH_FLAGS
 326 Arguments for the
 327 .Xr patch 1
 328 command used to apply
 329 .Va LOCAL_PATCHES
 330 patch file.
 331 .It Va LOCAL_SCRIPT
 332 A script that will be run in the
 333 .Xr chroot 8
 334 environment immediately after any local patches are applied.
 335 .It Va MAKE_DVD
 336 If defined, build a bootable ISO DVD image in the CD-ROM
 337 stage directory.
 338 This option may not be available for all architectures.
 339 .It Va MAKE_ISOS
 340 If defined, bootable ISO CD-ROM images will be created from the
 341 contents of the CD-ROM stage directory.
 342 .It Va NOCDROM
 343 If defined, the CD-ROM stage directories will not be created.
 344 .It Va NODOC
 345 If defined, the SGML-based documentation from the
 346 .Fx
 347 Documentation Project will not be built.
 348 However, the
 349 .Dq doc
 350 distribution will still be created with the minimal documentation set
 351 provided in
 352 .Pa src/share/doc .
 353 .It Va NO_FLOPPIES
 354 If defined, no boot and fixit floppy disk images will be created (for those
 355 platforms supporting them).
 356 .It Va NOPORTS
 357 If defined, the Ports Collection will be omitted from the release.
 358 .It Va PORTSRELEASETAG
 359 The CVS tag to use when checking out the ports tree.
 360 Usually,
 361 the head of the ports tree is used by default.
 362 If
 363 .Va RELEASETAG
 364 specifies a release tag,
 365 then the associated release version is used as the default instead.
 366 .It Va NO_PREFETCHDISTFILES
 367 If this variable is defined,
 368 then distfiles needed during the release build will not be downloaded prior to
 369 entering the
 370 .Xr chroot 8
 371 environment.
 372 Note that if
 373 .Va NO_PREFETCHDISTFILES
 374 is not set,
 375 the fetching is done after any distfiles are obtained via
 376 .Va RELEASEDISTFILES .
 377 .It Va RELEASEDISTFILES
 378 The directory where the distribution files for ports required by the
 379 release build can be found.
 380 This may save a significant amount of time over downloading the
 381 distfiles through a slow link.
 382 .It Va RELEASENOUPDATE
 383 If this variable is defined for
 384 .Dq Li "make rerelease" ,
 385 the source code will not be updated with
 386 .Dq Li "cvs update" .
 387 .It Va RELEASETAG
 388 The CVS tag corresponding to the release that is to be built.
 389 If undefined, the release will be built from the
 390 .Dv HEAD
 391 of the CVS tree
 392 (a
 393 .Dq "-CURRENT snapshot" ) .
 394 .It Va SEPARATE_LIVEFS
 395 Store the live file system on its own CD-ROM image rather than placing it on
 396 the first disc.
 397 .It Va SVNCMDARGS
 398 Additional arguments for svn
 399 .Ic checkout
 400 and
 401 .Ic switch
 402 commands.
 403 .It Va SVNROOT
 404 The location of the FreeBSD SVN source repository.
 405 If this variable is set,
 406 then the source tree will be extracted using Subversion rather than
 407 CVS.
 408 .It Va SVNBRANCH
 409 The branch to check out from a SVN source repository.
 410 It is specified as a path such as
 411 .Pa head
 412 or
 413 .Pa stable/7 .
 414 If this variable is not set,
 415 then the branch that corresponds to the current value of
 416 .Va RELEASETAG
 417 will be used.
 418 If neither
 419 .Va SVNBRANCH
 420 nor
 421 .Va RELEASETAG
 422 are set,
 423 then the
 424 .Pa head
 425 branch will be used.
 426 .It Va TARGET_ARCH
 427 The target machine processor architecture.
 428 This is analogous to the
 429 .Dq Nm uname Fl p
 430 output.
 431 Set this to cross-build for a different architecture.
 432 .It Va TARGET
 433 The target hardware platform.
 434 This is analogous to the
 435 .Dq Nm uname Fl m
 436 output.
 437 This is necessary to cross-build some target architectures.
 438 For example, cross-building for PC98 machines requires
 439 .Va TARGET_ARCH Ns = Ns Li i386
 440 and
 441 .Va TARGET Ns = Ns Li pc98 .
 442 .It Va WORLDDIR
 443 The directory where
 444 .Dq Li "make buildworld"
 445 was run; defaults to
 446 .Pa ${.CURDIR}/..
 447 which usually points to
 448 .Pa /usr/src .
 449 .It Va WORLD_FLAGS
 450 The contents of this variable are passed to
 451 .Xr make 1
 452 when building world during the release build.
 453 For example, setting this variable to
 454 .Dq Li "-j 4"
 455 will instruct
 456 .Xr make 1
 457 to execute up to four processes at a time.
 458 .El
 459 .Sh FILES
 460 .Bl -tag -compact
 461 .It Pa /usr/doc/Makefile
 462 .It Pa /usr/doc/share/mk/doc.project.mk
 463 .It Pa /usr/ports/Mk/bsd.port.mk
 464 .It Pa /usr/ports/Mk/bsd.sites.mk
 465 .It Pa /usr/share/examples/etc/make.conf
 466 .It Pa /usr/src/Makefile
 467 .It Pa /usr/src/Makefile.inc1
 468 .It Pa /usr/src/release/Makefile
 469 .It Pa /usr/src/release/${arch}/boot_crunch.conf
 470 .It Pa /usr/src/release/${arch}/fixit_crunch.conf
 471 .El
 472 .Sh EXAMPLES
 473 The following sequence of commands was used to build the
 474 .Fx 4.9
 475 release:
 476 .Bd -literal -offset indent
 477 cd /usr
 478 cvs co -rRELENG_4_9_0_RELEASE src
 479 cd src
 480 make buildworld
 481 cd release
 482 make release CHROOTDIR=/local3/release BUILDNAME=4.9-RELEASE \\
 483   CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_9_0_RELEASE
 484 .Ed
 485 .Pp
 486 After running these commands, a complete system suitable for FTP or
 487 CD-ROM distribution is available in the
 488 .Pa /local3/release/R
 489 directory.
 490 .Pp
 491 The following sequence of commands can be used to build a
 492 .Dq "-CURRENT snapshot"
 493 of a
 494 locally modified source tree:
 495 .Bd -literal -offset indent
 496 cd /usr/src
 497 cvs diff -u > /path/to/local.patch
 498 make buildworld
 499 cd release
 500 make release CHROOTDIR=/local3/release BUILDNAME=6.0-CURRENT \\
 501   CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
 502 .Ed
 503 .Sh SEE ALSO
 504 .Xr cc 1 ,
 505 .Xr crunchgen 1 ,
 506 .Xr cvs 1 ,
 507 .Xr install 1 ,
 508 .Xr make 1 ,
 509 .Xr patch 1 ,
 510 .Xr svn 1 Pq Pa ports/devel/subversion-freebsd ,
 511 .Xr uname 1 ,
 512 .Xr md 4 ,
 513 .Xr make.conf 5 ,
 514 .Xr build 7 ,
 515 .Xr ports 7 ,
 516 .Xr chroot 8 ,
 517 .Xr mtree 8 ,
 518 .Xr sysctl 8
 519 .Rs
 520 .%T "FreeBSD Release Engineering"
 521 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
 522 .Re
 523 .Rs
 524 .%T "FreeBSD Release Engineering of Third Party Packages"
 525 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
 526 .Re
 527 .Rs
 528 .%T "FreeBSD Developers' Handbook"
 529 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
 530 .Re
 531 .Sh HISTORY
 532 .Fx
 533 1.x
 534 used a manual checklist, compiled by
 535 .An Rod Grimes ,
 536 to produce a release.
 537 Apart from being incomplete, the list put a lot of specific demands on
 538 available file systems and was quite torturous to execute.
 539 .Pp
 540 As part of the
 541 .Fx 2.0
 542 release engineering effort, significant
 543 effort was spent getting
 544 .Pa src/release/Makefile
 545 into a shape where it could at least automate most of the tediousness
 546 of building a release in a sterile environment.
 547 .Pp
 548 At near 1000 revisions spread over multiple branches, the
 549 .Xr cvs 1
 550 log of
 551 .Pa src/release/Makefile
 552 contains a vivid historical record of some
 553 of the hardships release engineers go through.
 554 .Sh AUTHORS
 555 .Pa src/release/Makefile
 556 was originally written by
 557 .An -nosplit
 558 .An Rod Grimes ,
 559 .An Jordan Hubbard ,
 560 and
 561 .An Poul-Henning Kamp .
 562 This manual page was written by
 563 .An Murray Stokely Aq murray@FreeBSD.org .
 564 .Sh BUGS
 565 Infrastructure changes are occasionally made to the
 566 .Fx
 567 documentation set in such a way that release builds on security
 568 branches can fail.
 569 To work around this, release builds can be made to checkout the
 570 documentation from the last fully supported release of
 571 .Fx .
 572 For example:
 573 .Pp
 574 .Dl "make release RELEASETAG=RELENG_4_9 DOCRELEASETAG=RELEASE_4_9_0 ..."