Document the public targets and make variables supported by the

build system.

Reviewed by:	ru (multiple passes)

1 files changed, 267 insertions, 51 deletions

diff --git a/share/man/man7/build.7 b/share/man/man7/build.7
index b1e1f28..1880f63 100644
--- a/share/man/man7/build.7
+++ b/share/man/man7/build.7
@@ -24,32 +24,37 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 3, 2005
+.Dd December 5, 2005
 .Dt BUILD 7
 .Os
 .Sh NAME
 .Nm build
 .Nd information on how to build the system
 .Sh DESCRIPTION
-The source for the
+The sources for the
 .Fx
-system and applications are contained in three different directories,
+system and its applications are contained in three different directories,
 normally
 .Pa /usr/src ,
 .Pa /usr/doc ,
 and
 .Pa /usr/ports .
+Directory
 .Pa /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
 .Pa /usr/doc
 contains the source for the system documentation, excluding the manual
 pages.
+Directory
 .Pa /usr/ports
-is a tree that provides a consistent interface for building and
+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 .
 .Pp
 The
 .Xr make 1
@@ -61,80 +66,274 @@ 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.
-The following
-list provides the names and actions for other targets:
-.Bl -tag -width indent-two
+.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.
+For a given source directory, its canonical object directory
+would be
+.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
+if
+.Xr make 1
+variable
+.Va MAKEOBJDIRPREFIX
+is set, or
+.Pa /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.
+.Pp
+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 .
+.Pp
+The following list provides the names and actions for the targets
+supported by the build system:
+.Bl -tag -width ".Cm cleandepend"
 .It Cm clean
-Removes any files created during the build process.
+Remove any files created during the build process.
+.It Cm cleandepend
+Remove the file
+.Pa ${.OBJDIR}/${DEPENDFILE}
+generated by a prior
+.Dq Li "make depend"
+step.
+.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} .
 .It Cm install
-Installs the results of the build for this directory.
-.It Cm update
-Gets updated sources as configured in
-.Xr make.conf 5 .
+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
+The other supported targets under directory
 .Pa /usr/src
-make targets are:
-.Bl -tag -width indent-two
+are:
+.Bl -tag -width ".Cm distributeworld"
+.It 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 .
+.Pp
+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.
 .It Cm buildworld
-Rebuild everything but the kernel, configure files in
-.Pa /etc ,
-and release.
+Build everything but the kernel, configure files in
+.Pa etc ,
+and
+.Pa release .
+The actual build location prefix used is
+.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
+for native builds, and
+.Pa ${MAKEOBJDIRPREFIX}/${TARGET}${.CURDIR}
+for cross builds and native builds with variable
+.Va CROSS_BUILD_TESTING
+set.
+.It Cm cleanworld
+Attempt to clean up targets built by a preceding
+.Cm buildworld
+step.
+.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 installworld
-Install everything built by
-.Cm buildworld .
-.It Cm kernel-toolchain
-Rebuild the tools needed for kernel compilation.
-Use this if you did not do a buildworld first.
+Install everything built by a preceding
+.Cm buildworld
+step into the directory hierarchy pointed to by
+.Xr make 1
+variable
+.Va DESTDIR .
+.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
+Execute a
+.Cm buildworld
+and
+.Cm buildkernel
+for all kernels including
+.Pa LINT ,
+for each architecture supported by the build system.
+This command takes a long time.
+.It Cm update
+Get updated sources as configured in
+.Xr make.conf 5 .
+.El
+.Pp
+Kernel specific build targets in
+.Pa /usr/src
+are:
+.Bl -tag -width ".Cm reinstallkernel"
 .It Cm buildkernel
 Rebuild the kernel and the kernel modules.
 .It Cm installkernel
-Install the kernel and the kernel modules.
-.It Cm reinstallkernel .
-Reinstall the kernel and the kernel modules.
+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
+and
+.Va KODIR
+.Xr make 1
+variables.
 .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 directores in the system.
 .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.
+is specified at the command line, the delete operation will be
+non-interactive.
 The variables
-.Va DESTDIR , TARGET_ARCH
+.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 should only be used if no 3rd party software uses the libraries anymore.
+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.
+is specified at the command line, the delete operation will be
+non-interactive.
 The variables
-.Va DESTDIR , TARGET_ARCH
+.Va DESTDIR ,
+.Va TARGET_ARCH
 and
 .Va TARGET
 should be set as with
 .Dq Li "make installworld" .
 .El
-.Pp
-For more information about the ports build process, see
-.Xr ports 7 .
 .Sh ENVIRONMENT
-.Bl -tag -width ".Va TARGET_ARCH"
-.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.
+Variables that influence all builds include:
+.Bl -tag -width ".Va MAKEOBJDIRPREFIX"
+.It Va DESTDIR
+The directory hierarchy prefix where built objects will be installed.
+If not set,
+.Va DESTDIR
+defaults to the empty string.
+.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 and not via
+.Pa /etc/make.conf
+or the command line.
+.It Va NO_WERROR
+If defined, compiler warnings will not cause the build to halt,
+even if the makefile says otherwise.
+.El
+.Pp
+Additionally, builds in
+.Pa /usr/src
+are influenced by the following
+.Xr make 1
+variables:
+.Bl -tag -width ".Va SUBDIR_OVERRIDE"
+.It Va LOCAL_DIRS
+If set, this variable supplies a list of additional directories to
+build, relative to the root of the source tree.
+.It 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.
+.Bd -literal -offset indent
+make some-target SUBDIR_OVERRIDE=foo/bar
+.Ed
 .It Va TARGET
 The target hardware platform.
 This is analogous to the
@@ -145,12 +344,30 @@ For example, cross-building for PC98 machines requires
 .Va TARGET_ARCH Ns = Ns Li i386
 and
 .Va TARGET Ns = Ns Li pc98 .
-.It Va NO_WERROR
-If defined, warnings will not cause the build to halt, even if the
-makefile says otherwise.
-.It Va DESTDIR
-The directory hierarchy where the resulting binaries will be
-installed.
+If not set,
+.Va TARGET
+defaults to the current hardware platform.
+.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.
+.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
 .Sh FILES
 .Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
@@ -165,8 +382,7 @@ installed.
 .Sh EXAMPLES
 For an
 .Dq approved
-method of updating your system from the latest sources,
-please see the
+method of updating your system from the latest sources, please see the
 .Sx COMMON ITEMS
 section in
 .Pa src/UPDATING .