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