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