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 rerelease"
  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 .El
 112 .Pp
 113 Targets called by
 114 .Dq Li "make release" :
 115 .Bl -tag -width ".Cm fetch-distfiles"
 116 .It Cm release.1
 117 Cleans out the
 118 .Pa ${CHROOTDIR}/R
 119 directory and uses
 120 .Xr mtree 8
 121 to build the directory hierarchy for the system.
 122 .It Cm release.2
 123 Installs the system into the distribution directories.
 124 .It Cm release.3
 125 Makes and installs the
 126 .Pa GENERIC
 127 kernel as well as any other kernels listed in
 128 .Va KERNELS .
 129 .It Cm release.4
 130 Uses
 131 .Xr crunchgen 1
 132 to build
 133 .Dq crunched
 134 binaries to live on the installation floppies.
 135 .It Cm release.5
 136 Builds synthetic distributions, and cleans up the previously built
 137 distribution trees.
 138 .It Cm release.6
 139 Creates tarballs of the assembled distribution trees.
 140 .It Cm release.7
 141 Makes source distributions.
 142 .It Cm release.8
 143 Creates the MFS root file systems.
 144 .It Cm floppies.1
 145 Creates the boot and kernel floppies.
 146 .It Cm floppies.2
 147 Creates the fixit floppy.
 148 .It Cm floppies.3
 149 Finalizes the
 150 .Pa ${CHROOTDIR}/R/ftp/stage/floppies
 151 staging directory.
 152 .It Cm ftp.1
 153 Sets up a suitable area for FTP installations in
 154 .Pa ${CHROOTDIR}/R/ftp .
 155 .It Cm cdrom.1
 156 Sets up a suitable area to build CD-ROM images in
 157 .Pa ${CHROOTDIR}/R/cdrom .
 158 .It Cm iso.1
 159 Builds ISO images (installation and
 160 .Dq live
 161 file system) from the CD-ROM release area
 162 (disabled by default, see
 163 .Va MAKE_ISOS
 164 below).
 165 .It Cm fetch-distfiles
 166 Fetches distfiles needed during the release build that are not already in
 167 .Va RELEASEDISTFILES .
 168 .It Cm doc.1
 169 Builds all of the necessary tools to turn the
 170 .Fx
 171 Documentation Project source documents (SGML, XML) into HTML
 172 and text documents that will accompany the release.
 173 Also, builds and installs the actual user documentation.
 174 This includes the Handbook, FAQ, articles, and so on.
 175 .It Cm doc.2
 176 Builds the release documentation.
 177 This includes the release notes,
 178 hardware guide, and installation instructions.
 179 .El
 180 .Sh ENVIRONMENT
 181 Variables that must be specified:
 182 .Bl -tag -width ".Va BUILDNAME"
 183 .It Va BUILDNAME
 184 The name of the release to be built.
 185 This is used to set the
 186 .Va RELEASE
 187 value in
 188 .Pa sys/conf/newvers.sh ,
 189 which affects the output of
 190 .Xr uname 1 .
 191 .It Va CHROOTDIR
 192 The directory to be used as the
 193 .Xr chroot 8
 194 environment for the entire release build.
 195 .\" XXX: I recommend against hardcoding specific numbers like "2.3" here;
 196 .\" XXX: perhaps it should be replaced with something to the effect of
 197 .\" XXX: "we do not know how much space you'll need, but make sure you have
 198 .\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number,
 199 .\" XXX: but at least it looks less like a decree and more like an estimate.
 200 This file system should have at least 3.2 gigabytes of free space on the
 201 i386 architecture.
 202 .It Va CVSROOT
 203 The location of the
 204 .Fx
 205 CVS repository.
 206 This path name is in reference to the real system root,
 207 .Em not
 208 the root of the
 209 .Xr chroot 8
 210 directory tree.
 211 .El
 212 .Pp
 213 Optional variables:
 214 .Bl -tag -width ".Va NO_PREFETCHDISTFILES"
 215 .It Va CVSCMDARGS
 216 Additional arguments for
 217 .Xr cvs 1
 218 .Ic checkout
 219 and
 220 .Ic update
 221 commands.
 222 For example, setting this variable to
 223 .Dq Li "-D '01/01/2002 00:00:00 GMT'"
 224 for
 225 .Dq Li "make release"
 226 or
 227 .Dq Li "make rerelease"
 228 will ask
 229 .Xr cvs 1
 230 to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively.
 231 .It Va DOC_LANG
 232 The list of languages and encodings the SGML-based documentation
 233 should be built for.
 234 If not set, the documentation is built for all available languages.
 235 .It Va DOCRELEASETAG
 236 The CVS tag to use when checking out the documentation tree.
 237 Usually,
 238 the head of the documentation tree is used by default.
 239 If
 240 .Va RELEASETAG
 241 specifies a release tag,
 242 then the associated release version is used as the default instead.
 243 .It Va EXTLOCALDIR
 244 The directory that will be copied to
 245 .Pa ${CHROOTDIR}/usr/local .
 246 .It Va EXTSRCDIR
 247 The directory specified by this variable will be copied into
 248 .Pa ${CHROOTDIR}/usr/src
 249 instead of that directory being populated by a CVS checkout.
 250 For
 251 .Dq Li "rerelease" ,
 252 this will NOT be copied; cvs update will be used instead.
 253 .It Va KERNEL_FLAGS
 254 The contents of this variable are passed to
 255 .Xr make 1
 256 when building kernels during the release build.
 257 For example, setting this variable to
 258 .Dq Li "-j 4"
 259 will instruct
 260 .Xr make 1
 261 to execute up to four processes at a time.
 262 .It Va KERNELS
 263 Specifies a list of additional kernel configurations to compile and
 264 install into the
 265 .Dq base
 266 distribution.
 267 Each kernel is installed into
 268 .Pa /boot/<config>
 269 so that it can be booted from the loader via
 270 .Dq Li "boot <config>" .
 271 .It Va LOCAL_PATCHES
 272 Patch files against
 273 .Pa /usr/src
 274 that will be applied in the
 275 .Xr chroot 8
 276 environment before the release build begins.
 277 .It Va PATCH_FLAGS
 278 Arguments for the
 279 .Xr patch 1
 280 command used to apply
 281 .Va LOCAL_PATCHES
 282 patch file.
 283 .It Va LOCAL_SCRIPT
 284 A script that will be run in the
 285 .Xr chroot 8
 286 environment immediately after any local patches are applied.
 287 .It Va MAKE_ISOS
 288 If defined, bootable ISO CD-ROM images will be created from the
 289 contents of the CD-ROM stage directory.
 290 .It Va DISC1_LABEL
 291 The label used for the CD-ROM created from the disc1 contents, the
 292 default label will be
 293 .Dq Li fbsd_miniinst .
 294 .It Va DISC1_NAME
 295 The name used as part of the ISO file name for the CD-ROM created from
 296 the disc1 contents, the default will be
 297 .Dq Li miniinst .
 298 .It Va DISC2_LABEL
 299 The label used for the CD-ROM created from the disc2 contents, the
 300 default label will be
 301 .Dq Li fbsd_livefs .
 302 .It Va DISC2_NAME
 303 The name used as part of the ISO file name for the CD-ROM created from
 304 the disc2 contents, the default will be
 305 .Dq Li disc2 .
 306 .It Va NOCDROM
 307 If defined, the CD-ROM stage directories will not be created.
 308 .It Va NODOC
 309 If defined, the SGML-based documentation from the
 310 .Fx
 311 Documentation Project will not be built.
 312 However, the
 313 .Dq doc
 314 distribution will still be created with the minimal documentation set
 315 provided in
 316 .Pa src/share/doc .
 317 .It Va NO_FLOPPIES
 318 If defined, no boot and fixit floppy disk images will be created (for those
 319 platforms supporting them).
 320 .It Va NOPORTS
 321 If defined, the Ports Collection will be omitted from the release.
 322 .It Va NOPORTREADMES
 323 If defined, readme files will not be created for each individual port
 324 in the Ports Collection.
 325 The default behavior is for
 326 .Dq Li "make release"
 327 to run
 328 .Dq Li "make readmes"
 329 from
 330 .Pa ${CHROOTDIR}/usr/ports ,
 331 which can be a very time consuming operation.
 332 .It Va PORTSRELEASETAG
 333 The CVS tag to use when checking out the ports tree.
 334 Usually,
 335 the head of the ports tree is used by default.
 336 If
 337 .Va RELEASETAG
 338 specifies a release tag,
 339 then the associated release version is used as the default instead.
 340 .It Va NO_PREFETCHDISTFILES
 341 If this variable is defined,
 342 then distfiles needed during the release build will not be downloaded prior to
 343 entering the
 344 .Xr chroot 8
 345 environment.
 346 Note that if
 347 .Va NO_PREFETCHDISTFILES
 348 is not set,
 349 the fetching is done after any distfiles are obtained via
 350 .Va RELEASEDISTFILES .
 351 .It Va RELEASEDISTFILES
 352 The directory where the distribution files for ports required by the
 353 release build can be found.
 354 This may save a significant amount of time over downloading the
 355 distfiles through a slow link.
 356 .It Va RELEASENOUPDATE
 357 If this variable is defined for
 358 .Dq Li "make rerelease" ,
 359 the source code will not be updated with
 360 .Dq Li "cvs update" .
 361 .It Va RELEASETAG
 362 The CVS tag corresponding to the release that is to be built.
 363 If undefined, the release will be built from the
 364 .Dv HEAD
 365 of the CVS tree
 366 (a
 367 .Dq "-CURRENT snapshot" ) .
 368 .It Va TARGET_ARCH
 369 The target machine processor architecture.
 370 This is analogous to the
 371 .Dq Nm uname Fl p
 372 output.
 373 Set this to cross-build for a different architecture.
 374 .It Va TARGET
 375 The target hardware platform.
 376 This is analogous to the
 377 .Dq Nm uname Fl m
 378 output.
 379 This is necessary to cross-build some target architectures.
 380 For example, cross-building for PC98 machines requires
 381 .Va TARGET_ARCH Ns = Ns Li i386
 382 and
 383 .Va TARGET Ns = Ns Li pc98 .
 384 .It Va WORLDDIR
 385 The directory where
 386 .Dq Li "make buildworld"
 387 was run; defaults to
 388 .Pa ${.CURDIR}/..
 389 which usually points to
 390 .Pa /usr/src .
 391 .It Va WORLD_FLAGS
 392 The contents of this variable are passed to
 393 .Xr make 1
 394 when building world during the release build.
 395 For example, setting this variable to
 396 .Dq Li "-j 4"
 397 will instruct
 398 .Xr make 1
 399 to execute up to four processes at a time.
 400 .El
 401 .Sh FILES
 402 .Bl -tag -compact
 403 .It Pa /etc/make.conf
 404 .It Pa /usr/doc/Makefile
 405 .It Pa /usr/doc/share/mk/doc.project.mk
 406 .It Pa /usr/ports/Mk/bsd.port.mk
 407 .It Pa /usr/ports/Mk/bsd.sites.mk
 408 .It Pa /usr/share/examples/etc/make.conf
 409 .It Pa /usr/src/Makefile
 410 .It Pa /usr/src/Makefile.inc1
 411 .It Pa /usr/src/release/Makefile
 412 .It Pa /usr/src/release/${arch}/drivers.conf
 413 .It Pa /usr/src/release/${arch}/boot_crunch.conf
 414 .It Pa /usr/src/release/${arch}/fixit_crunch.conf
 415 .El
 416 .Sh EXAMPLES
 417 The following sequence of commands was used to build the
 418 .Fx 4.9
 419 release:
 420 .Bd -literal -offset indent
 421 cd /usr
 422 cvs co -rRELENG_4_9_0_RELEASE src
 423 cd src
 424 make buildworld
 425 cd release
 426 make release CHROOTDIR=/local3/release BUILDNAME=4.9-RELEASE \\
 427   CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_9_0_RELEASE
 428 .Ed
 429 .Pp
 430 After running these commands, a complete system suitable for FTP or
 431 CD-ROM distribution is available in the
 432 .Pa /local3/release/R
 433 directory.
 434 .Pp
 435 The following sequence of commands can be used to build a
 436 .Dq "-CURRENT snapshot"
 437 of a
 438 locally modified source tree:
 439 .Bd -literal -offset indent
 440 cd /usr/src
 441 cvs diff -u > /path/to/local.patch
 442 make buildworld
 443 cd release
 444 make release CHROOTDIR=/local3/release BUILDNAME=5.0-CURRENT \\
 445   CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
 446 .Ed
 447 .Sh SEE ALSO
 448 .Xr cc 1 ,
 449 .Xr crunchgen 1 ,
 450 .Xr cvs 1 ,
 451 .Xr install 1 ,
 452 .Xr make 1 ,
 453 .Xr patch 1 ,
 454 .Xr uname 1 ,
 455 .Xr md 4 ,
 456 .Xr drivers.conf 5 ,
 457 .Xr make.conf 5 ,
 458 .Xr build 7 ,
 459 .Xr ports 7 ,
 460 .Xr chroot 8 ,
 461 .Xr mtree 8 ,
 462 .Xr sysctl 8
 463 .Rs
 464 .%T "FreeBSD Release Engineering"
 465 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
 466 .Re
 467 .Rs
 468 .%T "FreeBSD Release Engineering of Third Party Packages"
 469 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
 470 .Re
 471 .Rs
 472 .%T "FreeBSD Developers' Handbook"
 473 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
 474 .Re
 475 .Sh HISTORY
 476 .Fx
 477 1.x
 478 used a manual checklist, compiled by
 479 .An Rod Grimes ,
 480 to produce a release.
 481 Apart from being incomplete, the list put a lot of specific demands on
 482 available file systems and was quite torturous to execute.
 483 .Pp
 484 As part of the
 485 .Fx 2.0
 486 release engineering effort, significant
 487 effort was spent getting
 488 .Pa src/release/Makefile
 489 into a shape where it could at least automate most of the tediousness
 490 of building a release in a sterile environment.
 491 .Pp
 492 With its almost 1000 revisions spread over multiple branches, the
 493 .Xr cvs 1
 494 log of
 495 .Pa src/release/Makefile
 496 contains a vivid historical record of some
 497 of the hardships release engineers go through.
 498 .Sh AUTHORS
 499 .Pa src/release/Makefile
 500 was originally written by
 501 .An -nosplit
 502 .An Rod Grimes ,
 503 .An Jordan Hubbard ,
 504 and
 505 .An Poul-Henning Kamp .
 506 This manual page was written by
 507 .An Murray Stokely Aq murray@FreeBSD.org .
 508 .Sh BUGS
 509 Infrastructure changes are occasionally made to the
 510 .Fx
 511 documentation set in such a way that release builds on security
 512 branches can fail.
 513 To work around this, release builds can be made to checkout the
 514 documentation from the last fully supported release of
 515 .Fx .
 516 For example:
 517 .Pp
 518 .Dl "make release RELEASETAG=RELENG_4_9 DOCRELEASETAG=RELEASE_4_9_0 ..."