Makefile.inc: Rework automatic backup (bug 2527)
[dragonfly.git] / share / man / man7 / build.7
1 .\" Copyright (c) 2000
2 .\"     Mike W. Meyer
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/build.7,v 1.19.2.1 2002/03/18 08:33:02 murray Exp $
26 .\"
27 .Dd April 16, 2013
28 .Dt BUILD 7
29 .Os
30 .Sh NAME
31 .Nm build
32 .Nd information on how to build the system
33 .Sh DESCRIPTION
34 The source for the
35 .Dx
36 system and applications is located in
37 .Pa /usr/src .
38 This directory contains the
39 .Dq "base system"
40 sources, which is loosely defined as the things required to rebuild
41 the system to a useful state.
42 It also contains the source for the system documentation, including
43 manual pages.
44 Refer to
45 .Xr development 7
46 for more information on how to obtain the
47 .Dx
48 sources.
49 .Pp
50 Third party applications have to be built using the
51 .Xr pkgsrc 7
52 system.
53 The file
54 .Pa /usr/src/UPDATING
55 gives specifics on how to obtain the tree for building packages.
56 .Pp
57 The
58 .Xr make 1
59 command is used in
60 .Pa /usr/src
61 to build and install the things in that directory.
62 Issuing the
63 .Xr make 1
64 command in any directory or
65 subdirectory of those directories has the same effect as issuing the
66 same command in all subdirectories of that directory.
67 With no target specified, the things in that directory are just built.
68 The following list provides the names and actions for other targets:
69 .Bl -tag -width ".Cm install"
70 .It Cm clean
71 Removes any files created during the build process.
72 .It Cm install
73 Installs the results of the build for this directory.
74 .El
75 .Pp
76 The other
77 .Pa /usr/src
78 make targets are:
79 .Bl -tag -width ".Cm backup-auto-clean"
80 .It Cm buildworld
81 Rebuild everything but the kernel.
82 .It Cm quickworld
83 Same as
84 .Cm buildworld ,
85 but skip bootstrap, build and cross-build tool steps.
86 This target can be used for incremental upgrades once a full build of the
87 world has been done with
88 .Cm buildworld .
89 .It Cm realquickworld
90 Same as
91 .Cm quickworld ,
92 but also skip the depend step.
93 .It Cm crossworld
94 Just do the bootstrap, build and cross-build steps.
95 .It Cm installworld
96 Install everything built by
97 .Cm buildworld .
98 .It Cm world
99 .Cm buildworld +
100 .Cm installworld .
101 .It Cm buildkernel
102 Rebuild the kernel and the kernel-modules.
103 .It Cm nativekernel
104 Rebuild the kernel and the kernel-modules using native tools.
105 .It Cm quickkernel
106 Same as
107 .Cm buildkernel ,
108 but skip the depend step and do not clean out the
109 obj modules.
110 This target can be used for incremental upgrades once a full
111 build of the kernel has been done with
112 .Cm buildkernel .
113 .It Cm installkernel
114 Install the kernel and the kernel-modules.
115 .It Cm reinstallkernel
116 Reinstall the kernel and the kernel-modules.
117 .It Cm kernel
118 .Cm buildkernel +
119 .Cm installkernel .
120 .It Cm preupgrade
121 Perform certain upgrades that have to be done before
122 .Cm installworld .
123 .Cm installworld
124 will complain if they have not been done.
125 .It Cm upgrade
126 Upgrade the files in /etc and also setup the rest of the system for
127 the version of
128 .Dx
129 just installed.
130 .It Cm most
131 Build user commands, no libraries or include files.
132 .It Cm installmost
133 Install user commands, no libraries or include files.
134 .It Cm backupworld
135 Manually archive binaries from installed world to location specified by
136 .Ev WORLD_BACKUP .
137 .It Cm backup-clean
138 Delete archive created by
139 .Cm backupworld .
140 .It Cm backup-auto-clean
141 Delete archive created automatically during
142 .Cm installworld .
143 .It Cm restoreworld
144 Restore binaries from archive created by
145 .Cm backupworld .
146 .It Cm restoreworld-auto
147 Restore binaries from archive created automatically during
148 .Cm installworld .
149 The archive location is specified by
150 .Ev AUTO_BACKUP .
151 .El
152 .Sh ENVIRONMENT
153 .Bl -tag -width ".Ev MAKEOBJDIRPREFIX"
154 .It Ev TARGET_ARCH , TARGET_PLATFORM
155 The target machine processor architecture and hardware platform.
156 These have to be set for cross-building.
157 .Ev TARGET_ARCH
158 is analogous to the
159 .Dq Nm uname Fl p
160 output.
161 To build for the 32 bit
162 .Tn Intel
163 architecture known as IA-32, x86 or x86-32, use:
164 .Bd -literal -offset indent
165 TARGET_ARCH=i386
166 TARGET_PLATFORM=pc32
167 .Ed
168 .Pp
169 For the 64 bit
170 .Tn AMD
171 architecture known as AMD64, x86-64 or Intel 64, use:
172 .Bd -literal -offset indent
173 TARGET_ARCH=x86_64
174 TARGET_PLATFORM=pc64
175 .Ed
176 .It Ev DESTDIR
177 An existing directory to be the root of
178 the hierarchy where the resulting binaries will be
179 installed (the default is
180 .Pa / ) .
181 .It Ev MAKEOBJDIRPREFIX
182 The directory hierarchy where the object files will be built (the default is
183 .Pa /usr/obj ) .
184 .It Ev __MAKE_CONF
185 Used to override the path of
186 .Xr make.conf 5
187 (the default is
188 .Pa /etc/make.conf ) .
189 .It Ev KERNCONF
190 The name of the kernel configuration file from which the kernel should
191 be built (the default is
192 .Li GENERIC ) .
193 .It Ev KERNCONFDIR
194 The directory where the kernel configuration files are kept (the default is
195 .Pa /usr/src/sys/config ) .
196 .It Ev DESTLABEL
197 Common suffix added to kernel and modules directory names, prefixed by
198 a single dot.  For example,
199 .Bd -literal -offset indent
200 make DESTLABEL=test installkernel
201 .Ed
202 .Pp
203 installs them as
204 .Pa /boot/kernel.test
205 and
206 .Pa /boot/modules.test ,
207 respectively.
208 .It Ev DESTKERNDIR
209 Where to install the kernel and the modules (the default is
210 .Pa /boot ) ,
211 in the directory hierarchy specified by the environment variable
212 .Ev DESTDIR .
213 .It Ev DESTKERNNAME
214 The name of the installed kernel file (the default is
215 .Pa kernel ) ,
216 under the directory specified by
217 .Ev DESTKERNDIR .
218 This overrides the effect of
219 .Ev DESTLABEL .
220 .It Ev DESTMODULESNAME
221 The name of the directory to install the kernel modules (the default is
222 .Pa modules ) ,
223 under the directory specified by
224 .Ev DESTKERNDIR .
225 This overrides the effect of
226 .Ev DESTLABEL .
227 .It Ev WORLD_BACKUP
228 Directory for manual backup of binaries of installed world (default:
229 .Pa /var/backups/world_backup ) .
230 .It Ev AUTO_BACKUP
231 Directory for automatic backup of binaries of installed world (default:
232 .Ev MAKEOBJDIRPREFIX Ns /world_binaries/ Ns Ev DESTDIR ) .
233 .It Ev NO_BACKUP
234 When defined, the automatic backup feature of 
235 .Cm installworld
236 is inhibited.
237 .El
238 .Sh FILES
239 .Bl -tag -width ".Pa /usr/src/Makefile_upgrade.inc" -compact
240 .It Pa /etc/make.conf
241 .It Pa /etc/defaults/make.conf
242 .It Pa /usr/src/share/doc/Makefile
243 .It Pa /usr/src/Makefile
244 .It Pa /usr/src/Makefile.inc1
245 .It Pa /usr/src/Makefile_upgrade.inc
246 .El
247 .Sh EXAMPLES
248 The
249 .Dq approved
250 method of updating your system from the latest sources is:
251 .Bd -literal -offset indent
252 make buildworld
253 make buildkernel KERNCONF=FOO
254 make installkernel KERNCONF=FOO
255 make installworld
256 make upgrade
257 .Ed
258 .Pp
259 After running these commands a system reboot is required,
260 otherwise many programs which have been rebuilt (such as
261 .Xr ps 1 ,
262 .Xr top 1 ,
263 etc.) may not work with the old kernel which is still running.
264 .Sh CAVEATS
265 The build and install order in the
266 .Sx EXAMPLES
267 section enforces that the new kernel is installed before the new
268 world.
269 Sometimes it might be necessary to reboot the system between those two
270 steps.
271 In this case
272 .Dq Nm make Cm installworld
273 will tell you to do so.
274 .Sh SEE ALSO
275 .Xr cc 1 ,
276 .Xr install 1 ,
277 .Xr make 1 ,
278 .Xr wmake 1 ,
279 .Xr make.conf 5 ,
280 .Xr development 7 ,
281 .Xr pkgsrc 7 ,
282 .Xr release 7 ,
283 .Xr config 8 ,
284 .Xr reboot 8 ,
285 .Xr shutdown 8
286 .Sh AUTHORS
287 .An -nosplit
288 .An Mike W. Meyer Aq mwm@mired.org
289 and
290 .An Sascha Wildner Aq swildner@gmail.com .