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