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