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