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