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 September 6, 2004
  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/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 filesystem 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 BUILDNAME"
 201 .It Va BUILDNAME
 202 The name of the release to be built.
 203 This is used to set the
 204 .Va RELEASE
 205 value in
 206 .Pa sys/conf/newvers.sh ,
 207 which affects the output of
 208 .Xr uname 1 .
 209 .It Va CHROOTDIR
 210 The directory to be used as the
 211 .Xr chroot 8
 212 environment for the entire release build.
 213 .\" XXX: I recommend against hardcoding specific numbers like "2.3" here;
 214 .\" XXX: perhaps it should be replaced with something to the effect of
 215 .\" XXX: "we do not know how much space you'll need, but make sure you have
 216 .\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number,
 217 .\" XXX: but at least it looks less like a decree and more like an estimate.
 218 This file system should have at least 3.2 gigabytes of free space on the
 219 i386 architecture.
 220 .It Va CVSROOT
 221 The location of the
 222 .Fx
 223 CVS repository.
 224 This path name is in reference to the real system root,
 225 .Em not
 226 the root of the
 227 .Xr chroot 8
 228 directory tree.
 229 .El
 230 .Pp
 231 Optional variables:
 232 .Bl -tag -width ".Va NO_PREFETCHDISTFILES"
 233 .It Va CD_PACKAGE_TREE
 234 A directory containing extra bits for the first and second CD-ROM images.
 235 The extra files for the first disc should be in
 236 .Pa ${CD_PACKAGE_TREE}/disc1
 237 and the extra files for the second disc should be in
 238 .Pa ${CD_PACKAGE_TREE}/disc2 .
 239 Typically, this variable will be set to the output directory of an earlier
 240 invocation of the
 241 .Cm package-split
 242 target.
 243 .It Va CVSARGS
 244 Additional arguments for
 245 .Xr cvs 1
 246 that come before the subcommands such as
 247 .Dq Li "-qR" .
 248 .It Va CVSCMDARGS
 249 Additional arguments for
 250 .Xr cvs 1
 251 .Ic checkout
 252 and
 253 .Ic update
 254 commands.
 255 For example, setting this variable to
 256 .Dq Li "-D '01/01/2002 00:00:00 GMT'"
 257 for
 258 .Dq Li "make release"
 259 or
 260 .Dq Li "make rerelease"
 261 will ask
 262 .Xr cvs 1
 263 to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively.
 264 .It Va DOC_LANG
 265 The list of languages and encodings the SGML-based documentation
 266 should be built for.
 267 If not set, the documentation is built for all available languages.
 268 .It Va DOCRELEASETAG
 269 The CVS tag to use when checking out the documentation tree.
 270 Usually,
 271 the head of the documentation tree is used by default.
 272 If
 273 .Va RELEASETAG
 274 specifies a release tag,
 275 then the associated release version is used as the default instead.
 276 .It Va EXTLOCALDIR
 277 The directory that will be copied to
 278 .Pa ${CHROOTDIR}/usr/local .
 279 .It Va EXTSRCDIR
 280 The directory specified by this variable will be copied into
 281 .Pa ${CHROOTDIR}/usr/src
 282 instead of that directory being populated by a CVS checkout.
 283 For
 284 .Dq Li "rerelease" ,
 285 this will NOT be copied; cvs update will be used instead.
 286 .It Va KERNEL_FLAGS
 287 The contents of this variable are passed to
 288 .Xr make 1
 289 when building kernels during the release build.
 290 For example, setting this variable to
 291 .Dq Li "-j 4"
 292 will instruct
 293 .Xr make 1
 294 to execute up to four processes at a time.
 295 .It Va KERNELS
 296 Specifies a list of additional kernel configurations to compile and
 297 install into the
 298 .Dq base
 299 distribution.
 300 Each kernel is installed into
 301 .Pa /boot/<config>
 302 so that it can be booted from the loader via
 303 .Dq Li "boot <config>" .
 304 .It Va LOCAL_PATCHES
 305 Patch files against
 306 .Pa /usr/src
 307 that will be applied in the
 308 .Xr chroot 8
 309 environment before the release build begins.
 310 .It Va PATCH_FLAGS
 311 Arguments for the
 312 .Xr patch 1
 313 command used to apply
 314 .Va LOCAL_PATCHES
 315 patch file.
 316 .It Va LOCAL_SCRIPT
 317 A script that will be run in the
 318 .Xr chroot 8
 319 environment immediately after any local patches are applied.
 320 .It Va MAKE_ISOS
 321 If defined, bootable ISO CD-ROM images will be created from the
 322 contents of the CD-ROM stage directory.
 323 .It Va NOCDROM
 324 If defined, the CD-ROM stage directories will not be created.
 325 .It Va NODOC
 326 If defined, the SGML-based documentation from the
 327 .Fx
 328 Documentation Project will not be built.
 329 However, the
 330 .Dq doc
 331 distribution will still be created with the minimal documentation set
 332 provided in
 333 .Pa src/share/doc .
 334 .It Va NO_FLOPPIES
 335 If defined, no boot and fixit floppy disk images will be created (for those
 336 platforms supporting them).
 337 .It Va NOPORTS
 338 If defined, the Ports Collection will be omitted from the release.
 339 .It Va PORTSRELEASETAG
 340 The CVS tag to use when checking out the ports tree.
 341 Usually,
 342 the head of the ports tree is used by default.
 343 If
 344 .Va RELEASETAG
 345 specifies a release tag,
 346 then the associated release version is used as the default instead.
 347 .It Va NO_PREFETCHDISTFILES
 348 If this variable is defined,
 349 then distfiles needed during the release build will not be downloaded prior to
 350 entering the
 351 .Xr chroot 8
 352 environment.
 353 Note that if
 354 .Va NO_PREFETCHDISTFILES
 355 is not set,
 356 the fetching is done after any distfiles are obtained via
 357 .Va RELEASEDISTFILES .
 358 .It Va RELEASEDISTFILES
 359 The directory where the distribution files for ports required by the
 360 release build can be found.
 361 This may save a significant amount of time over downloading the
 362 distfiles through a slow link.
 363 .It Va RELEASENOUPDATE
 364 If this variable is defined for
 365 .Dq Li "make rerelease" ,
 366 the source code will not be updated with
 367 .Dq Li "cvs update" .
 368 .It Va RELEASETAG
 369 The CVS tag corresponding to the release that is to be built.
 370 If undefined, the release will be built from the
 371 .Dv HEAD
 372 of the CVS tree
 373 (a
 374 .Dq "-CURRENT snapshot" ) .
 375 .It Va SEPARATE_LIVEFS
 376 Store the live filesystem on its own CD-ROM image rather than placing it on
 377 the first disc.
 378 .It Va TARGET_ARCH
 379 The target machine processor architecture.
 380 This is analogous to the
 381 .Dq Nm uname Fl p
 382 output.
 383 Set this to cross-build for a different architecture.
 384 .It Va TARGET
 385 The target hardware platform.
 386 This is analogous to the
 387 .Dq Nm uname Fl m
 388 output.
 389 This is necessary to cross-build some target architectures.
 390 For example, cross-building for PC98 machines requires
 391 .Va TARGET_ARCH Ns = Ns Li i386
 392 and
 393 .Va TARGET Ns = Ns Li pc98 .
 394 .It Va WORLDDIR
 395 The directory where
 396 .Dq Li "make buildworld"
 397 was run; defaults to
 398 .Pa ${.CURDIR}/..
 399 which usually points to
 400 .Pa /usr/src .
 401 .It Va WORLD_FLAGS
 402 The contents of this variable are passed to
 403 .Xr make 1
 404 when building world during the release build.
 405 For example, setting this variable to
 406 .Dq Li "-j 4"
 407 will instruct
 408 .Xr make 1
 409 to execute up to four processes at a time.
 410 .El
 411 .Sh FILES
 412 .Bl -tag -compact
 413 .It Pa /etc/make.conf
 414 .It Pa /usr/doc/Makefile
 415 .It Pa /usr/doc/share/mk/doc.project.mk
 416 .It Pa /usr/ports/Mk/bsd.port.mk
 417 .It Pa /usr/ports/Mk/bsd.sites.mk
 418 .It Pa /usr/share/examples/etc/make.conf
 419 .It Pa /usr/src/Makefile
 420 .It Pa /usr/src/Makefile.inc1
 421 .It Pa /usr/src/release/Makefile
 422 .It Pa /usr/src/release/${arch}/boot_crunch.conf
 423 .It Pa /usr/src/release/${arch}/fixit_crunch.conf
 424 .El
 425 .Sh EXAMPLES
 426 The following sequence of commands was used to build the
 427 .Fx 4.9
 428 release:
 429 .Bd -literal -offset indent
 430 cd /usr
 431 cvs co -rRELENG_4_9_0_RELEASE src
 432 cd src
 433 make buildworld
 434 cd release
 435 make release CHROOTDIR=/local3/release BUILDNAME=4.9-RELEASE \\
 436   CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_9_0_RELEASE
 437 .Ed
 438 .Pp
 439 After running these commands, a complete system suitable for FTP or
 440 CD-ROM distribution is available in the
 441 .Pa /local3/release/R
 442 directory.
 443 .Pp
 444 The following sequence of commands can be used to build a
 445 .Dq "-CURRENT snapshot"
 446 of a
 447 locally modified source tree:
 448 .Bd -literal -offset indent
 449 cd /usr/src
 450 cvs diff -u > /path/to/local.patch
 451 make buildworld
 452 cd release
 453 make release CHROOTDIR=/local3/release BUILDNAME=6.0-CURRENT \\
 454   CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
 455 .Ed
 456 .Sh SEE ALSO
 457 .Xr cc 1 ,
 458 .Xr crunchgen 1 ,
 459 .Xr cvs 1 ,
 460 .Xr install 1 ,
 461 .Xr make 1 ,
 462 .Xr patch 1 ,
 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 .%O 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 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
 478 .Re
 479 .Rs
 480 .%T "FreeBSD Developers' Handbook"
 481 .%O 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 With its almost 1000 revisions spread over multiple branches, the
 501 .Xr cvs 1
 502 log of
 503 .Pa src/release/Makefile
 504 contains a vivid historical record of some
 505 of the hardships release engineers go through.
 506 .Sh AUTHORS
 507 .Pa src/release/Makefile
 508 was originally written by
 509 .An -nosplit
 510 .An Rod Grimes ,
 511 .An Jordan Hubbard ,
 512 and
 513 .An Poul-Henning Kamp .
 514 This manual page was written by
 515 .An Murray Stokely Aq murray@FreeBSD.org .
 516 .Sh BUGS
 517 Infrastructure changes are occasionally made to the
 518 .Fx
 519 documentation set in such a way that release builds on security
 520 branches can fail.
 521 To work around this, release builds can be made to checkout the
 522 documentation from the last fully supported release of
 523 .Fx .
 524 For example:
 525 .Pp
 526 .Dl "make release RELEASETAG=RELENG_4_9 DOCRELEASETAG=RELEASE_4_9_0 ..."