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:

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 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 a buildkernel 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:

Convenience targets for cleaning up the install destination directory denoted by variable DESTDIR include:

ENVIRONMENT

Variables that influence all builds include:

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, NO_KERNELDEPEND and NO_KERNELOBJ. When set to a value other than 1 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 and distributeworld 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 and installkernel process.

make PORTS_MODULES=emulators/kqemu-kmod kernel

SUBDIR_OVERRIDE

Override the default list of sub-directories and only build the sub-directory named in this variable. This variable is 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):

Builds under directory /usr/doc are influenced by the following make(1) variables:

Builds using the universe target are influenced by the following make(1) variables:

FILES

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

AUTHORS

Mike W. Meyer <mwm@mired.org>.

YOS OPENSONAR