share/man/man7/release.7

   1 .\"
   2 .\" Copyright (c) 2006 The DragonFly Project.  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 .\"
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in
  12 .\"    the documentation and/or other materials provided with the
  13 .\"    distribution.
  14 .\" 3. Neither the name of The DragonFly Project nor the names of its
  15 .\"    contributors may be used to endorse or promote products derived
  16 .\"    from this software without specific, prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  21 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  22 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  24 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  26 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  27 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  28 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\" $FreeBSD: src/share/man/man7/release.7,v 1.3.2.6 2003/04/12 20:42:30 murray Exp $
  32 .\" $DragonFly: src/share/man/man7/release.7,v 1.12 2008/04/01 21:10:26 swildner Exp $
  33 .\"
  34 .Dd February 11, 2009
  35 .Dt NRELEASE 7
  36 .Os
  37 .Sh NAME
  38 .Nm nrelease
  39 .Nd release building infrastructure
  40 .Sh DESCRIPTION
  41 .Dx
  42 provides a complete build environment suitable for users to make
  43 full releases of the
  44 .Dx
  45 operating system.
  46 All of the tools necessary to build releases are available from the
  47 git repository in
  48 .Pa src/nrelease .
  49 A complete release (that is, a live CD) can actually be built with
  50 only a single command.
  51 This command is aptly named
  52 .Dq Li "make release" .
  53 .Pp
  54 This document does not cover source code management, quality
  55 assurance, or other aspects of the release engineering process.
  56 .Sh TARGETS
  57 The release Makefile
  58 .Pq Pa src/nrelease/Makefile
  59 defines a number of targets which are roughly modeled after the
  60 targets used for building the system.
  61 .Bl -tag -width ".Cm realquickrel"
  62 .It Cm help
  63 Offer some help.
  64 .It Cm release
  65 Builds world and kernel, installs them, adds packages and prepares the ISO
  66 image.
  67 .It Cm quickrel
  68 Same as
  69 .Cm release
  70 but uses the
  71 .Cm quickworld
  72 target (alias
  73 .Cm quick ) .
  74 .It Cm realquickrel
  75 Same as
  76 .Cm release
  77 but uses the
  78 .Cm realquickworld
  79 target (alias
  80 .Cm realquick ) .
  81 .It Cm clean
  82 Removes the ISO root directory and object files.
  83 .It Cm realclean
  84 Same as
  85 .Cm clean
  86 but also removes external packages.
  87 .It Cm fetch
  88 Downloads binary packages using
  89 .Xr fetch 1 .
  90 .El
  91 .Pp
  92 The
  93 .Cm quickrel
  94 and
  95 .Cm realquickrel
  96 targets will only work if a full
  97 .Cm buildworld
  98 and
  99 .Cm buildkernel
 100 have been done before.
 101 For a description of the corresponding build targets, see
 102 .Xr build 7 .
 103 .Pp
 104 A number of additional targets may be specified along with
 105 .Cm release ,
 106 .Cm quickrel ,
 107 or
 108 .Cm realquickrel
 109 to add additional features:
 110 .Bl -tag -width ".Cm realquickrel"
 111 .It Cm gui
 112 Adds
 113 .Xr Xorg 1
 114 along with some additional applications to the ISO (LiveDVD).
 115 .It Cm img
 116 In addition to the ISO, an image suitable for use with e.g., a USB thumb
 117 drive, will be created.
 118 .El
 119 .Pp
 120 During the process of rolling a release a check is performed to find
 121 out if external packages to be put on the CD exist on your system.
 122 If they cannot be found, the release process will stop and give
 123 proper commands for downloading and setting up these packages.
 124 .Sh ENVIRONMENT
 125 .Bl -tag -width ".Va PKGSRC_EXTRA_PACKAGES"
 126 .It Va ISODIR
 127 Default prefix of
 128 .Va ISOFILE
 129 and
 130 .Va ISOROOT
 131 (default is
 132 .Pa /usr/release ) .
 133 .It Va ISOFILE
 134 Name of the ISO image to generate (default is
 135 .Pa /usr/release/dfly.iso ) .
 136 .It Va ISOROOT
 137 Location where the image contents are installed to before the ISO is prepared.
 138 .It Va KERNCONF
 139 Kernel configuration(s) to use.
 140 .It Va PKGBIN_MKISOFS
 141 Location of the
 142 .Xr mkisofs 8
 143 utility which is to be used during the build.
 144 .It Va PKGBIN_PKG_ADD
 145 Location of the
 146 .Xr pkg_add 1
 147 utility which is to be used during the build.
 148 .It Va PKGBIN_PKG_ADMIN
 149 Location of the
 150 .Xr pkg_admin 1
 151 utility which is to be used during the build.
 152 .It Va PKGBIN_PKG_DELETE
 153 Location of the
 154 .Xr pkg_delete 1
 155 utility which is to be used during the build.
 156 .It Va PKGSRC_PACKAGES
 157 List of packages to be added to the ISO.
 158 .It Va PKGSRC_EXTRA_PACKAGES
 159 List of packages, in addition to
 160 .Va PKGSRC_PACKAGES ,
 161 to be added to the ISO.
 162 .It Va PKGSRC_PATH
 163 Location of
 164 .Xr pkgsrc 7
 165 tree to be used for package building.
 166 .It Va PKGSRC_PKG_PATH
 167 Specifies the location where binary
 168 .Xr pkgsrc 7
 169 packages are kept.
 170 .It Va WITHOUT_SRCS
 171 If set, this variable will prevent source code from being copied to
 172 the ISO image.
 173 .It Va IMGFILE
 174 The name of the image file (default is
 175 .Pa /usr/release/dfly.img ) .
 176 .It Va IMGMNT
 177 The mount point for the image (default is
 178 .Pa /usr/release/mnt ) .
 179 .It Va IMGUSBDEV
 180 The disk device to use in the image's
 181 .Xr fstab 5
 182 (default is
 183 .Pa /dev/da8 ) .
 184 .El
 185 .Sh FILES
 186 .Bl -tag -compact
 187 .It Pa /etc/make.conf
 188 .It Pa src/Makefile
 189 .It Pa src/Makefile.inc1
 190 .It Pa src/nrelease/Makefile
 191 .El
 192 .Sh EXAMPLES
 193 The following sequence of commands is used to build a standard
 194 .Dx 2.0
 195 installation CD image (assuming that a local git repository is
 196 available, see
 197 .Xr development 7
 198 for how to get this):
 199 .Bd -literal -offset indent
 200 cd /usr/src
 201 git checkout -b rel2_0 crater/DragonFly_RELEASE_2_0
 202 cd nrelease
 203 make release
 204 .Ed
 205 .Pp
 206 After running these commands, the image will be available in the
 207 .Pa /usr/release
 208 directory.
 209 .\".Pp
 210 .\"The steps required for engineering a release are documented in (CVS)
 211 .\".Pa doc/notes/release.txt
 212 .\"(how to branch the CVS tree etc.)
 213 .\"They were put in an out of the way place so normal developers would not
 214 .\"accidentally try to run the commands in question.
 215 .Sh SEE ALSO
 216 .Xr git 1 ,
 217 .Xr make 1 ,
 218 .Xr make.conf 5 ,
 219 .Xr build 7 ,
 220 .Xr development 7 ,
 221 .Xr pkgsrc 7
 222 .Sh HISTORY
 223 The
 224 .Nm
 225 framework was added in
 226 .Dx 1.0
 227 to implement the idea of a
 228 .Dq "live CD" .
 229 .Sh AUTHORS
 230 .An -nosplit
 231 The
 232 .Nm
 233 infrastructure was written by
 234 .An Matthew Dillon .
 235 This manual page was written by
 236 .An Sascha Wildner .