Document the public targets and make variables supported by the
build system. Reviewed by: ru (multiple passes)
This commit is contained in:
Joseph Koshy
parent
8c7a62275a
commit
7b710ab25b
@ -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.
|
||||
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
|
||||
Gets updated sources as configured in
|
||||
Get updated sources as configured in
|
||||
.Xr make.conf 5 .
|
||||
.El
|
||||
.Pp
|
||||
The other
|
||||
Kernel specific build targets in
|
||||
.Pa /usr/src
|
||||
make targets are:
|
||||
.Bl -tag -width indent-two
|
||||
.It Cm buildworld
|
||||
Rebuild everything but the kernel, configure files in
|
||||
.Pa /etc ,
|
||||
and release.
|
||||
.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.
|
||||
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 .
|
||||
|
||||
Loading…
Reference in New Issue
Block a user