BUILD(7)					       BSD Miscellaneous Information Manual						  BUILD(7)

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 consis-
     tent 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 speci-
     fied 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:

     clean	  Remove any files created during the build process.

     cleandepend  Remove the file ${.OBJDIR}/${DEPENDFILE} generated by a prior ``make depend'' step.

     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}.

     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}.

     tags	  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 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:

     buildkernel       Rebuild the kernel and the kernel modules.

     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 modi-
		       fied 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 by installkernel

     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 3rd 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 and installworld 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, 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

     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 or installworld 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.  This variable is use-
		      ful 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.  Setting NO_CLEAN implies NO_KERNELCLEAN, so when NO_CLEAN is set no ker-
			nel 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., manpages, 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_KERNELDEPEND	If set, the build process does not run ``make depend'' 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), config(8), mergemaster(8), portsnap(8), reboot(8),
     shutdown(8)

AUTHORS

     Mike W. Meyer <mwm@mired.org>

BSD
								 December 31, 2014							       BSD