xref: /freebsd/share/man/man7/build.7 (revision 9bc300465e48e19d794d88d0c158a2adb92c7197)
1.\"-
2.\" SPDX-License-Identifier: BSD-2-Clause
3.\"
4.\" Copyright (c) 2000
5.\"	Mike W. Meyer
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.Dd June 4, 2024
29.Dt BUILD 7
30.Os
31.Sh NAME
32.Nm build
33.Nd general instructions on how to build the
34.Fx
35system
36.Sh DESCRIPTION
37The sources for the
38.Fx
39system and its applications are contained in three different directories,
40normally
41.Pa /usr/src ,
42.Pa /usr/doc ,
43and
44.Pa /usr/ports .
45These directories may be initially empty or non-existent until updated with
46Git
47.Po installed from packages with
48.Xr pkg 7
49or from
50.Xr ports 7 Pc .
51Directory
52.Pa /usr/src
53contains the
54.Dq "base system"
55sources, which is loosely defined as the things required to rebuild
56the system to a useful state.
57Directory
58.Pa /usr/doc
59contains the source for the system documentation, excluding the manual
60pages.
61Directory
62.Pa /usr/ports
63contains a tree that provides a consistent interface for building and
64installing third party applications.
65For more information about the ports build process, see
66.Xr ports 7 .
67.Pp
68The
69.Xr make 1
70command is used in each of these directories to build and install the
71things in that directory.
72Issuing the
73.Xr make 1
74command in any directory issues the
75.Xr make 1
76command recursively in all subdirectories.
77With no target specified, the items in the directories are built
78and no further action is taken.
79.Pp
80A source tree is allowed to be read-only.
81As described in
82.Xr make 1 ,
83objects are usually built in a separate object directory hierarchy
84specified by the environment variable
85.Va MAKEOBJDIRPREFIX ,
86or under
87.Pa /usr/obj
88if variable
89.Va MAKEOBJDIRPREFIX
90is not set.
91The canonical object directory is described in the documentation for the
92.Cm buildworld
93target below.
94.Pp
95The build may be controlled by defining
96.Xr make 1
97variables described in the
98.Sx ENVIRONMENT
99section below, and by the variables documented in
100.Xr make.conf 5 .
101.Pp
102The default components included in the build are specified in the file
103.Pa /etc/src.conf
104in the source tree.
105To override the default file, include the SRCCONF option in the make steps,
106pointing to a custom src.conf file.
107For more information see
108.Xr src.conf 5 .
109.Pp
110The following list provides the names and actions for the targets
111supported by the build system:
112.Bl -tag -width ".Cm cleandepend"
113.It Cm analyze
114Run Clang static analyzer against all objects and present output on stdout.
115.It Cm check
116Run tests for a given subdirectory.
117The default directory used is
118.Pa ${.OBJDIR} ,
119but the check directory can be changed with
120.Pa ${CHECKDIR} .
121.It Cm checkworld
122Run the
123.Fx
124test suite on installed world.
125.It Cm clean
126Remove any files created during the build process.
127.It Cm cleandepend
128Remove the
129.Pa ${.OBJDIR}/${DEPENDFILE}*
130files generated by prior
131.Dq Li "make"
132and
133.Dq Li "make depend"
134steps.
135.It Cm cleandir
136Remove the canonical object directory if it exists, or perform
137actions equivalent to
138.Dq Li "make clean cleandepend"
139if it does not.
140This target will also remove an
141.Pa obj
142link in
143.Pa ${.CURDIR}
144if that exists.
145.Pp
146It is advisable to run
147.Dq Li "make cleandir"
148twice: the first invocation will remove the canonical object directory
149and the second one will clean up
150.Pa ${.CURDIR} .
151.It Cm depend
152Generate a list of build dependencies in file
153.Pa ${.OBJDIR}/${DEPENDFILE} .
154Per-object dependencies are generated at build time and stored in
155.Pa ${.OBJDIR}/${DEPENDFILE}.${OBJ} .
156.It Cm install
157Install the results of the build to the appropriate location in the
158installation directory hierarchy specified in variable
159.Va DESTDIR .
160.It Cm obj
161Create the canonical object directory associated with the current
162directory.
163.It Cm objlink
164Create a symbolic link to the canonical object directory in
165.Pa ${.CURDIR} .
166.It Cm tags
167Generate a tags file using the program specified in the
168.Xr make 1
169variable
170.Va CTAGS .
171The build system supports
172.Xr ctags 1
173and
174.Nm "GNU Global" .
175.El
176.Pp
177The other supported targets under directory
178.Pa /usr/src
179are:
180.Bl -tag -width ".Cm distributeworld"
181.It Cm buildenv
182Spawn an interactive shell with environment variables set up for
183building the system or individual components.
184For cross-building the target architecture needs to be specified with
185.Xr make 1
186variables
187.Va TARGET_ARCH
188and
189.Va TARGET .
190.Pp
191This target is only useful after a complete toolchain (including
192the compiler, linker, assembler, headers and libraries) has been
193built; see the
194.Cm toolchain
195target below.
196.It Cm buildworld
197Build everything but the kernel, configure files in
198.Pa etc ,
199and
200.Pa release .
201The object directory can be changed from the default
202.Pa /usr/obj
203by setting the
204.Pa MAKEOBJDIRPREFIX
205.Xr make 1
206variable.
207The actual build location prefix used
208depends on the
209.Va WITH_UNIFIED_OBJDIR
210option from
211.Xr src.conf 5 .
212If enabled it is
213.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}/${TARGET}.${TARGET_ARCH}
214for all builds.
215If disabled it is
216.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
217for native builds, and
218.Pa ${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}${.CURDIR}
219for cross builds and native builds with variable
220.Va CROSS_BUILD_TESTING
221set.
222.It Cm cleankernel
223Attempts to clean up targets built by a preceding
224.Cm buildkernel ,
225or similar step, built from the same source directory and
226.Va KERNCONF .
227.It Cm cleanworld
228Attempt to clean up targets built by a preceding
229.Cm buildworld ,
230or similar step, built from this source directory.
231.It Cm cleanuniverse
232When
233.Va WITH_UNIFIED_OBJDIR
234is enabled, attempt to clean up targets built by a preceding
235.Cm buildworld ,
236.Cm universe ,
237or similar step, for any architecture built from this source directory.
238.It Cm distributeworld
239Distribute everything compiled by a preceding
240.Cm buildworld
241step.
242Files are placed in the directory hierarchy specified by
243.Xr make 1
244variable
245.Va DISTDIR .
246This target is used while building a release; see
247.Xr release 7 .
248.It Cm native-xtools
249This target builds a cross-toolchain for the given
250.Sy TARGET
251and
252.Sy TARGET_ARCH ,
253as well as a select list of static userland tools for the host system.
254This is intended to be used in a jail where QEMU is used to improve
255performance by avoiding emulating binaries that do not need to be emulated.
256.Sy TARGET
257and
258.Sy TARGET_ARCH
259should be defined.
260.It Cm native-xtools-install
261Installs the results to
262.Pa ${DESTDIR}/${NXTP}
263where
264.Va NXTP
265defaults to
266.Pa nxb-bin .
267.Sy TARGET
268and
269.Sy TARGET_ARCH
270must be defined.
271.It Cm packageworld
272Archive the results of
273.Cm distributeworld ,
274placing the results in
275.Va DISTDIR .
276This target is used while building a release; see
277.Xr release 7 .
278.It Cm installworld
279Install everything built by a preceding
280.Cm buildworld
281step into the directory hierarchy pointed to by
282.Xr make 1
283variable
284.Va DESTDIR .
285.Pp
286If installing onto an NFS file system and running
287.Xr make 1
288with the
289.Fl j
290option, make sure that
291.Xr rpc.lockd 8
292is running on both client and server.
293See
294.Xr rc.conf 5
295on how to make it start at boot time.
296.It Cm toolchain
297Create the build toolchain needed to build the rest of the system.
298For cross-architecture builds, this step creates a cross-toolchain.
299.It Cm universe
300For each architecture,
301execute a
302.Cm buildworld
303followed by a
304.Cm buildkernel
305for all kernels for that architecture,
306including
307.Pa LINT .
308This command takes a long time.
309.It Cm kernels
310Like
311.Cm universe
312with
313.Va WITHOUT_WORLDS
314defined so only the kernels for each architecture are built.
315.It Cm worlds
316Like
317.Cm universe
318with
319.Va WITHOUT_KERNELS
320defined so only the worlds for each architecture are built.
321.It Cm targets
322Print a list of supported
323.Va TARGET
324/
325.Va TARGET_ARCH
326pairs for world and kernel targets.
327.It Cm tinderbox
328Execute the same targets as
329.Cm universe .
330In addition print a summary of all failed targets at the end and
331exit with an error if there were any.
332.It Cm toolchains
333Create a build toolchain for each architecture supported by the build system.
334.It Cm xdev
335Builds and installs a cross-toolchain and sysroot for the given
336.Sy TARGET
337and
338.Sy TARGET_ARCH .
339The sysroot contains target library and headers.
340The target is an alias for
341.Cm xdev-build
342and
343.Cm xdev-install .
344The location of the files installed can be controlled with
345.Va DESTDIR .
346The target location in
347.Va DESTDIR
348is
349.Pa ${DESTDIR}/${XDTP}
350where
351.Va XDTP
352defaults to
353.Pa /usr/${XDDIR}
354and
355.Va XDDIR
356defaults to
357.Pa ${TARGET_ARCH}-freebsd .
358.It Cm xdev-build
359Builds for the
360.Cm xdev
361target.
362.It Cm xdev-install
363Installs the files for the
364.Cm xdev
365target.
366.It Cm xdev-links
367Installs autoconf-style symlinks to
368.Pa ${DESTDIR}/usr/bin
369pointing into the xdev toolchain in
370.Pa ${DESTDIR}/${XDTP} .
371.El
372.Pp
373Kernel specific build targets in
374.Pa /usr/src
375are:
376.Bl -tag -width ".Cm distributekernel"
377.It Cm buildkernel
378Rebuild the kernel and the kernel modules.
379The object directory can be changed from the default
380.Pa /usr/obj
381by setting the
382.Pa MAKEOBJDIRPREFIX
383.Xr make 1
384variable.
385.It Cm installkernel
386Install the kernel and the kernel modules to directory
387.Pa ${DESTDIR}/boot/kernel ,
388renaming any pre-existing directory with this name to
389.Pa kernel.old
390if it contained the currently running kernel.
391The target directory under
392.Pa ${DESTDIR}
393may be modified using the
394.Va INSTKERNNAME
395and
396.Va KODIR
397.Xr make 1
398variables.
399.It Cm distributekernel
400Install the kernel to the directory
401.Pa ${DISTDIR}/kernel/boot/kernel .
402This target is used while building a release; see
403.Xr release 7 .
404.It Cm packagekernel
405Archive the results of
406.Cm distributekernel ,
407placing the results in
408.Va DISTDIR .
409This target is used while building a release; see
410.Xr release 7 .
411.It Cm kernel
412Equivalent to
413.Cm buildkernel
414followed by
415.Cm installkernel
416.It Cm kernel-toolchain
417Rebuild the tools needed for kernel compilation.
418Use this if you did not do a
419.Cm buildworld
420first.
421.It Cm reinstallkernel
422Reinstall the kernel and the kernel modules, overwriting the contents
423of the target directory.
424As with the
425.Cm installkernel
426target, the target directory can be specified using the
427.Xr make 1
428variable
429.Va INSTKERNNAME .
430.El
431.Pp
432Convenience targets for cleaning up the install destination directory
433denoted by variable
434.Va DESTDIR
435include:
436.Bl -tag -width ".Cm delete-old-libs"
437.It Cm check-old
438Print a list of old files and directories in the system.
439.It Cm delete-old
440Delete obsolete base system files and directories interactively.
441When
442.Li -DBATCH_DELETE_OLD_FILES
443is specified at the command line, the delete operation will be
444non-interactive.
445The variables
446.Va DESTDIR ,
447.Va TARGET_ARCH
448and
449.Va TARGET
450should be set as with
451.Dq Li "make installworld" .
452.It Cm delete-old-libs
453Delete obsolete base system libraries interactively.
454This target should only be used if no third party software uses these
455libraries.
456When
457.Li -DBATCH_DELETE_OLD_FILES
458is specified at the command line, the delete operation will be
459non-interactive.
460The variables
461.Va DESTDIR ,
462.Va TARGET_ARCH
463and
464.Va TARGET
465should be set as with
466.Dq Li "make installworld" .
467.El
468.Sh ENVIRONMENT
469Variables that influence all builds include:
470.Bl -tag -width ".Va MAKEOBJDIRPREFIX"
471.It Va DEBUG_FLAGS
472Defines a set of debugging flags that will be used to build all userland
473binaries under
474.Pa /usr/src .
475When
476.Va DEBUG_FLAGS
477is defined, the
478.Cm install
479and
480.Cm installworld
481targets install binaries from the current
482.Va MAKEOBJDIRPREFIX
483without stripping,
484so that debugging information is retained in the installed binaries.
485.It Va DESTDIR
486The directory hierarchy prefix where built objects will be installed.
487If not set,
488.Va DESTDIR
489defaults to the empty string.
490.It Va MAKEOBJDIRPREFIX
491Defines the prefix for directory names in the tree of built objects.
492Defaults to
493.Pa /usr/obj
494if not defined.
495This variable should only be set in the environment or
496.Pa /etc/src-env.conf
497and not via
498.Pa /etc/make.conf
499or
500.Pa /etc/src.conf
501or the command line.
502.It Va WITHOUT_WERROR
503If defined, compiler warnings will not cause the build to halt,
504even if the makefile says otherwise.
505.It Va WITH_CTF
506If defined, the build process will run the DTrace CTF conversion
507tools on built objects.
508.El
509.Pp
510Additionally, builds in
511.Pa /usr/src
512are influenced by the following
513.Xr make 1
514variables:
515.Bl -tag -width ".Va LOCAL_MODULES_DIR"
516.It Va CROSS_TOOLCHAIN
517Requests use of an external toolchain to build either the world or kernel.
518This value of this variable can either be the full path to a file,
519or the base name of a file in
520.Pa ${LOCALBASE}/share/toolchains .
521The file should be a make file which sets variables to request an external
522toolchain such as
523.Va XCC .
524.Pp
525External toolchains are available in ports for both LLVM and GCC/binutils.
526For external toolchains available in ports,
527.Va CROSS_TOOLCHAIN
528should be set to the name of the package.
529LLVM toolchain packages use the name llvm<major version>.
530GCC toolchains provide separate packages for each architecture and use the
531name ${MACHINE_ARCH}-gcc<major version>.
532.It Va KERNCONF
533Overrides which kernel to build and install for the various kernel
534make targets.
535It defaults to
536.Cm GENERIC .
537.It Va KERNCONFDIR
538Overrides the directory in which
539.Va KERNCONF
540and any files included by
541.Va KERNCONF
542should be found.
543Defaults to
544.Pa sys/${ARCH}/conf .
545.It Va KERNFAST
546If set, the build target
547.Cm buildkernel
548defaults to setting
549.Va NO_KERNELCLEAN ,
550.Va NO_KERNELCONFIG ,
551and
552.Va NO_KERNELOBJ .
553When set to a value other than
554.Cm 1
555then
556.Va KERNCONF
557is set to the value of
558.Va KERNFAST .
559.It Va LOCAL_DIRS
560If set, this variable supplies a list of additional directories relative to
561the root of the source tree to build as part of the
562.Cm everything
563target.
564The directories are built in parallel with each other,
565and with the base system directories.
566Insert a
567.Va .WAIT
568directive at the beginning of the
569.Va LOCAL_DIRS
570list to ensure all base system directories are built first.
571.Va .WAIT
572may also be used as needed elsewhere within the list.
573.It Va LOCAL_ITOOLS
574If set, this variable supplies a list of additional tools that are used by the
575.Cm installworld
576and
577.Cm distributeworld
578targets.
579.It Va LOCAL_LIB_DIRS
580If set, this variable supplies a list of additional directories relative to
581the root of the source tree to build as part of the
582.Cm libraries
583target.
584The directories are built in parallel with each other,
585and with the base system libraries.
586Insert a
587.Va .WAIT
588directive at the beginning of the
589.Va LOCAL_DIRS
590list to ensure all base system libraries are built first.
591.Va .WAIT
592may also be used as needed elsewhere within the list.
593.It Va LOCAL_MTREE
594If set, this variable supplies a list of additional mtrees relative to the
595root of the source tree to use as part of the
596.Cm hierarchy
597target.
598.It Va LOCAL_LEGACY_DIRS
599If set, this variable supplies a list of additional directories relative to
600the root of the source tree to build as part of the
601.Cm legacy
602target.
603.It Va LOCAL_BSTOOL_DIRS
604If set, this variable supplies a list of additional directories relative to
605the root of the source tree to build as part of the
606.Cm bootstrap-tools
607target.
608.It Va LOCAL_TOOL_DIRS
609If set, this variable supplies a list of additional directories relative to
610the root of the source tree to build as part of the
611.Cm build-tools
612target.
613.It Va LOCAL_XTOOL_DIRS
614If set, this variable supplies a list of additional directories relative to
615the root of the source tree to build as part of the
616.Cm cross-tools
617target.
618.It Va PORTS_MODULES
619A list of ports with kernel modules that should be built and installed
620as part of the
621.Cm buildkernel
622and
623.Cm installkernel
624process.
625.Bd -literal -offset indent
626make PORTS_MODULES=emulators/virtualbox-ose-kmod kernel
627.Ed
628.It Va LOCAL_MODULES
629A list of external kernel modules that should be built and installed
630as part of the
631.Cm buildkernel
632and
633.Cm installkernel
634process.
635Defaults to the list of sub-directories of
636.Va LOCAL_MODULES_DIR .
637.It Va LOCAL_MODULES_DIR
638The directory in which to search for the kernel modules specified by
639.Va LOCAL_MODULES .
640Each kernel module should consist of a directory containing a makefile.
641Defaults to
642.Pa ${LOCALBASE}/sys/modules .
643.It Va SRCCONF
644Specify a file to override the default
645.Pa /etc/src.conf .
646The src.conf file controls the components to build.
647See
648.Xr src.conf 5
649.It Va STRIPBIN
650Command to use at install time when stripping binaries.
651Be sure to add any additional tools required to run
652.Va STRIPBIN
653to the
654.Va LOCAL_ITOOLS
655.Xr make 1
656variable before running the
657.Cm distributeworld
658or
659.Cm installworld
660targets.
661See
662.Xr install 1
663for more details.
664.It Va SUBDIR_OVERRIDE
665Override the default list of sub-directories and only build the
666sub-directory named in this variable.
667If combined with
668.Cm buildworld
669then all libraries and includes, and some of the build tools will still build
670as well.
671Specifying
672.Cm -DNO_LIBS ,
673and
674.Cm -DWORLDFAST
675will only build the specified directory as was done historically.
676When combined with
677.Cm buildworld
678it is necessary to override
679.Va LOCAL_LIB_DIRS
680with any custom directories containing libraries.
681This allows building a subset of the system in the same way as
682.Cm buildworld
683does using its sysroot handling.
684This variable can also be useful when debugging failed builds.
685.Bd -literal -offset indent
686make some-target SUBDIR_OVERRIDE=foo/bar
687.Ed
688.It Va SYSDIR
689Specify the location of the kernel source to override the default
690.Pa /usr/src/sys .
691The kernel source is located in the
692.Pa sys
693subdirectory of the source tree checked out from the
694.Pa src.git
695repository.
696.It Va TARGET
697The target hardware platform.
698This is analogous to the
699.Dq Nm uname Fl m
700output.
701This is necessary to cross-build some target architectures.
702For example, cross-building for ARM64 machines requires
703.Va TARGET_ARCH Ns = Ns Li aarch64
704and
705.Va TARGET Ns = Ns Li arm64 .
706If not set,
707.Va TARGET
708defaults to the current hardware platform, unless
709.Va TARGET_ARCH
710is also set, in which case it defaults to the appropriate
711value for that architecture.
712.It Va TARGET_ARCH
713The target machine processor architecture.
714This is analogous to the
715.Dq Nm uname Fl p
716output.
717Set this to cross-build for a different architecture.
718If not set,
719.Va TARGET_ARCH
720defaults to the current machine architecture, unless
721.Va TARGET
722is also set, in which case it defaults to the appropriate
723value for that platform.
724Typically, one only needs to set
725.Va TARGET .
726.El
727.Pp
728Builds under directory
729.Pa /usr/src
730are also influenced by defining one or more of the following symbols,
731using the
732.Fl D
733option of
734.Xr make 1 :
735.Bl -tag -width ".Va LOADER_DEFAULT_INTERP"
736.It Va LOADER_DEFAULT_INTERP
737Defines what interpreter the default loader program will have.
738Valid values include
739.Dq 4th ,
740.Dq lua ,
741and
742.Dq simp .
743This creates the default link for
744.Pa /boot/loader
745to the loader with that interpreter.
746It also determines what interpreter is compiled into
747.Pa userboot .
748.It Va NO_CLEANDIR
749If set, the build targets that clean parts of the object tree use the
750equivalent of
751.Dq make clean
752instead of
753.Dq make cleandir .
754.It Va NO_CLEAN
755If set, no object tree files are cleaned at all.
756This is the default when
757.Va WITH_META_MODE
758is used with
759.Xr filemon 4
760loaded.
761See
762.Xr src.conf 5
763for more details.
764Setting
765.Va NO_CLEAN
766implies
767.Va NO_KERNELCLEAN ,
768so when
769.Va NO_CLEAN
770is set no kernel objects are cleaned either.
771.It Va NO_CTF
772If set, the build process does not run the DTrace CTF conversion tools
773on built objects.
774.It Va NO_SHARE
775If set, the build does not descend into the
776.Pa /usr/src/share
777subdirectory (i.e., manual pages, locale data files, timezone data files and
778other
779.Pa /usr/src/share
780files will not be rebuild from their sources).
781.It Va NO_KERNELCLEAN
782If set, the build process does not run
783.Dq make clean
784as part of the
785.Cm buildkernel
786target.
787.It Va NO_KERNELCONFIG
788If set, the build process does not run
789.Xr config 8
790as part of the
791.Cm buildkernel
792target.
793.It Va NO_KERNELOBJ
794If set, the build process does not run
795.Dq make obj
796as part of the
797.Cm buildkernel
798target.
799.It Va NO_LIBS
800If set, the libraries phase will be skipped.
801.It Va NO_OBJWALK
802If set, no object directories will be created.
803This should only be used if object directories were created in a
804previous build and no new directories are connected.
805.It Va UNIVERSE_TOOLCHAIN
806Requests use of the toolchain built as part of the
807.Cm universe
808target as an external toolchain.
809.It Va WORLDFAST
810If set, the build target
811.Cm buildworld
812defaults to setting
813.Va NO_CLEAN ,
814.Va NO_OBJWALK ,
815and will skip most bootstrap phases.
816It will only bootstrap libraries and build all of userland.
817This option should be used only when it is known that none of the bootstrap
818needs changed and that no new directories have been connected to the build.
819.El
820.Pp
821Builds under directory
822.Pa /usr/doc
823are influenced by the following
824.Xr make 1
825variables:
826.Bl -tag -width ".Va DOC_LANG"
827.It Va DOC_LANG
828If set, restricts the documentation build to the language subdirectories
829specified as its content.
830The default action is to build documentation for all languages.
831.El
832.Pp
833Builds using the
834.Cm universe
835and related targets are influenced by the following
836.Xr make 1
837variables:
838.Bl -tag -width ".Va USE_GCC_TOOLCHAINS"
839.It Va JFLAG
840Pass the value of this variable to each
841.Xr make 1
842invocation used to build worlds and kernels.
843This can be used to enable multiple jobs within a single architecture's build
844while still building each architecture serially.
845.It Va MAKE_JUST_KERNELS
846Only build kernels for each supported architecture.
847.It Va MAKE_JUST_WORLDS
848Only build worlds for each supported architecture.
849.It Va WITHOUT_WORLDS
850Only build kernels for each supported architecture.
851.It Va WITHOUT_KERNELS
852Only build worlds for each supported architecture.
853.It Va UNIVERSE_TARGET
854Execute the specified
855.Xr make 1
856target for each supported architecture instead of the default action of
857building a world and one or more kernels.
858This variable implies
859.Va WITHOUT_KERNELS .
860.It Va USE_GCC_TOOLCHAINS
861Use external GCC toolchains to build the requested targets.
862If the required toolchain package for a supported architecture is not installed,
863the build for that architecture is skipped.
864.It Va TARGETS
865Only build the listed targets instead of each supported architecture.
866.It Va EXTRA_TARGETS
867In addition to the supported architectures, build the semi-supported
868architectures.
869A semi-supported architecture has build support in the
870.Fx
871tree, but receives significantly less testing and is generally for
872fringe uses that do not have a wide appeal.
873.El
874.Sh FILES
875.Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
876.It Pa /usr/doc/Makefile
877.It Pa /usr/doc/share/mk/doc.project.mk
878.It Pa /usr/ports/Mk/bsd.port.mk
879.It Pa /usr/ports/Mk/bsd.sites.mk
880.It Pa /usr/share/examples/etc/make.conf
881.It Pa /usr/src/Makefile
882.It Pa /usr/src/Makefile.inc1
883.El
884.Sh EXAMPLES
885For an
886.Dq approved
887method of updating your system from the latest sources, please see the
888.Sx COMMON ITEMS
889section in
890.Pa src/UPDATING .
891.Pp
892The following sequence of commands can be used to cross-build the system for
893the arm64 (aarch64) architecture on a different host architecture, such as
894amd64:
895.Bd -literal -offset indent
896cd /usr/src
897make TARGET=arm64 buildworld buildkernel
898make TARGET=arm64 DESTDIR=/clients/arm64 installworld installkernel
899.Ed
900.Sh SEE ALSO
901.Xr cc 1 ,
902.Xr install 1 ,
903.Xr make 1 ,
904.Xr make.conf 5 ,
905.Xr src.conf 5 ,
906.Xr arch 7 ,
907.Xr development 7 ,
908.Xr pkg 7 ,
909.Xr ports 7 ,
910.Xr release 7 ,
911.Xr tests 7 ,
912.Xr config 8 ,
913.Xr etcupdate 8 ,
914.Xr reboot 8 ,
915.Xr shutdown 8
916.Sh HISTORY
917The
918.Nm
919manpage first appeared in
920.Fx 4.3 .
921.Sh AUTHORS
922.An Mike W. Meyer Aq Mt mwm@mired.org
923