xref: /freebsd/share/man/man7/build.7 (revision cdc58367265a2bd6e8f913db2bdc591699ee229f)
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$
26.\"
27.Dd December 31, 2014
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 sources for the
35.Fx
36system and its applications are contained in three different directories,
37normally
38.Pa /usr/src ,
39.Pa /usr/doc ,
40and
41.Pa /usr/ports .
42These directories may be initially empty or non-existent until updated with
43.Xr svn 1
44or
45.Xr portsnap 8 .
46Directory
47.Pa /usr/src
48contains the
49.Dq "base system"
50sources, which is loosely defined as the things required to rebuild
51the system to a useful state.
52Directory
53.Pa /usr/doc
54contains the source for the system documentation, excluding the manual
55pages.
56Directory
57.Pa /usr/ports
58contains a tree that provides a consistent interface for building and
59installing third party applications.
60For more information about the ports build process, see
61.Xr ports 7 .
62.Pp
63The
64.Xr make 1
65command is used in each of these directories to build and install the
66things in that directory.
67Issuing the
68.Xr make 1
69command in any directory or
70subdirectory of those directories has the same effect as issuing the
71same command in all subdirectories of that directory.
72With no target specified, the things in that directory are just built.
73.Pp
74A source tree is allowed to be read-only.
75As described in
76.Xr make 1 ,
77objects are usually built in a separate object directory hierarchy
78specified by the environment variable
79.Va MAKEOBJDIRPREFIX ,
80or under
81.Pa /usr/obj
82if variable
83.Va MAKEOBJDIRPREFIX
84is not set.
85For a given source directory, its canonical object directory
86would be
87.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
88if
89.Xr make 1
90variable
91.Va MAKEOBJDIRPREFIX
92is set, or
93.Pa /usr/obj${.CURDIR}
94if this variable is not set.
95Cross-builds set the object directory as described in the
96documentation for the
97.Cm buildworld
98target below.
99.Pp
100The build may be controlled by defining
101.Xr make 1
102variables described in the
103.Sx ENVIRONMENT
104section below, and by the variables documented in
105.Xr make.conf 5 .
106.Pp
107The following list provides the names and actions for the targets
108supported by the build system:
109.Bl -tag -width ".Cm cleandepend"
110.It Cm clean
111Remove any files created during the build process.
112.It Cm cleandepend
113Remove the file
114.Pa ${.OBJDIR}/${DEPENDFILE}
115generated by a prior
116.Dq Li "make depend"
117step.
118.It Cm cleandir
119Remove the canonical object directory if it exists, or perform
120actions equivalent to
121.Dq Li "make clean cleandepend"
122if it does not.
123This target will also remove an
124.Pa obj
125link in
126.Pa ${.CURDIR}
127if that exists.
128.Pp
129It is advisable to run
130.Dq Li "make cleandir"
131twice: the first invocation will remove the canonical object directory
132and the second one will clean up
133.Pa ${.CURDIR} .
134.It Cm depend
135Generate a list of build dependencies in file
136.Pa ${.OBJDIR}/${DEPENDFILE} .
137.It Cm install
138Install the results of the build to the appropriate location in the
139installation directory hierarchy specified in variable
140.Va DESTDIR .
141.It Cm obj
142Create the canonical object directory associated with the current
143directory.
144.It Cm objlink
145Create a symbolic link to the canonical object directory in
146.Pa ${.CURDIR} .
147.It Cm tags
148Generate a tags file using the program specified in the
149.Xr make 1
150variable
151.Va CTAGS .
152The build system supports
153.Xr ctags 1
154and
155.Nm "GNU Global" .
156.El
157.Pp
158The other supported targets under directory
159.Pa /usr/src
160are:
161.Bl -tag -width ".Cm distributeworld"
162.It Cm buildenv
163Spawn an interactive shell with environment variables set up for
164cross-building the system.
165The target architecture needs to be specified with
166.Xr make 1
167variables
168.Va TARGET_ARCH
169and
170.Va TARGET .
171.Pp
172This target is only useful after a complete cross-toolchain including
173the compiler, linker, assembler, headers and libraries has been
174built; see the
175.Cm toolchain
176target below.
177.It Cm buildworld
178Build everything but the kernel, configure files in
179.Pa etc ,
180and
181.Pa release .
182The actual build location prefix used is
183.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
184for native builds, and
185.Pa ${MAKEOBJDIRPREFIX}/${TARGET}${.CURDIR}
186for cross builds and native builds with variable
187.Va CROSS_BUILD_TESTING
188set.
189.It Cm cleanworld
190Attempt to clean up targets built by a preceding
191.Cm buildworld
192step.
193.It Cm distributeworld
194Distribute everything compiled by a preceding
195.Cm buildworld
196step.
197Files are placed in the directory hierarchy specified by
198.Xr make 1
199variable
200.Va DISTDIR .
201This target is used while building a release; see
202.Xr release 7 .
203.It Cm packageworld
204Archive the results of
205.Cm distributeworld ,
206placing the results in
207.Va DISTDIR .
208This target is used while building a release; see
209.Xr release 7 .
210.It Cm installworld
211Install everything built by a preceding
212.Cm buildworld
213step into the directory hierarchy pointed to by
214.Xr make 1
215variable
216.Va DESTDIR .
217.Pp
218If installing onto an NFS file system and running
219.Xr make 1
220with the
221.Fl j
222option, make sure that
223.Xr rpc.lockd 8
224is running on both client and server.
225See
226.Xr rc.conf 5
227on how to make it start at boot time.
228.It Cm toolchain
229Create the build toolchain needed to build the rest of the system.
230For cross-architecture builds, this step creates a cross-toolchain.
231.It Cm universe
232For each architecture,
233execute a
234.Cm buildworld
235followed by a
236.Cm buildkernel
237for all kernels for that architecture,
238including
239.Pa LINT .
240This command takes a long time.
241.It Cm update
242Get updated sources as configured in
243.Xr make.conf 5 .
244.It Cm targets
245Print a list of supported
246.Va TARGET
247/
248.Va TARGET_ARCH
249pairs for world and kernel targets.
250.It Cm tinderbox
251Execute the same targets as
252.Cm universe .
253In addition print a summary of all failed targets at the end and
254exit with an error if there were any.
255.It Cm toolchains
256Create a build toolchain for each architecture supported by the build system.
257.El
258.Pp
259Kernel specific build targets in
260.Pa /usr/src
261are:
262.Bl -tag -width ".Cm distributekernel"
263.It Cm buildkernel
264Rebuild the kernel and the kernel modules.
265.It Cm installkernel
266Install the kernel and the kernel modules to directory
267.Pa ${DESTDIR}/boot/kernel ,
268renaming any pre-existing directory with this name to
269.Pa kernel.old
270if it contained the currently running kernel.
271The target directory under
272.Pa ${DESTDIR}
273may be modified using the
274.Va INSTKERNNAME
275and
276.Va KODIR
277.Xr make 1
278variables.
279.It Cm distributekernel
280Install the kernel to the directory
281.Pa ${DISTDIR}/kernel/boot/kernel .
282This target is used while building a release; see
283.Xr release 7 .
284.It Cm packagekernel
285Archive the results of
286.Cm distributekernel ,
287placing the results in
288.Va DISTDIR .
289This target is used while building a release; see
290.Xr release 7 .
291.It Cm kernel
292Equivalent to
293.Cm buildkernel
294followed by
295.Cm installkernel
296.It Cm kernel-toolchain
297Rebuild the tools needed for kernel compilation.
298Use this if you did not do a
299.Cm buildworld
300first.
301.It Cm reinstallkernel
302Reinstall the kernel and the kernel modules, overwriting the contents
303of the target directory.
304As with the
305.Cm installkernel
306target, the target directory can be specified using the
307.Xr make 1
308variable
309.Va INSTKERNNAME .
310.El
311.Pp
312Convenience targets for cleaning up the install destination directory
313denoted by variable
314.Va DESTDIR
315include:
316.Bl -tag -width ".Cm delete-old-libs"
317.It Cm check-old
318Print a list of old files and directories in the system.
319.It Cm delete-old
320Delete obsolete base system files and directories interactively.
321When
322.Li -DBATCH_DELETE_OLD_FILES
323is specified at the command line, the delete operation will be
324non-interactive.
325The variables
326.Va DESTDIR ,
327.Va TARGET_ARCH
328and
329.Va TARGET
330should be set as with
331.Dq Li "make installworld" .
332.It Cm delete-old-libs
333Delete obsolete base system libraries interactively.
334This target should only be used if no 3rd party software uses these
335libraries.
336When
337.Li -DBATCH_DELETE_OLD_FILES
338is specified at the command line, the delete operation will be
339non-interactive.
340The variables
341.Va DESTDIR ,
342.Va TARGET_ARCH
343and
344.Va TARGET
345should be set as with
346.Dq Li "make installworld" .
347.El
348.Sh ENVIRONMENT
349Variables that influence all builds include:
350.Bl -tag -width ".Va MAKEOBJDIRPREFIX"
351.It Va DEBUG_FLAGS
352Defines a set of debugging flags that will be used to build all userland
353binaries under
354.Pa /usr/src .
355When
356.Va DEBUG_FLAGS
357is defined, the
358.Cm install
359and
360.Cm installworld
361targets install binaries from the current
362.Va MAKEOBJDIRPREFIX
363without stripping,
364so that debugging information is retained in the installed binaries.
365.It Va DESTDIR
366The directory hierarchy prefix where built objects will be installed.
367If not set,
368.Va DESTDIR
369defaults to the empty string.
370.It Va MAKEOBJDIRPREFIX
371Defines the prefix for directory names in the tree of built objects.
372Defaults to
373.Pa /usr/obj
374if not defined.
375This variable should only be set in the environment and not via
376.Pa /etc/make.conf
377or the command line.
378.It Va NO_WERROR
379If defined, compiler warnings will not cause the build to halt,
380even if the makefile says otherwise.
381.It Va WITH_CTF
382If defined, the build process will run the DTrace CTF conversion
383tools on built objects.
384.El
385.Pp
386Additionally, builds in
387.Pa /usr/src
388are influenced by the following
389.Xr make 1
390variables:
391.Bl -tag -width ".Va SUBDIR_OVERRIDE"
392.It Va KERNCONF
393Overrides which kernel to build and install for the various kernel
394make targets.
395It defaults to
396.Cm GENERIC .
397.It Va KERNFAST
398If set, the build target
399.Cm buildkernel
400defaults to setting
401.Va NO_KERNELCLEAN ,
402.Va NO_KERNELCONFIG ,
403.Va NO_KERNELDEPEND
404and
405.Va NO_KERNELOBJ .
406When set to a value other than
407.Cm 1
408then
409.Va KERNCONF
410is set to the value of
411.Va KERNFAST .
412.It Va LOCAL_DIRS
413If set, this variable supplies a list of additional directories relative to
414the root of the source tree to build as part of the
415.Cm everything
416target.
417.It Va LOCAL_ITOOLS
418If set, this variable supplies a list of additional tools that are used by the
419.Cm installworld
420and
421.Cm distributeworld
422targets.
423.It Va LOCAL_LIB_DIRS
424If set, this variable supplies a list of additional directories relative to
425the root of the source tree to build as part of the
426.Cm libraries
427target.
428.It Va LOCAL_MTREE
429If set, this variable supplies a list of additional mtrees relative to the
430root of the source tree to use as part of the
431.Cm hierarchy
432target.
433.It Va LOCAL_TOOL_DIRS
434If set, this variable supplies a list of additional directories relative to
435the root of the source tree to build as part of the
436.Cm build-tools
437target.
438.It Va PORTS_MODULES
439A list of ports with kernel modules that should be built and installed
440as part of the
441.Cm buildkernel
442and
443.Cm installkernel
444process.
445.Bd -literal -offset indent
446make PORTS_MODULES=emulators/kqemu-kmod kernel
447.Ed
448.It Va STRIPBIN
449Command to use at install time when stripping binaries.
450Be sure to add any additional tools required to run
451.Va STRIPBIN
452to the
453.Va LOCAL_ITOOLS
454.Xr make 1
455variable before running the
456.Cm distributeworld
457or
458.Cm installworld
459targets.
460See
461.Xr install 1
462for more details.
463.It Va SUBDIR_OVERRIDE
464Override the default list of sub-directories and only build the
465sub-directory named in this variable.
466This variable is useful when debugging failed builds.
467.Bd -literal -offset indent
468make some-target SUBDIR_OVERRIDE=foo/bar
469.Ed
470.It Va TARGET
471The target hardware platform.
472This is analogous to the
473.Dq Nm uname Fl m
474output.
475This is necessary to cross-build some target architectures.
476For example, cross-building for PC98 machines requires
477.Va TARGET_ARCH Ns = Ns Li i386
478and
479.Va TARGET Ns = Ns Li pc98 .
480If not set,
481.Va TARGET
482defaults to the current hardware platform.
483.It Va TARGET_ARCH
484The target machine processor architecture.
485This is analogous to the
486.Dq Nm uname Fl p
487output.
488Set this to cross-build for a different architecture.
489If not set,
490.Va TARGET_ARCH
491defaults to the current machine architecture, unless
492.Va TARGET
493is also set, in which case it defaults to the appropriate
494value for that platform.
495Typically, one only needs to set
496.Va TARGET .
497.El
498.Pp
499Builds under directory
500.Pa /usr/src
501are also influenced by defining one or more of the following symbols,
502using the
503.Fl D
504option of
505.Xr make 1 :
506.Bl -tag -width ".Va -DNO_KERNELDEPEND"
507.It Va NO_CLEANDIR
508If set, the build targets that clean parts of the object tree use the
509equivalent of
510.Dq make clean
511instead of
512.Dq make cleandir .
513.It Va NO_CLEAN
514If set, no object tree files are cleaned at all.
515Setting
516.Va NO_CLEAN
517implies
518.Va NO_KERNELCLEAN ,
519so when
520.Va NO_CLEAN
521is set no kernel objects are cleaned either.
522.It Va NO_CTF
523If set, the build process does not run the DTrace CTF conversion tools
524on built objects.
525.It Va NO_SHARE
526If set, the build does not descend into the
527.Pa /usr/src/share
528subdirectory (i.e., manpages, locale data files, timezone data files and
529other
530.Pa /usr/src/share
531files will not be rebuild from their sources).
532.It Va NO_KERNELCLEAN
533If set, the build process does not run
534.Dq make clean
535as part of the
536.Cm buildkernel
537target.
538.It Va NO_KERNELCONFIG
539If set, the build process does not run
540.Xr config 8
541as part of the
542.Cm buildkernel
543target.
544.It Va NO_KERNELDEPEND
545If set, the build process does not run
546.Dq make depend
547as part of the
548.Cm buildkernel
549target.
550.It Va NO_KERNELOBJ
551If set, the build process does not run
552.Dq make obj
553as part of the
554.Cm buildkernel
555target.
556.It Va NO_DOCUPDATE
557If set, the update process does not update the source of the
558.Fx
559documentation as part of the
560.Dq make update
561target.
562.It Va NO_PORTSUPDATE
563If set, the update process does not update the Ports tree as part of the
564.Dq make update
565target.
566.It Va NO_WWWUPDATE
567If set, the update process does not update the www tree as part of the
568.Dq make update
569target.
570.El
571.Pp
572Builds under directory
573.Pa /usr/doc
574are influenced by the following
575.Xr make 1
576variables:
577.Bl -tag -width ".Va DOC_LANG"
578.It Va DOC_LANG
579If set, restricts the documentation build to the language subdirectories
580specified as its content.
581The default action is to build documentation for all languages.
582.El
583.Pp
584Builds using the
585.Cm universe
586target are influenced by the following
587.Xr make 1
588variables:
589.Bl -tag -width ".Va MAKE_JUST_KERNELS"
590.It Va JFLAG
591Pass the value of this variable to each
592.Xr make 1
593invocation used to build worlds and kernels.
594This can be used to enable multiple jobs within a single architecture's build
595while still building each architecture serially.
596.It Va MAKE_JUST_KERNELS
597Only build kernels for each supported architecture.
598.It Va MAKE_JUST_WORLDS
599Only build worlds for each supported architecture.
600.It Va UNIVERSE_TARGET
601Execute the specified
602.Xr make 1
603target for each supported architecture instead of the default action of
604building a world and one or more kernels.
605.El
606.Sh FILES
607.Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
608.It Pa /usr/doc/Makefile
609.It Pa /usr/doc/share/mk/doc.project.mk
610.It Pa /usr/ports/Mk/bsd.port.mk
611.It Pa /usr/ports/Mk/bsd.sites.mk
612.It Pa /usr/share/examples/etc/make.conf
613.It Pa /usr/src/Makefile
614.It Pa /usr/src/Makefile.inc1
615.El
616.Sh EXAMPLES
617For an
618.Dq approved
619method of updating your system from the latest sources, please see the
620.Sx COMMON ITEMS
621section in
622.Pa src/UPDATING .
623.Pp
624The following sequence of commands can be used to cross-build the
625system for the sparc64 architecture on an i386 host:
626.Bd -literal -offset indent
627cd /usr/src
628make TARGET=sparc64 buildworld
629make TARGET=sparc64 DESTDIR=/clients/sparc64 installworld
630.Ed
631.Sh SEE ALSO
632.Xr cc 1 ,
633.Xr install 1 ,
634.Xr make 1 ,
635.Xr svn 1 ,
636.Xr make.conf 5 ,
637.Xr src.conf 5 ,
638.Xr ports 7 ,
639.Xr release 7 ,
640.Xr config 8 ,
641.Xr mergemaster 8 ,
642.Xr portsnap 8 ,
643.Xr reboot 8 ,
644.Xr shutdown 8
645.Sh AUTHORS
646.An Mike W. Meyer Aq Mt mwm@mired.org
647