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