NAME
build
—
information on how to build the
system
DESCRIPTION
The sources for the FreeBSD system and its applications are contained in three different directories, normally /usr/src, /usr/doc, and /usr/ports. These directories may be initially empty or non-existent until updated with svn(1) or portsnap(8). Directory /usr/src contains the “base system” sources, which is loosely defined as the things required to rebuild the system to a useful state. Directory /usr/doc contains the source for the system documentation, excluding the manual pages. Directory /usr/ports contains a tree that provides a consistent interface for building and installing third party applications. For more information about the ports build process, see ports(7).The make(1) command is used in each of these directories to build and install the things in that directory. Issuing the make(1) command in any directory or subdirectory of those directories has the same effect as issuing the same command in all subdirectories of that directory. With no target specified, the things in that directory are just built.
A source tree is allowed to be read-only. As described in
make(1), objects are usually built in a separate object directory
hierarchy specified by the environment variable
MAKEOBJDIRPREFIX, or under
/usr/obj if variable
MAKEOBJDIRPREFIX is not set. For a given source
directory, its canonical object directory would be
${MAKEOBJDIRPREFIX}${.CURDIR} if
make(1) variable MAKEOBJDIRPREFIX is set, or
/usr/obj${.CURDIR} if this variable is not set.
Cross-builds set the object directory as described in the documentation for
the buildworld
target below.
The build may be controlled by defining make(1) variables described in the ENVIRONMENT section below, and by the variables documented in make.conf(5).
The following list provides the names and actions for the targets supported by the build system:
analyze
- Run Clang static analyzer against all objects and present output on stdout.
check
- Run tests for a given subdirectory. The default directory used is ${.OBJDIR}, but the check directory can be changed with ${CHECKDIR}.
checkworld
- Run the FreeBSD test suite on installed world.
clean
- Remove any files created during the build process.
cleandepend
- Remove the ${.OBJDIR}/${DEPENDFILE}* files
generated by prior “
make
” and “make depend
” steps. cleandir
- Remove the canonical object directory if it exists, or perform actions
equivalent to “
make clean cleandepend
” if it does not. This target will also remove an obj link in ${.CURDIR} if that exists.It is advisable to run “
make cleandir
” twice: the first invocation will remove the canonical object directory and the second one will clean up ${.CURDIR}. depend
- Generate a list of build dependencies in file ${.OBJDIR}/${DEPENDFILE}. Per-object dependencies are generated at build time and stored in ${.OBJDIR}/${DEPENDFILE}.${OBJ}.
install
- Install the results of the build to the appropriate location in the installation directory hierarchy specified in variable DESTDIR.
obj
- Create the canonical object directory associated with the current directory.
objlink
- Create a symbolic link to the canonical object directory in ${.CURDIR}.
- Generate a tags file using the program specified in the
make(1) variable CTAGS. The build system
supports ctags(1) and
GNU Global
.
The other supported targets under directory /usr/src are:
buildenv
- Spawn an interactive shell with environment variables set up for
cross-building the system. The target architecture needs to be specified
with make(1) variables TARGET_ARCH and
TARGET.
This target is only useful after a complete cross-toolchain including the compiler, linker, assembler, headers and libraries has been built; see the
toolchain
target below. buildworld
- Build everything but the kernel, configure files in etc, and release. The object directory can be changed from the default /usr/obj by setting the MAKEOBJDIRPREFIX make(1) variable. The actual build location prefix used is ${MAKEOBJDIRPREFIX}${.CURDIR} for native builds, and ${MAKEOBJDIRPREFIX}/${TARGET}${.CURDIR} for cross builds and native builds with variable CROSS_BUILD_TESTING set.
cleanworld
- Attempt to clean up targets built by a preceding
buildworld
step. distributeworld
- Distribute everything compiled by a preceding
buildworld
step. Files are placed in the directory hierarchy specified by make(1) variable DISTDIR. This target is used while building a release; see release(7). packageworld
- Archive the results of
distributeworld
, placing the results in DISTDIR. This target is used while building a release; see release(7). installworld
- Install everything built by a preceding
buildworld
step into the directory hierarchy pointed to by make(1) variable DESTDIR.If installing onto an NFS file system and running make(1) with the
-j
option, make sure that rpc.lockd(8) is running on both client and server. See rc.conf(5) on how to make it start at boot time. toolchain
- Create the build toolchain needed to build the rest of the system. For cross-architecture builds, this step creates a cross-toolchain.
universe
- For each architecture, execute a
buildworld
followed by abuildkernel
for all kernels for that architecture, including LINT. This command takes a long time. update
- Get updated sources as configured in make.conf(5).
targets
- Print a list of supported TARGET / TARGET_ARCH pairs for world and kernel targets.
tinderbox
- Execute the same targets as
universe
. In addition print a summary of all failed targets at the end and exit with an error if there were any. toolchains
- Create a build toolchain for each architecture supported by the build system.
Kernel specific build targets in /usr/src are:
buildkernel
- Rebuild the kernel and the kernel modules. The object directory can be changed from the default /usr/obj by setting the MAKEOBJDIRPREFIX make(1) variable.
installkernel
- Install the kernel and the kernel modules to directory ${DESTDIR}/boot/kernel, renaming any pre-existing directory with this name to kernel.old if it contained the currently running kernel. The target directory under ${DESTDIR} may be modified using the INSTKERNNAME and KODIR make(1) variables.
distributekernel
- Install the kernel to the directory ${DISTDIR}/kernel/boot/kernel. This target is used while building a release; see release(7).
packagekernel
- Archive the results of
distributekernel
, placing the results in DISTDIR. This target is used while building a release; see release(7). kernel
- Equivalent to
buildkernel
followed byinstallkernel
kernel-toolchain
- Rebuild the tools needed for kernel compilation. Use this if you did not
do a
buildworld
first. reinstallkernel
- Reinstall the kernel and the kernel modules, overwriting the contents of
the target directory. As with the
installkernel
target, the target directory can be specified using the make(1) variable INSTKERNNAME.
Convenience targets for cleaning up the install destination directory denoted by variable DESTDIR include:
check-old
- Print a list of old files and directories in the system.
delete-old
- Delete obsolete base system files and directories interactively. When
-DBATCH_DELETE_OLD_FILES
is specified at the command line, the delete operation will be non-interactive. The variables DESTDIR, TARGET_ARCH and TARGET should be set as with “make installworld
”. delete-old-libs
- Delete obsolete base system libraries interactively. This target should
only be used if no third party software uses these libraries. When
-DBATCH_DELETE_OLD_FILES
is specified at the command line, the delete operation will be non-interactive. The variables DESTDIR, TARGET_ARCH and TARGET should be set as with “make installworld
”.
ENVIRONMENT
Variables that influence all builds include:
- DEBUG_FLAGS
- Defines a set of debugging flags that will be used to build all userland
binaries under /usr/src. When
DEBUG_FLAGS is defined, the
install
andinstallworld
targets install binaries from the current MAKEOBJDIRPREFIX without stripping, so that debugging information is retained in the installed binaries. - DESTDIR
- The directory hierarchy prefix where built objects will be installed. If not set, DESTDIR defaults to the empty string.
- MAKEOBJDIRPREFIX
- Defines the prefix for directory names in the tree of built objects. Defaults to /usr/obj if not defined. This variable should only be set in the environment and not via /etc/make.conf or the command line.
- NO_WERROR
- If defined, compiler warnings will not cause the build to halt, even if the makefile says otherwise.
- WITH_CTF
- If defined, the build process will run the DTrace CTF conversion tools on built objects.
Additionally, builds in /usr/src are influenced by the following make(1) variables:
- KERNCONF
- Overrides which kernel to build and install for the various kernel make
targets. It defaults to
GENERIC
. - KERNFAST
- If set, the build target
buildkernel
defaults to setting NO_KERNELCLEAN, NO_KERNELCONFIG, and NO_KERNELOBJ. When set to a value other than1
then KERNCONF is set to the value of KERNFAST. - 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
everything
target. - LOCAL_ITOOLS
- If set, this variable supplies a list of additional tools that are used by
the
installworld
anddistributeworld
targets. - 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
libraries
target. - 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
hierarchy
target. - 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
build-tools
target. - PORTS_MODULES
- A list of ports with kernel modules that should be built and installed as
part of the
buildkernel
andinstallkernel
process.make PORTS_MODULES=emulators/kqemu-kmod kernel
- STRIPBIN
- Command to use at install time when stripping binaries. Be sure to add any
additional tools required to run STRIPBIN to the
LOCAL_ITOOLS
make(1) variable before running the
distributeworld
orinstallworld
targets. See install(1) for more details. - SUBDIR_OVERRIDE
- Override the default list of sub-directories and only build the
sub-directory named in this variable. If combined with
buildworld
then all libraries and includes, and some of the build tools will still build as well. When combined withbuildworld
it is necesarry to override LOCAL_LIB_DIRS with any custom directories containing libraries. This allows building a subset of the system in the same way asbuildworld
does using its sysroot handling. This variable can also be useful when debugging failed builds.make some-target SUBDIR_OVERRIDE=foo/bar
- TARGET
- The target hardware platform. This is analogous to the
“
uname
-m
” output. This is necessary to cross-build some target architectures. For example, cross-building for PC98 machines requires TARGET_ARCH=i386
and TARGET=pc98
. If not set, TARGET defaults to the current hardware platform. - TARGET_ARCH
- The target machine processor architecture. This is analogous to the
“
uname
-p
” output. Set this to cross-build for a different architecture. If not set, TARGET_ARCH defaults to the current machine architecture, unless TARGET is also set, in which case it defaults to the appropriate value for that platform. Typically, one only needs to set TARGET.
Builds under directory /usr/src are also
influenced by defining one or more of the following symbols, using the
-D
option of
make(1):
- NO_CLEANDIR
- If set, the build targets that clean parts of the object tree use the equivalent of “make clean” instead of “make cleandir”.
- NO_CLEAN
- If set, no object tree files are cleaned at all. This is the default when WITH_META_MODE is used with filemon(4) loaded. See src.conf(5) for more details. Setting NO_CLEAN implies NO_KERNELCLEAN, so when NO_CLEAN is set no kernel objects are cleaned either.
- NO_CTF
- If set, the build process does not run the DTrace CTF conversion tools on built objects.
- NO_SHARE
- If set, the build does not descend into the /usr/src/share subdirectory (i.e., manual pages, locale data files, timezone data files and other /usr/src/share files will not be rebuild from their sources).
- NO_KERNELCLEAN
- If set, the build process does not run “make clean” as part
of the
buildkernel
target. - NO_KERNELCONFIG
- If set, the build process does not run
config(8) as part of the
buildkernel
target. - NO_KERNELOBJ
- If set, the build process does not run “make obj” as part of
the
buildkernel
target. - NO_DOCUPDATE
- If set, the update process does not update the source of the FreeBSD documentation as part of the “make update” target.
- NO_PORTSUPDATE
- If set, the update process does not update the Ports tree as part of the “make update” target.
- NO_WWWUPDATE
- If set, the update process does not update the www tree as part of the “make update” target.
Builds under directory /usr/doc are influenced by the following make(1) variables:
- 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.
Builds using the universe
target are
influenced by the following
make(1) variables:
- JFLAG
- Pass the value of this variable to each 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.
- MAKE_JUST_KERNELS
- Only build kernels for each supported architecture.
- MAKE_JUST_WORLDS
- Only build worlds for each supported architecture.
- UNIVERSE_TARGET
- Execute the specified make(1) target for each supported architecture instead of the default action of building a world and one or more kernels.
FILES
- /usr/doc/Makefile
- /usr/doc/share/mk/doc.project.mk
- /usr/ports/Mk/bsd.port.mk
- /usr/ports/Mk/bsd.sites.mk
- /usr/share/examples/etc/make.conf
- /usr/src/Makefile
- /usr/src/Makefile.inc1
EXAMPLES
For an “approved” method of updating your system from the latest sources, please see the COMMON ITEMS section in src/UPDATING.
The following sequence of commands can be used to cross-build the system for the sparc64 architecture on an i386 host:
cd /usr/src make TARGET=sparc64 buildworld make TARGET=sparc64 DESTDIR=/clients/sparc64 installworld
SEE ALSO
cc(1), install(1), make(1), svn(1), make.conf(5), src.conf(5), ports(7), release(7), tests(7), config(8), mergemaster(8), portsnap(8), reboot(8), shutdown(8)
AUTHORS
Mike W. Meyer <mwm@mired.org>