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.
$FreeBSD: head/share/man/man7/build.7 276673 2015-01-05 00:03:42Z ngie $
.Dd December 31, 2014 .Dt BUILD 7 .Os .Sh NAME .Nm build .Nd information on how to build the system .Sh DESCRIPTION The sources for the .Fx system and its applications are contained in three different directories, normally
a /usr/ports . These directories may be initially empty or non-existent until updated with .Xr svn 1 or .Xr portsnap 8 . Directory
a /usr/src contains the .Dq "base system" sources, which is loosely defined as the things required to rebuild the system to a useful state. Directory
a /usr/doc contains the source for the system documentation, excluding the manual pages. Directory
a /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 .Xr ports 7 .
p 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 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.
p 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
a /usr/obj if variable .Va MAKEOBJDIRPREFIX is not set. For a given source directory, its canonical object directory would be
a ${MAKEOBJDIRPREFIX}${.CURDIR} if .Xr make 1 variable .Va MAKEOBJDIRPREFIX is set, or
a /usr/obj${.CURDIR} if this variable is not set. Cross-builds set the object directory as described in the documentation for the .Cm buildworld target below.
p The build 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 .
p The following list provides the names and actions for the targets supported by the build system: l -tag -width ".Cm cleandepend" t Cm clean Remove any files created during the build process. t Cm cleandepend Remove the file
a ${.OBJDIR}/${DEPENDFILE} generated by a prior .Dq Li "make depend" step. t 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
a obj link in
a ${.CURDIR} if that exists.
p 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
a ${.CURDIR} . t Cm depend Generate a list of build dependencies in file
a ${.OBJDIR}/${DEPENDFILE} . t Cm install Install the results of the build to the appropriate location in the installation directory hierarchy specified in variable .Va DESTDIR . t Cm obj Create the canonical object directory associated with the current directory. t Cm objlink Create a symbolic link to the canonical object directory in
a ${.CURDIR} . t 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
p The other supported targets under directory
a /usr/src are: l -tag -width ".Cm distributeworld" t Cm buildenv Spawn an interactive shell with environment variables set up for cross-building the system. The target architecture needs to be specified with .Xr make 1 variables .Va TARGET_ARCH and .Va TARGET .
p This target is only useful after a complete cross-toolchain including the compiler, linker, assembler, headers and libraries has been built; see the .Cm toolchain target below. t Cm buildworld Build everything but the kernel, configure files in
a etc , and
a release . The actual build location prefix used is
a ${MAKEOBJDIRPREFIX}${.CURDIR} for native builds, and
a ${MAKEOBJDIRPREFIX}/${TARGET}${.CURDIR} for cross builds and native builds with variable .Va CROSS_BUILD_TESTING set. t Cm cleanworld Attempt to clean up targets built by a preceding .Cm buildworld step. t 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 . t Cm packageworld Archive the results of .Cm distributeworld , placing the results in .Va DISTDIR . This target is used while building a release; see .Xr release 7 . t Cm installworld Install everything built by a preceding .Cm buildworld step into the directory hierarchy pointed to by .Xr make 1 variable .Va DESTDIR .
p 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. t Cm toolchain Create the build toolchain needed to build the rest of the system. For cross-architecture builds, this step creates a cross-toolchain. t Cm universe For each architecture, execute a .Cm buildworld followed by a .Cm buildkernel for all kernels for that architecture, including
a LINT . This command takes a long time. t Cm update Get updated sources as configured in .Xr make.conf 5 . t Cm targets Print a list of supported .Va TARGET / .Va TARGET_ARCH pairs for world and kernel targets. t 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. t Cm toolchains Create a build toolchain for each architecture supported by the build system. .El
p Kernel specific build targets in
a /usr/src are: l -tag -width ".Cm distributekernel" t Cm buildkernel Rebuild the kernel and the kernel modules. t Cm installkernel Install the kernel and the kernel modules to directory
a ${DESTDIR}/boot/kernel , renaming any pre-existing directory with this name to
a kernel.old if it contained the currently running kernel. The target directory under
a ${DESTDIR} may be modified using the .Va INSTKERNNAME and .Va KODIR .Xr make 1 variables. t Cm distributekernel Install the kernel to the directory
a ${DISTDIR}/kernel/boot/kernel . This target is used while building a release; see .Xr release 7 . t Cm packagekernel Archive the results of .Cm distributekernel , placing the results in .Va DISTDIR . This target is used while building a release; see .Xr release 7 . t Cm kernel Equivalent to .Cm buildkernel followed by .Cm installkernel t Cm kernel-toolchain Rebuild the tools needed for kernel compilation. Use this if you did not do a .Cm buildworld first. t 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
p Convenience targets for cleaning up the install destination directory denoted by variable .Va DESTDIR include: l -tag -width ".Cm delete-old-libs" t Cm check-old Print a list of old files and directories in the system. t 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" . t Cm delete-old-libs Delete obsolete base system libraries interactively. This target should only be used if no 3rd 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: l -tag -width ".Va MAKEOBJDIRPREFIX" t Va DEBUG_FLAGS Defines a set of debugging flags that will be used to build all userland binaries under
a /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. t Va DESTDIR The directory hierarchy prefix where built objects will be installed. If not set, .Va DESTDIR defaults to the empty string. t Va MAKEOBJDIRPREFIX Defines the prefix for directory names in the tree of built objects. Defaults to
a /usr/obj if not defined. This variable should only be set in the environment and not via
a /etc/make.conf or the command line. t Va NO_WERROR If defined, compiler warnings will not cause the build to halt, even if the makefile says otherwise. t Va WITH_CTF If defined, the build process will run the DTrace CTF conversion tools on built objects. .El
p Additionally, builds in
a /usr/src are influenced by the following .Xr make 1 variables: l -tag -width ".Va SUBDIR_OVERRIDE" t Va KERNCONF Overrides which kernel to build and install for the various kernel make targets. It defaults to .Cm GENERIC . t Va KERNFAST If set, the build target .Cm buildkernel defaults to setting .Va NO_KERNELCLEAN , .Va NO_KERNELCONFIG , .Va NO_KERNELDEPEND and .Va NO_KERNELOBJ . When set to a value other than .Cm 1 then .Va KERNCONF is set to the value of .Va KERNFAST . t 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. t Va LOCAL_ITOOLS If set, this variable supplies a list of additional tools that are used by the .Cm installworld and .Cm distributeworld targets. t 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. t 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. t 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. t 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. d -literal -offset indent make PORTS_MODULES=emulators/kqemu-kmod kernel .Ed t 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. t Va 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. d -literal -offset indent make some-target SUBDIR_OVERRIDE=foo/bar .Ed t 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 PC98 machines requires .Va TARGET_ARCH Ns = Ns Li i386 and .Va TARGET Ns = Ns Li pc98 . If not set, .Va TARGET defaults to the current hardware platform. t 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
p Builds under directory
a /usr/src are also influenced by defining one or more of the following symbols, using the .Fl D option of .Xr make 1 : l -tag -width ".Va -DNO_KERNELDEPEND" t 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 . t Va NO_CLEAN If set, no object tree files are cleaned at all. Setting .Va NO_CLEAN implies .Va NO_KERNELCLEAN , so when .Va NO_CLEAN is set no kernel objects are cleaned either. t Va NO_CTF If set, the build process does not run the DTrace CTF conversion tools on built objects. t Va NO_SHARE If set, the build does not descend into the
a /usr/src/share subdirectory (i.e., manpages, locale data files, timezone data files and other
a /usr/src/share files will not be rebuild from their sources). t Va NO_KERNELCLEAN If set, the build process does not run .Dq make clean as part of the .Cm buildkernel target. t Va NO_KERNELCONFIG If set, the build process does not run .Xr config 8 as part of the .Cm buildkernel target. t Va NO_KERNELDEPEND If set, the build process does not run .Dq make depend as part of the .Cm buildkernel target. t Va NO_KERNELOBJ If set, the build process does not run .Dq make obj as part of the .Cm buildkernel target. t Va NO_DOCUPDATE If set, the update process does not update the source of the .Fx documentation as part of the .Dq make update target. t Va NO_PORTSUPDATE If set, the update process does not update the Ports tree as part of the .Dq make update target. t Va NO_WWWUPDATE If set, the update process does not update the www tree as part of the .Dq make update target. .El
p Builds under directory
a /usr/doc are influenced by the following .Xr make 1 variables: l -tag -width ".Va DOC_LANG" t 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
p Builds using the .Cm universe target are influenced by the following .Xr make 1 variables: l -tag -width ".Va MAKE_JUST_KERNELS" t 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. t Va MAKE_JUST_KERNELS Only build kernels for each supported architecture. t Va MAKE_JUST_WORLDS Only build worlds for each supported architecture. t 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. .El .Sh FILES l -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact t Pa /usr/doc/Makefile t Pa /usr/doc/share/mk/doc.project.mk t Pa /usr/ports/Mk/bsd.port.mk t Pa /usr/ports/Mk/bsd.sites.mk t Pa /usr/share/examples/etc/make.conf t Pa /usr/src/Makefile t Pa /usr/src/Makefile.inc1 .El .Sh EXAMPLES For an .Dq approved method of updating your system from the latest sources, please see the .Sx COMMON ITEMS section in
p The following sequence of commands can be used to cross-build the system for the sparc64 architecture on an i386 host: d -literal -offset indent cd /usr/src make TARGET=sparc64 buildworld make TARGET=sparc64 DESTDIR=/clients/sparc64 installworld .Ed .Sh SEE ALSO .Xr cc 1 , .Xr install 1 , .Xr make 1 , .Xr svn 1 , .Xr make.conf 5 , .Xr src.conf 5 , .Xr ports 7 , .Xr release 7 , .Xr config 8 , .Xr mergemaster 8 , .Xr portsnap 8 , .Xr reboot 8 , .Xr shutdown 8 .Sh AUTHORS .An Mike W. Meyer Aq Mt mwm@mired.org