.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2000
.\" Mike W. Meyer
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd September 25, 2025
.Dt BUILD 7
.Os
.Sh NAME
.Nm build
.Nd general instructions on how to build the
.Fx
system
.Sh DESCRIPTION
The sources for the
.Fx
system and its applications are contained in three directories,
normally:
.Bl -tag -width "/usr/ports"
.It Pa /usr/src
.Dq base system ,
loosely defined as everything required to build the system
to a useful state
.It Pa /usr/doc
system documentation, excluding manual pages
.It Pa /usr/ports
third-party software, with a consistent interface for building and
installing them; see
.Xr ports 7
.El
.Pp
These directories may be initially empty or non-existent until updated
with Git
.Po Pa devel/git
from the
.Fx
Ports Collection
.Pc .
.Pp
The
.Xr make 1
command is used in each of these directories to build and install the
things in that directory.
Issuing the
.Xr make 1
command in any directory issues the
.Xr make 1
command recursively in all subdirectories.
With no target specified, the items in the directories are built
and no further action is taken.
.Pp
A source tree is allowed to be read-only.
As described in
.Xr make 1 ,
objects are usually built in a separate object directory hierarchy
specified by the environment variable
.Va MAKEOBJDIRPREFIX ,
or under
.Pa /usr/obj
if variable
.Va MAKEOBJDIRPREFIX
is not set.
The canonical object directory is described in the documentation for the
.Cm buildworld
target below.
.Pp
The
.Nm
may be controlled by defining
.Xr make 1
variables described in the
.Sx ENVIRONMENT
section below, and by the variables documented in
.Xr make.conf 5 .
.Pp
The default components included in the build are specified in the file
.Pa /etc/src.conf
in the source tree.
To override the default file, include the SRCCONF option in the make steps,
pointing to a custom src.conf file.
For more information see
.Xr src.conf 5 .
.Pp
The following list provides the names and actions for the targets
supported by the build system:
.Bl -tag -width ".Cm cleandepend"
.It Cm analyze
Run Clang static analyzer against all objects and present output on stdout.
.It Cm check
Run tests for a given subdirectory.
The default directory used is
.Pa ${.OBJDIR} ,
but the check directory can be changed with
.Pa ${CHECKDIR} .
.It Cm checkworld
Run the
.Fx
test suite on installed world.
.It Cm clean
Remove any files created during the build process.
.It Cm cleandepend
Remove the
.Pa ${.OBJDIR}/${DEPENDFILE}*
files generated by prior
.Dq Li "make"
and
.Dq Li "make depend"
steps.
.It Cm cleandir
Remove the canonical object directory if it exists, or perform
actions equivalent to
.Dq Li "make clean cleandepend"
if it does not.
This target will also remove an
.Pa obj
link in
.Pa ${.CURDIR}
if that exists.
.Pp
It is advisable to run
.Dq Li "make cleandir"
twice: the first invocation will remove the canonical object directory
and the second one will clean up
.Pa ${.CURDIR} .
.It Cm depend
Generate a list of build dependencies in file
.Pa ${.OBJDIR}/${DEPENDFILE} .
Per-object dependencies are generated at build time and stored in
.Pa ${.OBJDIR}/${DEPENDFILE}.${OBJ} .
.It Cm install
Install the results of the build to the appropriate location in the
installation directory hierarchy specified in variable
.Va DESTDIR .
.It Cm obj
Create the canonical object directory associated with the current
directory.
.It Cm objlink
Create a symbolic link to the canonical object directory in
.Pa ${.CURDIR} .
.It Cm tags
Generate a tags file using the program specified in the
.Xr make 1
variable
.Va CTAGS .
The build system supports
.Xr ctags 1
and
.Nm "GNU Global" .
.El
.Pp
The other supported targets under directory
.Pa /usr/src
are:
.Bl -tag -width ".Cm distributeworld"
.It Cm buildenv
Spawn an interactive shell with environment variables set up for
building the system or individual components.
For cross-building the target architecture needs to be specified with
.Xr make 1
variables
.Va TARGET_ARCH
and
.Va TARGET .
.Pp
This target is only useful after a complete toolchain (including
the compiler, linker, assembler, headers and libraries) has been
built; see the
.Cm toolchain
target below.
.Pp
.Va BUILDENV_SHELL ,
which defaults to
.Pa /bin/sh ,
is executed.
This can be set to a command that does something in this build environment,
like cross build an application.
If that application has dependencies, though, the
.Pa devel/poudriere
package or port provides a more generic solution.
.It Cm buildenvvars
Print the shell variables that are set for a
.Cm buildenv
envirnoment and exit.
.It Cm buildworld
Build everything but the kernel, configure files in
.Pa etc ,
and
.Pa release .
The object directory can be changed from the default
.Pa /usr/obj
by setting the
.Pa MAKEOBJDIRPREFIX
.Xr make 1
variable.
The actual build location prefix used
depends on the
.Va WITH_UNIFIED_OBJDIR
option from
.Xr src.conf 5 .
If enabled it is
.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}/${TARGET}.${TARGET_ARCH}
for all builds.
If disabled it is
.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
for native builds, and
.Pa ${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}${.CURDIR}
for cross builds and native builds with variable
.Va CROSS_BUILD_TESTING
set.
.It Cm cleankernel
Attempts to clean up targets built by a preceding
.Cm buildkernel ,
or similar step, built from the same source directory and
.Va KERNCONF .
.It Cm cleanworld
Attempt to clean up targets built by a preceding
.Cm buildworld ,
or similar step, built from this source directory.
.It Cm cleanuniverse
When
.Va WITH_UNIFIED_OBJDIR
is enabled, attempt to clean up targets built by a preceding
.Cm buildworld ,
.Cm universe ,
or similar step, for any architecture built from this source directory.
.It Cm distributeworld
Distribute everything compiled by a preceding
.Cm buildworld
step.
Files are placed in the directory hierarchy specified by
.Xr make 1
variable
.Va DISTDIR .
This target is used while building a release; see
.Xr release 7 .
.It Cm native-xtools
This target builds a cross-toolchain for the given
.Sy TARGET
and
.Sy TARGET_ARCH ,
as well as a select list of static userland tools for the host system.
This is intended to be used in a jail where QEMU is used to improve
performance by avoiding emulating binaries that do not need to be emulated.
.Sy TARGET
and
.Sy TARGET_ARCH
should be defined.
.It Cm native-xtools-install
Installs the results to
.Pa ${DESTDIR}/${NXTP}
where
.Va NXTP
defaults to
.Pa nxb-bin .
.Sy TARGET
and
.Sy TARGET_ARCH
must be defined.
.It Cm packages
Create a
.Xr freebsd-base 7
package repository containing packages that can be
used to install or upgrade the base system.
The repository is created in the object directory, under
.Pa ${REPODIR}/${PKG_ABI}
where
.Ev REPODIR
is the base directory where the repository will be created, and
.Va PKG_ABI
is the
.Xr pkg 7
ABI for the build target, for example,
.Pa /usr/obj/${SRCDIR}/repo/FreeBSD:15:amd64 .
.It Cm packageworld
Archive the results of
.Cm distributeworld ,
placing the results in
.Va DISTDIR .
This target is used while building a
.Xr release 7
and is unrelated to building
.Xr freebsd-base 7
packages.
.It Cm installworld
Install everything built by a preceding
.Cm buildworld
step into the directory hierarchy pointed to by
.Xr make 1
variable
.Va DESTDIR .
.Pp
If installing onto an NFS file system and running
.Xr make 1
with the
.Fl j
option, make sure that
.Xr rpc.lockd 8
is running on both client and server.
See
.Xr rc.conf 5
on how to make it start at boot time.
.It Cm toolchain
Create the build toolchain needed to build the rest of the system.
For cross-architecture builds, this step creates a cross-toolchain.
.It Cm universe
For each architecture,
execute a
.Cm buildworld
followed by a
.Cm buildkernel
for all kernels for that architecture,
including
.Pa LINT .
This command takes a long time.
.It Cm kernels
Like
.Cm universe
with
.Va WITHOUT_WORLDS
defined so only the kernels for each architecture are built.
.It Cm worlds
Like
.Cm universe
with
.Va WITHOUT_KERNELS
defined so only the worlds for each architecture are built.
.It Cm targets
Print a list of supported
.Va TARGET
/
.Va TARGET_ARCH
pairs for world and kernel targets.
.It Cm tinderbox
Execute the same targets as
.Cm universe .
In addition print a summary of all failed targets at the end and
exit with an error if there were any.
.It Cm toolchains
Create a build toolchain for each architecture supported by the build system.
.It Cm xdev
Builds and installs a cross-toolchain and sysroot for the given
.Sy TARGET
and
.Sy TARGET_ARCH .
The sysroot contains target library and headers.
The target is an alias for
.Cm xdev-build
and
.Cm xdev-install .
The location of the files installed can be controlled with
.Va DESTDIR .
The target location in
.Va DESTDIR
is
.Pa ${DESTDIR}/${XDTP}
where
.Va XDTP
defaults to
.Pa /usr/${XDDIR}
and
.Va XDDIR
defaults to
.Pa ${TARGET_ARCH}-freebsd .
.It Cm update-packages
Create or update the
.Xr freebsd-base 7
package repository for the base system.
If an old repository is being updated,
then packages whose contents have not changed since the previous version
will be copied into the new repository to avoid needless updating of the
version number.
.It Cm xdev-build
Builds for the
.Cm xdev
target.
.It Cm xdev-install
Installs the files for the
.Cm xdev
target.
.It Cm xdev-links
Installs autoconf-style symlinks to
.Pa ${DESTDIR}/usr/bin
pointing into the xdev toolchain in
.Pa ${DESTDIR}/${XDTP} .
.El
.Pp
Kernel specific build targets in
.Pa /usr/src
are:
.Bl -tag -width ".Cm distributekernel"
.It Cm buildkernel
Rebuild the kernel and the kernel modules.
The object directory can be changed from the default
.Pa /usr/obj
by setting the
.Pa MAKEOBJDIRPREFIX
.Xr make 1
variable.
.It Cm installkernel
Install the kernel and the kernel modules to directory
.Pa ${DESTDIR}/boot/kernel ,
renaming any pre-existing directory with this name to
.Pa kernel.old
if it contained the currently running kernel.
The target directory under
.Pa ${DESTDIR}
may be modified using the
.Va INSTKERNNAME
or
.Va KODIR
.Xr make 1
variables.
.It Cm distributekernel
Install the kernel to the directory
.Pa ${DISTDIR}/kernel/boot/kernel .
This target is used while building a release; see
.Xr release 7 .
.It Cm packagekernel
Archive the results of
.Cm distributekernel ,
placing the results in
.Va DISTDIR .
This target is used while building a
.Xr release 7
and is unrelated to building
.Xr freebsd-base 7
packages.
.It Cm kernel
Equivalent to
.Cm buildkernel
followed by
.Cm installkernel
.It Cm kernel-toolchain
Rebuild the tools needed for kernel compilation.
Use this if you did not do a
.Cm buildworld
first.
.It Cm reinstallkernel
Reinstall the kernel and the kernel modules, overwriting the contents
of the target directory.
As with the
.Cm installkernel
target, the target directory can be specified using the
.Xr make 1
variable
.Va INSTKERNNAME .
.El
.Pp
Convenience targets for cleaning up the install destination directory
denoted by variable
.Va DESTDIR
include:
.Bl -tag -width ".Cm delete-old-libs"
.It Cm check-old
Print a list of old files and directories in the system.
.It Cm check-old-libs
Print a list of obsolete base system libraries.
.It Cm delete-old
Delete obsolete base system files and directories interactively.
When
.Li -DBATCH_DELETE_OLD_FILES
is specified at the command line, the delete operation will be
non-interactive.
The variables
.Va DESTDIR ,
.Va TARGET_ARCH
and
.Va TARGET
should be set as with
.Dq Li "make installworld" .
.It Cm delete-old-libs
Delete obsolete base system libraries interactively.
This target should only be used if no third party software uses these
libraries.
When
.Li -DBATCH_DELETE_OLD_FILES
is specified at the command line, the delete operation will be
non-interactive.
The variables
.Va DESTDIR ,
.Va TARGET_ARCH
and
.Va TARGET
should be set as with
.Dq Li "make installworld" .
.El
.Sh ENVIRONMENT
Variables that influence all builds include:
.Bl -tag -width ".Va MAKEOBJDIRPREFIX"
.It Va DEBUG_FLAGS
Defines a set of debugging flags that will be used to build all userland
binaries under
.Pa /usr/src .
When
.Va DEBUG_FLAGS
is defined, the
.Cm install
and
.Cm installworld
targets install binaries from the current
.Va MAKEOBJDIRPREFIX
without stripping,
so that debugging information is retained in the installed binaries.
.It Va DESTDIR
The directory hierarchy prefix where built objects will be installed.
If not set,
.Va DESTDIR
defaults to the empty string.
If set,
.Va DESTDIR
must specify an absolute path.
.It Va MAKEOBJDIRPREFIX
Defines the prefix for directory names in the tree of built objects.
Defaults to
.Pa /usr/obj
if not defined.
This variable should only be set in the environment or
.Pa /etc/src-env.conf
and not via
.Pa /etc/make.conf
or
.Pa /etc/src.conf
or the command line.
.Va MAKEOBJDIRPREFIX
must specify an absolute path.
.It Va WITHOUT_WERROR
If defined, compiler warnings will not cause the build to halt,
even if the makefile says otherwise.
.It Va WITH_CTF
If defined, the build process will run the DTrace CTF conversion
tools on built objects.
.El
.Pp
Additionally, builds in
.Pa /usr/src
are influenced by the following
.Xr make 1
variables:
.Bl -tag -width ".Va LOCAL_MODULES_DIR"
.It Va CROSS_TOOLCHAIN
Requests use of an external toolchain to build either the world or kernel.
This value of this variable can either be the full path to a file,
or the base name of a file in
.Pa ${LOCALBASE}/share/toolchains .
The file should be a make file which sets variables to request an external
toolchain such as
.Va XCC .
.Pp
External toolchains are available in ports for both LLVM and GCC/binutils.
For external toolchains available in ports,
.Va CROSS_TOOLCHAIN
should be set to the name of the package.
LLVM toolchain packages use the name llvm<major version>.
GCC toolchains provide separate packages for each architecture and use the
name ${MACHINE_ARCH}-gcc<major version>.
.It Va INSTKERNNAME
If set, specify an alternative name to build and install for the various
kernel make targets.
.It Va KERNCONF
Overrides which kernel to build and install for the various kernel
make targets.
It defaults to
.Cm GENERIC .
.It Va KERNBUILDDIR
Overrides the default directory to get all the opt_*.h files for
building a kernel module.
Useful for stand-alone modules that depend on
.Xr config 8
options.
Automatically set for modules built with a kernel.
.It Va KERNCONFDIR
Overrides the directory in which
.Va KERNCONF
and any files included by
.Va KERNCONF
should be found.
Defaults to
.Pa sys/${ARCH}/conf .
.It Va KERNFAST
If set, the build target
.Cm buildkernel
defaults to setting
.Va NO_KERNELCLEAN ,
.Va NO_KERNELCONFIG ,
and
.Va NO_KERNELOBJ .
When set to a value other than
.Cm 1
then
.Va KERNCONF
is set to the value of
.Va KERNFAST .
.It Va KODIR
If set,
this variable specifies an alternative directory to install the kernel.
.It Va LOCAL_DIRS
If set, this variable supplies a list of additional directories relative to
the root of the source tree to build as part of the
.Cm everything
target.
The directories are built in parallel with each other,
and with the base system directories.
Insert a
.Va .WAIT
directive at the beginning of the
.Va LOCAL_DIRS
list to ensure all base system directories are built first.
.Va .WAIT
may also be used as needed elsewhere within the list.
.It Va LOCAL_ITOOLS
If set, this variable supplies a list of additional tools that are used by the
.Cm installworld
and
.Cm distributeworld
targets.
.It Va LOCAL_LIB_DIRS
If set, this variable supplies a list of additional directories relative to
the root of the source tree to build as part of the
.Cm libraries
target.
The directories are built in parallel with each other,
and with the base system libraries.
Insert a
.Va .WAIT
directive at the beginning of the
.Va LOCAL_DIRS
list to ensure all base system libraries are built first.
.Va .WAIT
may also be used as needed elsewhere within the list.
.It Va LOCAL_MTREE
If set, this variable supplies a list of additional mtrees relative to the
root of the source tree to use as part of the
.Cm hierarchy
target.
.It Va LOCAL_LEGACY_DIRS
If set, this variable supplies a list of additional directories relative to
the root of the source tree to build as part of the
.Cm legacy
target.
.It Va LOCAL_BSTOOL_DIRS
If set, this variable supplies a list of additional directories relative to
the root of the source tree to build as part of the
.Cm bootstrap-tools
target.
.It Va LOCAL_TOOL_DIRS
If set, this variable supplies a list of additional directories relative to
the root of the source tree to build as part of the
.Cm build-tools
target.
.It Va LOCAL_XTOOL_DIRS
If set, this variable supplies a list of additional directories relative to
the root of the source tree to build as part of the
.Cm cross-tools
target.
.It Va OBJROOT
The object directory root is defined as
.Pa ${OBJDIR}/${SRCDIR}/ .
See
.Pa share/mk/src.sys.obj.mk .
.It Va PKG_FORMAT
Specify a package compression format when building
.Xr freebsd-base 7
packages.
Default:
.Ql tzst .
Consider using
.Ql tar
to disable compression.
Accepted options are documented in the
.Fl f
description of
.Xr pkg-create 8 .
.It Va PORTS_MODULES
A list of ports with kernel modules that should be built and installed
as part of the
.Cm buildkernel
and
.Cm installkernel
process.
This is currently incompatible with building
.Xr freebsd-base 7
packages.
Each port must be specified as
.Ar category Ns Li / Ns Ar port Ns Op Li @ Ns Ar flavor ,
e.g.
.Bd -literal
PORTS_MODULES=graphics/gpu-firmware-intel-kmod@kabylake
PORTS_MODULES+=graphics/drm-66-kmod
.Ed
.It Va LOCAL_MODULES
A list of external kernel modules that should be built and installed
as part of the
.Cm buildkernel
and
.Cm installkernel
process.
Defaults to the list of sub-directories of
.Va LOCAL_MODULES_DIR .
.It Va LOCAL_MODULES_DIR
The directory in which to search for the kernel modules specified by
.Va LOCAL_MODULES .
Each kernel module should consist of a directory containing a makefile.
Defaults to
.Pa ${LOCALBASE}/sys/modules .
.It Va SRCCONF
Specify a file to override the default
.Pa /etc/src.conf .
The src.conf file controls the components to build.
See
.Xr src.conf 5
.It Va REPODIR
The root directory used to create the package repository for building
.Xr packges 7 .
Defaults to
.Pa ${OBJROOT}/repo/ .
This can also be set in
.Xr src-env.conf 5 .
.It Va STRIPBIN
Command to use at install time when stripping binaries.
Be sure to add any additional tools required to run
.Va STRIPBIN
to the
.Va LOCAL_ITOOLS
.Xr make 1
variable before running the
.Cm distributeworld
or
.Cm installworld
targets.
See
.Xr install 1
for more details.
.It Va SUBDIR_OVERRIDE
Override the default list of sub-directories and only build the
sub-directory named in this variable.
If combined with
.Cm buildworld
then all libraries and includes, and some of the build tools will still build
as well.
Specifying
.Cm -DNO_LIBS ,
and
.Cm -DWORLDFAST
will only build the specified directory as was done historically.
When combined with
.Cm buildworld
it is necessary to override
.Va LOCAL_LIB_DIRS
with any custom directories containing libraries.
This allows building a subset of the system in the same way as
.Cm buildworld
does using its sysroot handling.
This variable can also be useful when debugging failed builds.
.Bd -literal -offset indent
make some-target SUBDIR_OVERRIDE=foo/bar
.Ed
.It Va SYSDIR
Specify the location of the kernel source to override the default
.Pa /usr/src/sys .
The kernel source is located in the
.Pa sys
subdirectory of the source tree checked out from the
.Pa src.git
repository.
.It Va TARGET
The target hardware platform.
This is analogous to the
.Dq Nm uname Fl m
output.
This is necessary to cross-build some target architectures.
For example, cross-building for ARM64 machines requires
.Va TARGET_ARCH Ns = Ns Li aarch64
and
.Va TARGET Ns = Ns Li arm64 .
If not set,
.Va TARGET
defaults to the current hardware platform, unless
.Va TARGET_ARCH
is also set, in which case it defaults to the appropriate
value for that architecture.
.It Va TARGET_ARCH
The target machine processor architecture.
This is analogous to the
.Dq Nm uname Fl p
output.
Set this to cross-build for a different architecture.
If not set,
.Va TARGET_ARCH
defaults to the current machine architecture, unless
.Va TARGET
is also set, in which case it defaults to the appropriate
value for that platform.
Typically, one only needs to set
.Va TARGET .
.El
.Pp
Builds under directory
.Pa /usr/src
are also influenced by defining one or more of the following symbols,
using the
.Fl D
option of
.Xr make 1 :
.Bl -tag -width ".Va LOADER_DEFAULT_INTERP"
.It Va LOADER_DEFAULT_INTERP
Defines what interpreter the default loader program will have.
Valid values include
.Dq 4th ,
.Dq lua ,
and
.Dq simp .
This creates the default link for
.Pa /boot/loader
to the loader with that interpreter.
It also determines what interpreter is compiled into
.Pa userboot .
.It Va NO_CLEANDIR
If set, the build targets that clean parts of the object tree use the
equivalent of
.Dq make clean
instead of
.Dq make cleandir .
.It Va NO_CLEAN
If set, no object tree files are cleaned at all.
This is the default when
.Va WITH_META_MODE
is used with
.Xr filemon 4
loaded.
See
.Xr src.conf 5
for more details.
Setting
.Va NO_CLEAN
implies
.Va NO_KERNELCLEAN ,
so when
.Va NO_CLEAN
is set no kernel objects are cleaned either.
.It Va NO_CTF
If set, the build process does not run the DTrace CTF conversion tools
on built objects.
.It Va NO_SHARE
If set, the build does not descend into the
.Pa /usr/src/share
subdirectory (i.e., manual pages, locale data files, timezone data files and
other
.Pa /usr/src/share
files will not be rebuild from their sources).
.It Va NO_KERNELCLEAN
If set, the build process does not run
.Dq make clean
as part of the
.Cm buildkernel
target.
.It Va NO_KERNELCONFIG
If set, the build process does not run
.Xr config 8
as part of the
.Cm buildkernel
target.
.It Va NO_KERNELOBJ
If set, the build process does not run
.Dq make obj
as part of the
.Cm buildkernel
target.
.It Va NO_LIBS
If set, the libraries phase will be skipped.
.It Va NO_OBJWALK
If set, no object directories will be created.
This should only be used if object directories were created in a
previous build and no new directories are connected.
.It Va UNIVERSE_TOOLCHAIN
Requests use of the toolchain built as part of the
.Cm universe
target as an external toolchain.
.It Va WORLDFAST
If set, the build target
.Cm buildworld
defaults to setting
.Va NO_CLEAN ,
.Va NO_OBJWALK ,
and will skip most bootstrap phases.
It will only bootstrap libraries and build all of userland.
This option should be used only when it is known that none of the bootstrap
needs changed and that no new directories have been connected to the build.
.El
.Pp
Builds under directory
.Pa /usr/doc
are influenced by the following
.Xr make 1
variables:
.Bl -tag -width ".Va DOC_LANG"
.It Va DOC_LANG
If set, restricts the documentation build to the language subdirectories
specified as its content.
The default action is to build documentation for all languages.
.El
.Pp
Builds using the
.Cm universe
and related targets are influenced by the following
.Xr make 1
variables:
.Bl -tag -width ".Va USE_GCC_TOOLCHAINS"
.It Va JFLAG
Pass the value of this variable to each
.Xr make 1
invocation used to build worlds and kernels.
This can be used to enable multiple jobs within a single architecture's build
while still building each architecture serially.
.It Va MAKE_JUST_KERNELS
Only build kernels for each supported architecture.
.It Va MAKE_JUST_WORLDS
Only build worlds for each supported architecture.
.It Va WITHOUT_WORLDS
Only build kernels for each supported architecture.
.It Va WITHOUT_KERNELS
Only build worlds for each supported architecture.
.It Va UNIVERSE_TARGET
Execute the specified
.Xr make 1
target for each supported architecture instead of the default action of
building a world and one or more kernels.
This variable implies
.Va WITHOUT_KERNELS .
.It Va USE_GCC_TOOLCHAINS
Use external GCC toolchains to build the requested targets.
If the required toolchain package for a supported architecture is not installed,
the build for that architecture is skipped.
.Pp
A specific version of GCC can be used by setting the value of this variable
to the desired version
.Pq for example, Dq gcc14 ;
otherwise a default version of GCC is used.
.It Va TARGETS
Only build the listed targets instead of each supported architecture.
.It Va EXTRA_TARGETS
In addition to the supported architectures, build the semi-supported
architectures.
A semi-supported architecture has build support in the
.Fx
tree, but receives significantly less testing and is generally for
fringe uses that do not have a wide appeal.
.El
.Sh FILES
.Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
.It Pa /usr/doc/Makefile
.It Pa /usr/doc/share/mk/doc.project.mk
.It Pa /usr/ports/Mk/bsd.port.mk
.It Pa /usr/ports/Mk/bsd.sites.mk
.It Pa /usr/src/Makefile
.It Pa /usr/src/Makefile.inc1
.Xr make 1
infrastructure for each tree
.It Pa /usr/ports/UPDATING
.It Pa /usr/src/UPDATING
notable changes in each tree
.It Pa /usr/share/examples/etc/make.conf
example
.Xr make.conf 5
.It Pa /etc/src.conf
src build configuration, see
.Xr src.conf 5
.El
.Sh EXAMPLES
This section describes best practices for common situations.
When manual intervention is necessary, it will be mentioned in
.Pa UPDATING .
Make sure you have full backups before proceeding!
.Ss Example 1: Build and upgrade system in place
If using installed drivers such as graphics or virtual machine guest
drivers, check out the
.Xr ports 7
tree, and specify the drivers in
.Xr src.conf 5
so they are built and installed automatically after the kernel:
.Bd -literal -offset indent
git clone https://git.FreeBSD.org/ports.git /usr/ports
cat << EOF >> /etc/src.conf
PORTS_MODULES+=graphics/drm-kmod emulators/virtualbox-ose-kmod
EOF
.Ed
.Pp
Check out the CURRENT branch, build it, and install,
overwriting the current system:
.Bd -literal -offset indent
git clone https://git.FreeBSD.org/src.git /usr/src
cd /usr/src
make buildworld buildkernel
make installkernel
shutdown -r now
.Ed
.Pp
For major version upgrades, boot into single-user mode.
After restarting, install userspace, and merge configurations.
After verifying that you do not need them, delete old files
and libraries:
.Bd -literal -offset indent
cd /usr/src
etcupdate -p
make installworld
etcupdate -B
make delete-old delete-old-libs
shutdown -r now
.Ed
.Ss Example 2: Build and upgrade a custom kernel in place
Create a custom kernel configuration,
.Va MYKERNEL ,
by including an existing configuration and using
.Cm device Ns / Ns Cm nodevice
and
.Cm options Ns / Ns Cm nooption
to select and configure components:
.Bd -literal -offset indent
cd /usr/src
cat << EOF > sys/amd64/conf/MYKERNEL
include GENERIC
ident MYKERNEL
nodevice sound
EOF
.Ed
.Pp
After creating the new kernel configuration, build a fresh toolchain,
build the kernel, and install it, moving the old kernel to
.Pa /boot/kernel.old/ :
.Bd -literal -offset indent
make kernel-toolchain
make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=MYKERNEL
make -DALWAYS_CHECK_MAKE installkernel KERNCONF=MYKERNEL
shutdown -r now
.Ed
.Pp
To build the kernel to an alternate location, use the
.Va INSTKERNNAME
variable and boot it once to test via
.Xr nextboot 8 :
.Bd -literal -offset indent
make installkernel KERNCONF=MYKERNEL INSTKERNNAME=testkernel
nextboot -k testkernel
shutdown -r now
.Ed
.Ss Example 3: Build and upgrade a single piece of userspace
Rebuild and reinstall a single piece of userspace, in this case
.Xr ls 1 :
.Bd -literal -offset indent
cd /usr/src/bin/ls
make clean all
make install
.Ed
.Ss Example 4: Build and upgrade a loadable kernel module
Rebuild and reinstall a single loadable kernel module, in this case
.Xr sound 4 :
.Bd -literal -offset indent
cd /usr/src/sys/modules/sound
make all install clean cleandepend KMODDIR=/boot/kernel
.Ed
.Ss Example 5: Quickly rebuild a kernel in place
Quickly rebuild and reinstall the kernel, only recompiling the files
changed since last build; note that this will only work if the full
kernel build has been completed in the past, not on a fresh source tree:
.Bd -literal -offset indent
cd /usr/src
make kernel KERNFAST=1
.Ed
.Ss Example 6: Cross-compiling for different architectures
To rebuild parts of
.Fx
for another CPU architecture,
first prepare your source tree by building the cross-toolchain:
.Bd -literal -offset indent
cd src
make toolchain TARGET_ARCH=aarch64
.Ed
.Pp
The following sequence of commands can be used to cross-build the system
for the arm64 (aarch64) architecture on a different host architecture,
such as amd64:
.Bd -literal -offset indent
cd /usr/src
make TARGET_ARCH=aarch64 buildworld buildkernel
make TARGET_ARCH=aarch64 DESTDIR=/armclient installworld installkernel
.Ed
.Pp
Afterwards, to build and install a single piece of userspace, use:
.Bd -literal -offset indent
cd src/bin/ls
make buildenv TARGET_ARCH=aarch64
make clean all install DESTDIR=/armclient
.Ed
.Pp
Likewise, to quickly rebuild and reinstall the kernel, use:
.Bd -literal -offset indent
cd src
make buildenv TARGET_ARCH=aarch64
make kernel KERNFAST=1 DESTDIR=/armclient
.Ed
.Sh DIAGNOSTICS
.Bl -diag
.It Bad system call (core dumped)
.It rescue/sh check failed, installation aborted
.Pp
The kernel was not updated due to incorrect build procedure.
Study the examples above.
.Sh SEE ALSO
.Xr cc 1 ,
.Xr install 1 ,
.Xr make 1 ,
.Xr make.conf 5 ,
.Xr src.conf 5 ,
.Xr arch 7 ,
.Xr development 7 ,
.Xr freebsd-base 7 ,
.Xr pkg 7 ,
.Xr ports 7 ,
.Xr release 7 ,
.Xr tests 7 ,
.Xr config 8 ,
.Xr etcupdate 8 ,
.Xr nextboot 8 ,
.Xr shutdown 8
.Sh HISTORY
The
.Nm
manpage first appeared in
.Fx 4.3 .
.Sh AUTHORS
.An Mike W. Meyer Aq Mt [email protected]
.Sh CAVEATS
Old objects can cause obscure build problems; try
.Ql make cleandir cleandir .
.Pp
Environment poisioning can cause obscure build problems; try prefixing
.Xr make 1
commands with
.Ql env -i
.Pp
When doing a major release upgrade,
booting into single user mode for
.Cm installworld
is required.
.Pp
Updating the boot
.Xr loader 8
is architecture specific.
Consult
.Xr boot 8
for your architecture for more details.
