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 March 12, 2002
  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 with
  52 .Dq Li "make world" .
  53 The release build process requires that
  54 .Pa /usr/obj
  55 be populated with the output of
  56 .Dq Li "make buildworld" .
  57 This is necessary so that the object files for a complete system can
  58 be installed into a clean
  59 .Xr chroot 8
  60 environment.
  61 The release procedure also requires that the
  62 .Xr md 4
  63 (memory disk) device driver be present in the kernel
  64 (either by being compiled in or loaded as a module).
  65 .Pp
  66 This document does not cover source code management, quality
  67 assurance, or other aspects of the release engineering process.
  68 .Sh TARGETS
  69 The release makefile
  70 .Pq Pa src/release/Makefile
  71 is fairly abstruse.
  72 Most developers will only be concerned with the
  73 .Cm release
  74 target.
  75 .\" XXX: Some sort of introduction to this list?  All the others have one.
  76 .Bl -tag -width ".Cm rerelease"
  77 .It Cm release
  78 Uses
  79 .Dq Li "make installworld"
  80 to install a clean system into a
  81 .Xr chroot 8
  82 environment on the filesystem.
  83 Checks out the specified version of the source code and then rebuilds
  84 the entire system in the clean environment with
  85 .Dq Li "make world" .
  86 The detailed steps that follow are then executed to package up the
  87 different distributions, build the installation floppy disks, build
  88 release documentation, and so on.
  89 .It Cm rerelease
  90 Assumes that the output of a release build has been manually modified,
  91 and performs the minimal number of steps to rebuild the release using
  92 the intermediate output of the previous
  93 .Dq Li "make release" .
  94 .It Cm floppies
  95 Generate a new set of boot floppies.
  96 This will call the
  97 .Cm release.5 ,
  98 .Cm release.9 ,
  99 and
 100 .Cm release.10
 101 targets to re-generate the floppy images of a previous
 102 .Dq Li "make release" .
 103 This is most often used to build custom boot floppies.
 104 .El
 105 .Pp
 106 Targets called by
 107 .Dq Li "make release" :
 108 .Bl -tag -width ".Cm release.10"
 109 .It Cm release.1
 110 Cleans out the
 111 .Pa ${CHROOTDIR}/R
 112 directory and uses
 113 .Xr mtree 8
 114 to build the directory hierarchy for the system.
 115 .It Cm release.2
 116 Installs the system into the distribution directories.
 117 .It Cm release.3
 118 Builds and installs
 119 .Dq crypto ,
 120 .Dq krb4
 121 and
 122 .Dq krb5
 123 distributions.
 124 .It Cm release.4
 125 .\" XXX: We build more than one kernel.  We build a stripped down
 126 .\" kernel for the boot media in addition to a full GENERIC kernel.
 127 Makes and installs the
 128 .Pa GENERIC
 129 kernel.
 130 .It Cm release.5
 131 Uses
 132 .Xr crunchgen 1
 133 to build
 134 .Dq crunched
 135 binaries to live on the installation floppies.
 136 .It Cm release.6
 137 Builds synthetic distributions, and cleans up the previously built
 138 distribution trees.
 139 .It Cm release.7
 140 Creates tarballs of the assembled distribution trees.
 141 .It Cm release.8
 142 Makes source distributions.
 143 .It Cm release.9
 144 Creates the boot and MFS root floppies.
 145 .It Cm release.10
 146 Creates the fixit floppy.
 147 .It Cm ftp.1
 148 Sets up a suitable area for FTP installations in
 149 .Pa ${CHROOTDIR}/R/ftp .
 150 .It Cm cdrom.1
 151 Sets up a suitable area to build CD-ROM images in
 152 .Pa ${CHROOTDIR}/R/cdrom .
 153 .It Cm iso.1
 154 Builds two ISO images (installation and
 155 .Dq live
 156 filesystem) from the CD-ROM release area
 157 (disabled by default, see
 158 .Va MAKE_ISOS
 159 below).
 160 .It Cm doc.1
 161 Builds all of the necessary tools to turn the
 162 .Fx
 163 Documentation Project source documents (SGML, XML) into HTML
 164 and text documents that will accompany the release.
 165 Also, builds and installs the actual user documentation.
 166 This includes the Handbook, FAQ, articles, and so on.
 167 .It Cm doc.2
 168 Builds the release documentation.
 169 This includes the release notes,
 170 hardware guide, and installation instructions.
 171 .El
 172 .Sh ENVIRONMENT
 173 Variables that must be specified:
 174 .Bl -tag -width ".Va BUILDNAME"
 175 .It Va BUILDNAME
 176 The name of the release to be built.
 177 This is used to set the
 178 .Va RELEASE
 179 value in
 180 .Pa sys/conf/newvers.sh ,
 181 which affects the output of
 182 .Xr uname 1 .
 183 .It Va CHROOTDIR
 184 The directory to be used as the
 185 .Xr chroot 8
 186 environment for the entire release build.
 187 .\" XXX: I recommend against hardcoding specific numbers like "2.3" here;
 188 .\" XXX: perhaps it should be replaced with something to the effect of
 189 .\" XXX: "we don't know how much space you'll need, but make sure you have
 190 .\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number,
 191 .\" XXX: but at least it looks less like a decree and more like an estimate.
 192 This filesystem should have at least 2.3 gigabytes of free space on the
 193 i386 architecture.
 194 .It Va CVSROOT
 195 The location of the
 196 .Fx
 197 CVS repository.
 198 This path name is referenced to the real system root,
 199 .Em not
 200 the root of the
 201 .Xr chroot 8
 202 directory tree.
 203 .El
 204 .Pp
 205 Optional variables:
 206 .Bl -tag -width ".Va PREFETCHDISTFILES"
 207 .It Va CVSCMDARGS
 208 Additional arguments for
 209 .Xr cvs 1
 210 .Ic checkout
 211 and
 212 .Ic update
 213 commands.
 214 For example, setting this variable to
 215 .Dq Li "-D '01/01/2002 00:00:00 GMT'"
 216 for
 217 .Dq Li "make release"
 218 or
 219 .Dq Li "make rerelease"
 220 will ask
 221 .Xr cvs 1
 222 to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively.
 223 .It Va DOC_LANG
 224 The list of languages and encodings the SGML-based documentation
 225 should be built for.
 226 If not set, the documentation is built for all available languages.
 227 .It Va DOCRELEASETAG
 228 The CVS tag to use when checking out the documentation tree.
 229 Usually,
 230 the head of the documentation tree is used by default.
 231 If
 232 .Va RELEASETAG
 233 specifies a release tag,
 234 then the associated release version is used as the default instead.
 235 .It Va KERNEL_FLAGS
 236 The contents of this variable are passed to
 237 .Xr make 1
 238 when building kernels during the release build.
 239 For example, setting this variable to
 240 .Dq Li "-j 4"
 241 will instruct
 242 .Xr make 1
 243 to execute up to four processes at a time.
 244 .It Va LOCAL_PATCHES
 245 A patch file against
 246 .Pa /usr/src
 247 that will be applied in the
 248 .Xr chroot 8
 249 environment before the release build begins.
 250 .It Va PATCH_FLAGS
 251 Arguments for the
 252 .Xr patch 1
 253 command used to apply
 254 .Va LOCAL_PATCHES
 255 patch file.
 256 .It Va LOCAL_SCRIPT
 257 A script that will be run in the
 258 .Xr chroot 8
 259 environment immediately after any local patches are applied.
 260 .It Va MAKE_ISOS
 261 If defined, bootable ISO CD-ROM images will be created from the
 262 contents of the CD-ROM stage directory.
 263 .It Va NODOC
 264 If set to
 265 .Dq Li YES ,
 266 the SGML-based documentation from the
 267 .Fx
 268 Documentation Project will not be built.
 269 However, the
 270 .Dq doc
 271 distribution will still be created with the minimal documentation set
 272 provided in
 273 .Pa src/share/doc .
 274 .It Va NOPORTS
 275 If set to
 276 .Dq Li YES
 277 then the Ports Collection will be omitted from the release.
 278 .It Va NOPORTREADMES
 279 If defined, readme files will not be created for each individual port
 280 in the Ports Collection.
 281 The default behavior is for
 282 .Dq Li "make release"
 283 to run
 284 .Dq Li "make readmes"
 285 from
 286 .Pa ${CHROOTDIR}/usr/ports ,
 287 which can be a very time consuming operation.
 288 .It Va PORTSRELEASETAG
 289 The CVS tag to use when checking out the ports tree.
 290 Usually,
 291 the head of the ports tree is used by default.
 292 If
 293 .Va RELEASETAG
 294 specifies a release tag,
 295 then the associated release version is used as the default instead.
 296 .It Va PREFETCHDISTFILES
 297 If this variable is defined,
 298 then distfiles needed during the release build will be downloaded prior to
 299 entering the
 300 .Xr chroot 8
 301 environment.
 302 Note that this is done after any distfiles are obtained via
 303 .Va RELEASEDISTFILES .
 304 .It Va RELEASEDISTFILES
 305 The directory where the distribution files for ports required by the
 306 release build can be found.
 307 This may save a significant amount of time over downloading the
 308 distfiles through a slow link.
 309 .It Va RELEASENOUPDATE
 310 If this variable is defined for
 311 .Dq Li "make rerelease" ,
 312 the source code will not be updated with
 313 .Dq Li "cvs update" .
 314 .It Va RELEASETAG
 315 The CVS tag corresponding to the release that is to be built.
 316 If undefined, the release will be built from the
 317 .Dv HEAD
 318 of the CVS tree
 319 (a
 320 .Dq "-CURRENT snapshot" ) .
 321 .It Va TARGET_ARCH
 322 The target machine processor architecture.
 323 This is analogous to the
 324 .Dq Nm uname Fl p
 325 output.
 326 Set this to cross-build for a different architecture.
 327 .It Va TARGET
 328 The target hardware platform.
 329 This is analogous to the
 330 .Dq Nm uname Fl m
 331 output.
 332 This is necessary to cross-build some target architectures.
 333 For example, cross-building for PC98 machines requires
 334 .Va TARGET_ARCH Ns = Ns Li i386
 335 and
 336 .Va TARGET Ns = Ns Li pc98 .
 337 .It Va WORLD_FLAGS
 338 The contents of this variable are passed to
 339 .Xr make 1
 340 when building world during the release build.
 341 For example, setting this variable to
 342 .Dq Li "-j 4"
 343 will instruct
 344 .Xr make 1
 345 to execute up to four processes at a time.
 346 .El
 347 .Sh FILES
 348 .Bl -tag -compact
 349 .It Pa /etc/make.conf
 350 .It Pa /usr/doc/Makefile
 351 .It Pa /usr/doc/share/mk/doc.project.mk
 352 .It Pa /usr/ports/Mk/bsd.port.mk
 353 .It Pa /usr/ports/Mk/bsd.sites.mk
 354 .It Pa /usr/share/examples/etc/make.conf
 355 .It Pa /usr/src/Makefile
 356 .It Pa /usr/src/Makefile.inc1
 357 .It Pa /usr/src/release/Makefile
 358 .It Pa /usr/src/release/${arch}/drivers.conf
 359 .It Pa /usr/src/release/${arch}/boot_crunch.conf
 360 .It Pa /usr/src/release/${arch}/fixit_crunch.conf
 361 .El
 362 .Sh EXAMPLES
 363 The following sequence of commands was used to build the
 364 .Fx 4.5
 365 release:
 366 .Bd -literal -offset indent
 367 cd /usr
 368 cvs co -rRELENG_4_5_0_RELEASE src
 369 cd src
 370 make buildworld
 371 cd release
 372 make release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\
 373   CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_5_0_RELEASE
 374 .Ed
 375 .Pp
 376 After running these commands, a complete system suitable for FTP or
 377 CD-ROM distribution is available in the
 378 .Pa /local3/release/R
 379 directory.
 380 .Pp
 381 The following sequence of commands can be used to build a
 382 .Dq "-CURRENT snapshot"
 383 of a
 384 locally modified source tree:
 385 .Bd -literal -offset indent
 386 cd /usr/src
 387 cvs diff -u > /path/to/local.patch
 388 make buildworld
 389 cd release
 390 make release CHROOTDIR=/local3/release BUILDNAME=5.0-CURRENT \\
 391   CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
 392 .Ed
 393 .Sh SEE ALSO
 394 .Xr cc 1 ,
 395 .Xr crunchgen 1 ,
 396 .Xr cvs 1 ,
 397 .Xr install 1 ,
 398 .Xr make 1 ,
 399 .Xr patch 1 ,
 400 .Xr uname 1 ,
 401 .Xr md 4 ,
 402 .Xr drivers.conf 5 ,
 403 .Xr make.conf 5 ,
 404 .Xr build 7 ,
 405 .Xr ports 7 ,
 406 .Xr chroot 8 ,
 407 .Xr mtree 8
 408 .Rs
 409 .%T "FreeBSD Release Engineering"
 410 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
 411 .Re
 412 .Rs
 413 .%T "FreeBSD Release Engineering of Third Party Packages"
 414 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
 415 .Re
 416 .Rs
 417 .%T "FreeBSD Developers' Handbook"
 418 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
 419 .Re
 420 .Sh HISTORY
 421 .Fx
 422 1.x
 423 used a manual checklist, compiled by
 424 .An Rod Grimes ,
 425 to produce a release.
 426 Apart from being incomplete, the list put a lot of specific demands on
 427 available filesystems and was quite torturous to execute.
 428 .Pp
 429 As part of the
 430 .Fx 2.0
 431 release engineering effort, significant
 432 effort was spent getting
 433 .Pa src/release/Makefile
 434 into a shape where it could at least automate most of the tediousness
 435 of building a release in a sterile environment.
 436 .Pp
 437 With its almost 1000 revisions spread over multiple branches, the
 438 .Xr cvs 1
 439 log of
 440 .Pa src/release/Makefile
 441 contains a vivid historical record of some
 442 of the hardships release engineers go through.
 443 .Sh AUTHORS
 444 .Pa src/release/Makefile
 445 was originally written by
 446 .An -nosplit
 447 .An Rod Grimes ,
 448 .An Jordan Hubbard ,
 449 and
 450 .An Poul-Henning Kamp .
 451 This manual page was written by
 452 .An Murray Stokely Aq murray@FreeBSD.org .