522 lines
24 KiB
Plaintext
522 lines
24 KiB
Plaintext
BUILDING(8) NetBSD System Manager's Manual BUILDING(8)
|
|
|
|
NAME
|
|
BUILDING - Procedure for building NetBSD from source code.
|
|
|
|
STATUS
|
|
This document is a work-in-progress. As such, the information described
|
|
here may not match the reality of the build system as of this writing.
|
|
Once this document is completely in sync with reality, this paragraph
|
|
will be removed.
|
|
|
|
Discrepancies between this documentation and the current reality of im-
|
|
plementation are noted specially, as with the note below:
|
|
|
|
Note: This document applies only to platforms which use the new toolchain
|
|
as indicated by the default setting of USE_NEW_TOOLCHAIN in <bsd.own.mk>.
|
|
Platforms which have not yet been switched to the new toolchain should
|
|
continue building traditionally, using the notes specified in the file
|
|
UPDATING.
|
|
|
|
REQUIREMENTS
|
|
NetBSD is designed to be buildable on most POSIX-compliant host systems.
|
|
The basic build procedure is the same whether compiling natively (on the
|
|
same NetBSD architecture) or cross compiling (on another architecture or
|
|
OS).
|
|
|
|
This source tree contains a special subtree, ``tools'', which uses the
|
|
host system to create a build toolchain for the target architecture. The
|
|
host system must have at least C and C++ compilers in order to create the
|
|
toolchain (make is not required); all other tools are created as part of
|
|
the NetBSD build process.
|
|
|
|
Note: A couple host toolchain components are not yet available in
|
|
the tools directory. Also, some tools use non-POSIX, non-ANSI C
|
|
extensions and need to be standardized. As a result, cross-compil-
|
|
ing from systems other than NetBSD is not currently supported.
|
|
|
|
FILES
|
|
Source tree layout
|
|
|
|
BUILDING.mdoc This document (in -mdoc troff format; the original copy).
|
|
|
|
BUILDING This document (in plaintext).
|
|
|
|
Makefile The main Makefile for NetBSD; should only be run for na-
|
|
tive builds with an appropriately up-to-date version of
|
|
NetBSD make(1). (For building from out-of-date systems or
|
|
on a non-native host, see the build.sh shell script.)
|
|
|
|
UPDATING Special notes for updating from an earlier revision of
|
|
NetBSD. It is important to read this file before every
|
|
build of an updated source tree.
|
|
|
|
build.sh Bourne-compatible shell script used for building the host
|
|
build tools and the NetBSD system from scratch. Can be
|
|
used for both native and cross builds, and should be used
|
|
instead of make(1) for any source tree that is updated and
|
|
recompiled regularly.
|
|
|
|
crypto/dist/, dist/, gnu/dist/
|
|
Sources imported verbatim from third parties, without man-
|
|
gling the existing build structure. Other source trees in
|
|
bin through usr.sbin use the NetBSD make(1) ``reachover''
|
|
Makefile semantics when building these programs for a na-
|
|
tive host.
|
|
|
|
distrib/, etc/
|
|
Sources for items used when making a full release snap-
|
|
shot, such as files installed in /etc on the destination
|
|
system, boot media, and release notes.
|
|
|
|
regress/ Regression test harness. Can be cross-compiled, but only
|
|
run natively.
|
|
|
|
sys/ NetBSD kernel sources.
|
|
|
|
tools/ ``Reachover'' build structure for the host build tools.
|
|
This has a special method of determining out-of-date sta-
|
|
tus.
|
|
|
|
bin/ ... usr.sbin/
|
|
Sources to the NetBSD userland (non-kernel) programs. If
|
|
any of these directories are missing, they will be skipped
|
|
during the build.
|
|
|
|
Build tree layout
|
|
The NetBSD build tree is described in hier(7), and the release layout is
|
|
described in release(7).
|
|
|
|
CONFIGURATION
|
|
Environment variables
|
|
Several environment variables control the behaviour of NetBSD builds.
|
|
|
|
MACHINE Machine type.
|
|
|
|
MACHINE_ARCH Machine architecture.
|
|
|
|
MAKE Path name to invoke make(1) as.
|
|
|
|
MAKEFLAGS Flags to invoke make(1) with.
|
|
|
|
MAKEOBJDIR Directory to use as the .OBJDIR for the current direc-
|
|
tory. Used only if MAKEOBJDIRPREFIX is not defined.
|
|
MAKEOBJDIR can only be provided in the environment.
|
|
|
|
MAKEOBJDIRPREFIX Top level directory of the object directory tree. If
|
|
this is defined, ${MAKEOBJDIRPREFIX}/${.CURDIR} is used
|
|
as the .OBJDIR for the current directory. The current
|
|
directory may be read only. MAKEOBJDIRPREFIX can only
|
|
be provided in the environment.
|
|
|
|
"make" variables
|
|
Several variables control the behavior of NetBSD builds. Unless other-
|
|
wise specified, these variables may be set in either the process environ-
|
|
ment or the make(1) configuration file specified by MAKECONF.
|
|
|
|
BUILDID Identifier for the build. The identifier will be appended to
|
|
object directory names, and can be consulted in the make(1)
|
|
configuration file in order to set additional build parame-
|
|
ters, such as compiler flags.
|
|
|
|
DESTDIR Directory to contain the built NetBSD system. If set, spe-
|
|
cial options are passed to the compilation tools to prevent
|
|
their default use of the host system's /usr/include,
|
|
/usr/lib, and so forth. This pathname should not end with a
|
|
slash (/) character (for installation into the system's root
|
|
directory, set DESTDIR to an empty string). The directory
|
|
must reside on a file system which supports long file names
|
|
and hard links.
|
|
|
|
Default: Empty string if USETOOLS is ``yes''; unset other-
|
|
wise.
|
|
|
|
MAKECONF The name of the make(1) configuration file. Only settable in
|
|
the process environment.
|
|
|
|
Default: ``/etc/mk.conf''
|
|
|
|
MKCATPAGES Can be set to ``yes'' or ``no''. Indicates whether prefor-
|
|
matted plaintext manual pages will be created during a build.
|
|
|
|
Default: ``yes''
|
|
|
|
MKCRYPTO Can be set to ``yes'' or ``no''. Indicates whether crypto-
|
|
graphic code will be included in a build; provided for the
|
|
benefit of countries that do not allow strong cryptography.
|
|
Will not affect use of the standard low-security password en-
|
|
cryption system, crypt(3).
|
|
|
|
Default: ``yes''
|
|
|
|
MKDOC Can be set to ``yes'' or ``no''. Indicates whether system
|
|
documentation destined for /usr/share/doc will be installed
|
|
during a build.
|
|
|
|
Default: ``yes''
|
|
|
|
MKHOSTOBJ Can be set to ``yes'' or ``no''. If set to ``yes'', then for
|
|
programs intended to be run on the compile host, the name,
|
|
release, and architecture of the host operating system will
|
|
be suffixed to the name of the object directory created by
|
|
``make obj''. (This allows multiple host systems to compile
|
|
NetBSD for a single target.) If set to ``no'', then programs
|
|
built to be run on the compile host will use the same object
|
|
directory names as programs built to be run on the target.
|
|
|
|
Default: ``no''
|
|
|
|
MKINFO Can be set to ``yes'' or ``no''. Indicates whether GNU Info
|
|
files, used for the documentation for most of the compilation
|
|
tools, will be created and installed during a build.
|
|
|
|
Default: ``yes''
|
|
|
|
MKLINT Can be set to ``yes'' or ``no''. Indicates whether lint(1)
|
|
will be run against portions of the NetBSD source code during
|
|
the build, and whether lint libraries will be installed into
|
|
/usr/libdata/lint.
|
|
|
|
Default: ``yes''
|
|
|
|
MKMAN Can be set to ``yes'' or ``no''. Indicates whether manual
|
|
pages will be installed during a build.
|
|
|
|
Default: ``yes''
|
|
|
|
MKNLS Can be set to ``yes'' or ``no''. Indicates whether Native
|
|
Language System locale zone files will be compiled and in-
|
|
stalled during a build.
|
|
|
|
Default: ``yes''
|
|
|
|
MKOBJ Can be set to ``yes'' or ``no''. Indicates whether object
|
|
directories will be created when running ``make obj''. If
|
|
set to ``no'', then all built files will be located inside
|
|
the regular source tree.
|
|
|
|
Default: ``yes''
|
|
|
|
MKPIC Can be set to ``yes'' or ``no''. Indicates whether shared
|
|
objects and libraries will be created and installed during a
|
|
build. If set to ``no'', the entire built system will be
|
|
statically linked.
|
|
|
|
Default: Platform dependent. As of this writing, all plat-
|
|
forms except sh3 default to ``yes''.
|
|
|
|
MKPICINSTALL
|
|
Can be set to ``yes'' or ``no''. Indicates whether the ar(1)
|
|
format libraries (lib*_pic.a), used to generate shared li-
|
|
braries, are installed during a build.
|
|
|
|
Default: ``yes''
|
|
|
|
MKPROFILE Can be set to ``yes'' or ``no''. Indicates whether profiled
|
|
libraries (lib*_p.a) will be built and installed during a
|
|
build.
|
|
|
|
Default: ``yes''; however, some platforms turn off MKPROFILE
|
|
by default at times due to toolchain problems with profiled
|
|
code.
|
|
|
|
MKSHARE Can be set to ``yes'' or ``no''. Indicates whether files
|
|
destined to reside in /usr/share will be built and installed
|
|
during a build. If set to ``no'', then all of MKCATPAGES,
|
|
MKDOC, MKINFO, MKMAN, and MKNLS will be set to ``no'' uncon-
|
|
ditionally.
|
|
|
|
Default: ``yes''
|
|
|
|
TOOLDIR Directory to hold the host tools, once built. This directory
|
|
should be unique to a given host system and NetBSD source
|
|
tree. (However, multiple targets may share the same TOOLDIR;
|
|
the target-dependent files have unique names.) If unset, a
|
|
default based on the uname(1) information of the host plat-
|
|
form will be created in the .OBJDIR of src/tools.
|
|
|
|
Default: Unset.
|
|
|
|
UNPRIVED If set, then an unprivileged install will occur. The user,
|
|
group, permissions, and file flags, will not be set on the
|
|
installed item; instead the information will be appended to a
|
|
file called METALOG in DESTDIR. The contents of METALOG is
|
|
used during the generation of the distribution tar files to
|
|
ensure that the appropriate file ownership is stored.
|
|
|
|
Default: Unset.
|
|
|
|
UPDATE If set, then all install operations intended to write to
|
|
DESTDIR will compare file timestamps before installing, and
|
|
skip the install phase if the destination files are up-to-
|
|
date. This also has implications on full builds (see next
|
|
subsection).
|
|
|
|
Default: Unset.
|
|
|
|
USETOOLS Indicates whether the tools specified by TOOLDIR should be
|
|
used as part of a build in progress. Must be set to ``yes''
|
|
if cross-compiling.
|
|
|
|
yes Use the tools from TOOLDIR.
|
|
|
|
no Do not use the tools from TOOLDIR, but refuse to build
|
|
native compilation tool components that are version-
|
|
specific for that tool.
|
|
|
|
never Do not use the tools from TOOLDIR, even when building
|
|
native tool components. This is similar to the tradi-
|
|
tional NetBSD build method, but does not verify that
|
|
the compilation tools in use are up-to-date enough in
|
|
order to build the tree successfully. This may cause
|
|
build or runtime problems when building the whole
|
|
NetBSD source tree.
|
|
|
|
Default: ``yes'' if building all or part of a whole NetBSD
|
|
source tree (detected automatically); ``no'' otherwise (to
|
|
preserve traditional semantics of the <bsd.*.mk> make(1) in-
|
|
clude files).
|
|
|
|
"make" variables for full builds
|
|
These variables only affect the top level ``Makefile'' and do not affect
|
|
manually building subtrees of the NetBSD source code.
|
|
|
|
MKOBJDIRS Can be set to ``yes'' or ``no''. Indicates whether object
|
|
directories will be created automatically (via a ``make
|
|
obj'' pass) at the start of a build.
|
|
|
|
Default: ``yes''
|
|
|
|
NBUILDJOBS Now obsolete. Use the make(1) option -j, instead (see be-
|
|
low)
|
|
|
|
Default: Unset.
|
|
|
|
NOCLEANDIR If set, avoids the ``make cleandir'' phase of a full
|
|
build. This has the effect of allowing only changed files
|
|
in a source tree to be recompiled. This can speed up
|
|
builds when updating only a few files in the tree.
|
|
|
|
Default: Unset.
|
|
|
|
NODISTRIBDIRS If set, avoids the ``make distrib-dirs'' phase of a full
|
|
build. This skips running mtree(8) on DESTDIR, useful on
|
|
systems where building as an unprivileged user, or where
|
|
it is known that the system-wide mtree files have not
|
|
changed.
|
|
|
|
Default: Unset.
|
|
|
|
NOINCLUDES If set, avoids the ``make includes'' phase of a full
|
|
build. This has the effect of preventing make(1) from
|
|
thinking that some programs are out-of-date simply because
|
|
the system include files have changed. However, this op-
|
|
tion should not be used when updating the entire NetBSD
|
|
source tree arbitrarily; it is suggested to use UPDATE in
|
|
that case.
|
|
|
|
Default: Unset.
|
|
|
|
RELEASEDIR If set, specifies the directory to which a release(7) lay-
|
|
out will be written at the end of a ``make release''.
|
|
|
|
Default: Unset.
|
|
|
|
UPDATE If set, then in addition to the effects described for UP-
|
|
DATE above, this implies the effects of NOCLEANDIR.
|
|
|
|
BUILDING
|
|
"make" command line options
|
|
This is only a summary of options available to make(1); only the options
|
|
used most frequently with NetBSD builds are listed here.
|
|
|
|
-j njob Run up to njob make(1) subjobs in parallel. Makefiles should
|
|
use .WAIT or have explicit dependancies as necessary to en-
|
|
force build ordering. If you see build failures with -j,
|
|
please save complete build logs so the failures can be ana-
|
|
lyzed.
|
|
|
|
-m dir Specify the default directory for searching for system Make-
|
|
file segments, mainly the <bsd.*.mk> files. When building any
|
|
full NetBSD source tree, this should be set to the
|
|
``share/mk'' directory in the source tree. (This is set auto-
|
|
matically when building from the top level.)
|
|
|
|
-n Display the commands that would have been executed, but do not
|
|
actually execute them. This will still cause recursion to
|
|
take place.
|
|
|
|
-v var Print make(1)'s idea of the value of var. Does not build any
|
|
targets.
|
|
|
|
var=value Set the variable var to value, overriding any setting speci-
|
|
fied by the process environment, the MAKECONF configuration
|
|
file, or the system Makefile segments.
|
|
|
|
"make" targets
|
|
These default targets may be built by running make(1) in any subtree of
|
|
the NetBSD source code. It is recommended that none of these be used
|
|
from the top level Makefile; as a specific exception, ``make obj'' and
|
|
``make cleandir'' are useful in that context.
|
|
|
|
all Build programs, libraries, and preformatted documentation.
|
|
|
|
clean Remove program and library object code files.
|
|
|
|
cleandir Same as clean, but also remove preformatted documentation, de-
|
|
pendency files generated by ``make depend'', and any other
|
|
files known to be created at build time. ``make distclean''
|
|
may be used as a synonym, for familiarity with a similar well-
|
|
known convention.
|
|
|
|
depend Create dependency files (.depend) containing more detailed in-
|
|
formation about the dependencies of source code on header
|
|
files. Allows programs to be recompiled automatically when a
|
|
dependency changes.
|
|
|
|
dependall Does a ``make depend'' immediately followed by a ``make all''.
|
|
This improves cache locality of the build since both passes
|
|
read the source files in their entirety.
|
|
|
|
includes Build and install system header files. Typically needed be-
|
|
fore any system libraries or programs can be built.
|
|
|
|
install Install programs, libraries, and documentation into DESTDIR.
|
|
|
|
lint Run lint(1) against the C source code, where appropriate, and
|
|
generate system-installed lint libraries.
|
|
|
|
obj Create object directories to be used for built files, instead
|
|
of building directly in the source tree.
|
|
|
|
tags Create ctags(1) searchable function lists usable by the ex(1)
|
|
and vi(1) text editors.
|
|
|
|
"make" targets for the top level
|
|
Additional make(1) targets are usable specifically from the top source
|
|
level to facilitate building the entire NetBSD source tree.
|
|
|
|
build Build the entire NetBSD system. This orders portions of the
|
|
source tree such that prerequisites will be built in the prop-
|
|
er order.
|
|
|
|
release Do a ``make build'', then package the system into a standard
|
|
release layout as described by release(7). This requires that
|
|
RELEASEDIR be set (see above).
|
|
|
|
regression-tests
|
|
Can only be run after building the regression tests in the di-
|
|
rectory ``regress''. Runs the compiled regression tests on
|
|
the local host.
|
|
|
|
The "build.sh" script
|
|
This script file is a Bourne shell script designed to build the entire
|
|
NetBSD system on any host with a Bourne shell in /bin/sh, including many
|
|
that are not POSIX compliant. Note that if a host system's /bin/sh is
|
|
unusually old and broken, the Korn Shell (/bin/ksh), if available, may be
|
|
a usable alternative.
|
|
|
|
All cross-compile builds, and most native builds, of the entire system
|
|
should make use of build.sh rather than just running ``make''. This way,
|
|
the make(1) program will be bootstrapped properly, in case the host sys-
|
|
tem has an older or incompatible ``make'' program.
|
|
|
|
When compiling the entire system via build.sh, many make(1) variables are
|
|
set for you in order to help encapsulate the build process. In the list
|
|
of options below, variables that are automatically set by build.sh are
|
|
noted where applicable.
|
|
|
|
The following are available command line options that may be supplied to
|
|
build.sh:
|
|
|
|
-a arch Set the value of MACHINE_ARCH to arch.
|
|
|
|
-B buildid
|
|
Set the value of BUILDID to buildid. This will also append the
|
|
build idenfitier to the name of the ``make'' wrapper script so
|
|
that the resulting name is of the form ``nbmake-MACHINE-
|
|
BUILDID''.
|
|
|
|
-b Bootstrap ``make'' and create a nbmake-MACHINE script (see be-
|
|
low).
|
|
|
|
-d Build a full distribution. This differs from a normal build in
|
|
that etc files will also be installed. Note this does not
|
|
build a ``release''; no release sets are placed in ${RE-
|
|
LEASEDIR}.
|
|
|
|
-j njob Passed through to make(1). Makefiles should use .WAIT or have
|
|
explicit dependancies as necessary to enforce build ordering.
|
|
If you see build failures with -j, please save complete build
|
|
logs so the failures can be analyzed.
|
|
|
|
-m mach Set the value of MACHINE to mach. This will also override any
|
|
value of MACHINE_ARCH in the process environment with a value
|
|
deduced from mach, unless -a is specified. All cross builds
|
|
require -m, but if unset on a NetBSD host, the host's value of
|
|
MACHINE will be detected and used automatically.
|
|
|
|
-n Show the commands that would be executed by build.sh, but do
|
|
not make any changes. This is similar in concept to ``make
|
|
-n''.
|
|
|
|
-o Set the value of MKOBJDIRS to ``no''.
|
|
|
|
-r Remove the contents of DESTDIR and TOOLDIR before building
|
|
(provides a clean starting point). This will skip deleting
|
|
DESTDIR if building on a native system to the root directory.
|
|
|
|
-t Build and install the host tools from src/tools only. This op-
|
|
tion implies -b.
|
|
|
|
-u Set the UPDATE variable.
|
|
|
|
-w wrapper
|
|
Create the nbmake wrapper script (see below) in a custom loca-
|
|
tion, specified by wrapper. This allows, for instance, to
|
|
place the wrapper in PATH automatically. Note that wrapper is
|
|
the full name of the file, not just a directory name.
|
|
|
|
-D dest Set the value of DESTDIR to dest.
|
|
|
|
-O obj Create an appropriate transform macro for MAKEOBJDIR that will
|
|
place the built object files under obj. For instance, a set-
|
|
ting of /usr/obj will place build-time files files under
|
|
/usr/obj/bin, /usr/obj/lib, and so forth.
|
|
|
|
-R rel Set the value of RELEASEDIR to rel. Setting this option will
|
|
cause build.sh to run ``make release'' instead of ``make
|
|
build''.
|
|
|
|
-T tools Set the value of TOOLDIR to tools. If set, the bootstrap
|
|
``make'' will only be rebuilt as needed (when the source files
|
|
for make(1) change).
|
|
|
|
-U Set the UNPRIVED variable.
|
|
|
|
The "nbmake-MACHINE" wrapper script
|
|
If using the build.sh script to build NetBSD, a nbmake-MACHINE script
|
|
will be created in TOOLDIR/bin upon the first build to assist in building
|
|
subtrees on a cross-compile host.
|
|
|
|
nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
|
|
the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with sev-
|
|
eral key variables pre-set, including MACHINE, MACHINE_ARCH, and TOOLDIR.
|
|
This script can be symlinked into a directory listed in PATH, or called
|
|
with an absolute path.
|
|
|
|
OBSOLETE VARIABLES
|
|
NBUILDJOBS Now obsolete. Use the make(1) option -j, instead.
|
|
|
|
SEE ALSO
|
|
make(1), hier(7), release(7)
|
|
|
|
HISTORY
|
|
The USE_NEW_TOOLCHAIN based build scheme was introduced in the ``NetBSD-
|
|
current'' development sources between NetBSD 1.5 and NetBSD 1.6.
|
|
|
|
BUGS
|
|
A few platforms are not yet using the USE_NEW_TOOLCHAIN system.
|
|
|
|
NetBSD May 3, 2002 8
|