release.7: Sync environment variables with nrelease/Makefile
[dragonfly.git] / 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 May 9, 2015
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 .El
117 .Pp
118 During the process of rolling a release a check is performed to find
119 out if external packages to be put on the CD exist on your system.
120 If they cannot be found, the release process will stop and give
121 proper commands for downloading and setting up these packages.
122 .Sh ENVIRONMENT
123 .Bl -tag -width ".Va DPORTS_EXTRA_PACKAGES"
124 .It Va DPORTS_PACKAGES
125 List of packages to be added to the ISO.
126 .It Va DPORTS_EXTRA_PACKAGES
127 List of packages, in addition to
128 .Va DPORTS_PACKAGES ,
129 to be added to the ISO.
130 .It Va DPORTS_PATH
131 Location of the
132 .Xr dports 7
133 tree to be used for package building.
134 .It Va GITURL_SRC
135 The Git URL to the system source repository.
136 .It Va GITURL_DPORTS
137 The Git URL to the
138 .Xr dports 7
139 repository.
140 .It Va IMGFILE
141 The name of the image file (default is
142 .Pa /usr/obj/release/dfly.img ) .
143 .It Va IMGMNT
144 The mount point for the image (default is
145 .Pa /usr/obj/release/mnt ) .
146 .It Va IMGSIZE
147 The size of the IMG file (in units of 512-byte sector).
148 The default size is determined from the actual content by leaving about
149 600 MB free space.
150 .It Va ISODIR
151 Default prefix of
152 .Va ISOFILE
153 and
154 .Va ISOROOT
155 (default is
156 .Pa /usr/obj/release ) .
157 .It Va ISOFILE
158 Name of the ISO image to generate (default is
159 .Pa /usr/obj/release/dfly.iso ) .
160 .It Va ISOROOT
161 Location where the image contents are installed to before the ISO is prepared.
162 .It Va KERNCONF
163 Kernel configuration to use.
164 .It Va LABEL
165 The name of the
166 .Xr disklabel64 5
167 slice in the IMG file and is used to identify the installation USB device.
168 The is also the volume ID of the ISO file.
169 .It Va MAKE_JOBS
170 The number of make jobs (default is the value of sysctl
171 .Va hw.ncpu ) .
172 .It Va WITHOUT_SRCS
173 If set, this variable will prevent source code from being copied to
174 the ISO image.
175 .El
176 .Sh FILES
177 .Bl -tag -compact -width ".Pa src/nrelease/Makefile"
178 .It Pa /etc/make.conf
179 .It Pa src/Makefile
180 .It Pa src/Makefile.inc1
181 .It Pa src/nrelease/Makefile
182 .El
183 .Sh EXAMPLES
184 The following sequence of commands is used to build a standard
185 .Dx 2.0
186 installation CD image (assuming that a local git repository is
187 available, see
188 .Xr development 7
189 for how to get this):
190 .Bd -literal -offset indent
191 cd /usr/src
192 git checkout -b rel2_0 crater/DragonFly_RELEASE_2_0
193 cd nrelease
194 make release
195 .Ed
196 .Pp
197 After running these commands, the image will be available in the
198 .Pa /usr/obj/release
199 directory.
200 .\".Pp
201 .\"The steps required for engineering a release are documented in (CVS)
202 .\".Pa doc/notes/release.txt
203 .\"(how to branch the CVS tree etc.)
204 .\"They were put in an out of the way place so normal developers would not
205 .\"accidentally try to run the commands in question.
206 .Sh SEE ALSO
207 .Xr git 1 ,
208 .Xr make 1 ,
209 .Xr make.conf 5 ,
210 .Xr build 7 ,
211 .Xr development 7 ,
212 .Xr dports 7
213 .Sh HISTORY
214 The
215 .Nm
216 framework was added in
217 .Dx 1.0
218 to implement the idea of a
219 .Dq "live CD" .
220 .Sh AUTHORS
221 .An -nosplit
222 The
223 .Nm
224 infrastructure was written by
225 .An Matthew Dillon .
226 This manual page was written by
227 .An Sascha Wildner .