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 .\"
  33 .Dd February 24, 2023
  34 .Dt NRELEASE 7
  35 .Os
  36 .Sh NAME
  37 .Nm nrelease
  38 .Nd release building infrastructure
  39 .Sh DESCRIPTION
  40 .Dx
  41 provides a complete build environment suitable for users to make
  42 full releases of the
  43 .Dx
  44 operating system.
  45 All of the tools necessary to build releases are available from the
  46 git repository in
  47 .Pa src/nrelease .
  48 A complete release (that is, a live CD) can actually be built with
  49 only a single command.
  50 This command is aptly named
  51 .Dq Li "make release" .
  52 .Pp
  53 This document does not cover source code management, quality
  54 assurance, or other aspects of the release engineering process.
  55 .Sh TARGETS
  56 The release Makefile
  57 .Pq Pa src/nrelease/Makefile
  58 defines a number of targets which are roughly modeled after the
  59 targets used for building the system.
  60 .Bl -tag -width ".Cm realquickrel"
  61 .It Cm help
  62 Offer some help.
  63 .It Cm release
  64 Builds world and kernel, installs them, adds packages and prepares the ISO
  65 image.
  66 .It Cm quickrel
  67 Same as
  68 .Cm release
  69 but uses the
  70 .Cm quickworld
  71 target (alias
  72 .Cm quick ) .
  73 .It Cm realquickrel
  74 Same as
  75 .Cm release
  76 but uses the
  77 .Cm realquickworld
  78 target (alias
  79 .Cm realquick ) .
  80 .It Cm clean
  81 Removes the ISO root directory and object files.
  82 .It Cm realclean
  83 Same as
  84 .Cm clean
  85 but also removes external packages.
  86 .El
  87 .Pp
  88 The
  89 .Cm quickrel
  90 and
  91 .Cm realquickrel
  92 targets will only work if a full
  93 .Cm buildworld
  94 and
  95 .Cm buildkernel
  96 have been done before.
  97 For a description of the corresponding build targets, see
  98 .Xr build 7 .
  99 .Pp
 100 A number of additional targets may be specified along with
 101 .Cm release ,
 102 .Cm quickrel ,
 103 or
 104 .Cm realquickrel
 105 to add additional features:
 106 .Bl -tag -width ".Cm realquickrel"
 107 .It Cm gui
 108 Adds
 109 .Xr Xorg 1
 110 along with some additional applications to the ISO (LiveDVD).
 111 .It Cm nopkgs
 112 Do not add any packages (for debugging purposes).
 113 This is equivalent to setting
 114 .Va DPORTS_PACKAGES
 115 empty.
 116 .It Cm binpkgs
 117 Install binary packages using
 118 .Xr pkg 8
 119 instead of building them from
 120 .Xr dports 7 .
 121 .El
 122 .Pp
 123 During the process of rolling a release a check is performed to find
 124 out if external packages to be put on the CD exist on your system.
 125 If they cannot be found, the release process will stop and give
 126 proper commands for downloading and setting up these packages.
 127 .Sh ENVIRONMENT
 128 .Bl -tag -width ".Va DPORTS_EXTRA_PACKAGES"
 129 .It Va DPORTS_PACKAGES
 130 List of packages to be added to the ISO.
 131 .It Va DPORTS_EXTRA_PACKAGES
 132 List of packages, in addition to
 133 .Va DPORTS_PACKAGES ,
 134 to be added to the ISO.
 135 .It Va DPORTS_PATH
 136 Location of the
 137 .Xr dports 7
 138 tree to be used for package building.
 139 .It Va GITURL_SRC
 140 The Git URL to the system source repository.
 141 .It Va GITURL_DPORTS
 142 The Git URL to the
 143 .Xr dports 7
 144 repository.
 145 .It Va IMGFILE
 146 The name of the image file (default is
 147 .Pa /usr/obj/release/dfly.img ) .
 148 .It Va IMGMNT
 149 The mount point for the image (default is
 150 .Pa /usr/obj/release/mnt ) .
 151 .It Va IMGSIZE
 152 The size of the IMG file (in units of 512-byte sector).
 153 The default size is determined from the actual content by leaving about
 154 600 MB free space.
 155 .It Va IMGSIZE_MB
 156 Same as
 157 .Va IMGSIZE
 158 but specify the size in units of MB.
 159 .It Va ISODIR
 160 Default prefix of
 161 .Va ISOFILE
 162 and
 163 .Va ISOROOT
 164 (default is
 165 .Pa /usr/obj/release ) .
 166 .It Va ISOFILE
 167 Name of the ISO image to generate (default is
 168 .Pa /usr/obj/release/dfly.iso ) .
 169 .It Va ISOROOT
 170 Location where the image contents are installed to before the ISO is prepared.
 171 .It Va KERNCONF
 172 Kernel configuration to use.
 173 .It Va LABEL
 174 The name of the
 175 .Xr disklabel64 5
 176 slice in the IMG file and is used to identify the installation USB device.
 177 The is also the volume ID of the ISO file.
 178 .It Va NREL_MAKE_JOBS
 179 The number of make jobs (default is the value of sysctl
 180 .Va hw.ncpu ) .
 181 .It Va PKG_ Ns Aq Ar port
 182 Specify the binary package name for port
 183 .Dq port .
 184 .It Va WITHOUT_SRCS
 185 If set, this variable will prevent source code from being copied to
 186 the ISO image.
 187 .El
 188 .Sh FILES
 189 .Bl -tag -compact -width ".Pa src/nrelease/Makefile"
 190 .It Pa /etc/make.conf
 191 .It Pa src/Makefile
 192 .It Pa src/Makefile.inc1
 193 .It Pa src/nrelease/Makefile
 194 .El
 195 .Sh EXAMPLES
 196 The following sequence of commands is used to build a standard
 197 .Dx 2.0
 198 installation CD image (assuming that a local git repository is
 199 available, see
 200 .Xr development 7
 201 for how to get this):
 202 .Bd -literal -offset indent
 203 cd /usr/src
 204 git checkout -b rel2_0 crater/DragonFly_RELEASE_2_0
 205 cd nrelease
 206 make release
 207 .Ed
 208 .Pp
 209 After running these commands, the image will be available in the
 210 .Pa /usr/obj/release
 211 directory.
 212 .\".Pp
 213 .\"The steps required for engineering a release are documented in (CVS)
 214 .\".Pa doc/notes/release.txt
 215 .\"(how to branch the CVS tree etc.)
 216 .\"They were put in an out of the way place so normal developers would not
 217 .\"accidentally try to run the commands in question.
 218 .Sh SEE ALSO
 219 .Xr git 1 ,
 220 .Xr make 1 ,
 221 .Xr make.conf 5 ,
 222 .Xr build 7 ,
 223 .Xr development 7 ,
 224 .Xr dports 7
 225 .Sh HISTORY
 226 The
 227 .Nm
 228 framework was added in
 229 .Dx 1.0
 230 to implement the idea of a
 231 .Dq "live CD" .
 232 .Sh AUTHORS
 233 .An -nosplit
 234 The
 235 .Nm
 236 infrastructure was written by
 237 .An Matthew Dillon .
 238 This manual page was written by
 239 .An Sascha Wildner .