.\" Copyright (c) 2000
.\"	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$
.\"
.Dd December 5, 2005
.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
.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
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
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.
.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
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
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 supported targets under directory
.Pa /usr/src
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
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 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 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.
The variables
.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 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:
.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
.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.
.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
.It Pa /usr/doc/Makefile
.It Pa /usr/doc/share/mk/doc.project.mk
.It Pa /usr/ports/Mk/bsd.port.mk
.It Pa /usr/ports/Mk/bsd.sites.mk
.It Pa /usr/share/examples/etc/make.conf
.It Pa /usr/src/Makefile
.It 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
.Pa src/UPDATING .
.Pp
The following sequence of commands can be used to cross-build the
system for the Alpha architecture on an i386 host:
.Bd -literal -offset indent
cd /usr/src
make TARGET_ARCH=alpha buildworld
make TARGET_ARCH=alpha DESTDIR=/clients/axp installworld
.Ed
.Sh SEE ALSO
.Xr cc 1 ,
.Xr install 1 ,
.Xr make 1 ,
.Xr make.conf 5 ,
.Xr ports 7 ,
.Xr release 7 ,
.Xr config 8 ,
.Xr mergemaster 8 ,
.Xr reboot 8 ,
.Xr shutdown 8
.Sh AUTHORS
.An Mike W. Meyer Aq mwm@mired.org .