xref: /src/BUILDING

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 TOOLCHAIN_MISSING 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

     doc/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.
                Few files will be installed to /dev, /etc, /root or /var in
                order to prevent user supplied configuration data from being
                overwritten.

     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 dest   Set the value of DESTDIR to dest.

     -d        Build a full distribution.  This differs from a default build
               in that files will also be installed to /dev, /etc, /root and
               /var.  Note this does not build a ``release''; no release sets
               are placed in ${RELEASEDIR}.  -d is implied by -R.

     -E        Set `expert' mode; DESTDIR does not have to be set to a non-
               root path for builds when this is set.

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

     -k kernel
               Build a new kernel.  The kernel argument is the name of a con-
               figuration file suitable for use by config(8).  If kernel does
               not contain any `/' characters, the configuration file is ex-
               pected to be found in the KERNCONFDIR directory, which is typi-
               cally sys/arch/MACHINE/conf.  The new kernel will be built in a
               subdirectory of KERNOBJDIR, which is typically
               sys/arch/MACHINE/compile or an associated object directory.  In
               order to ensure that the kernel is built using up-to-date
               tools, it is strongly recommended that the tools be rebuilt
               (using the -t option) in a separate invocation of build.sh pri-
               or to using the -k option, or that the -t and -k options be
               used together in a single invocation of build.sh.

     -M obj    Set MAKEOBJDIRPREFIX to obj.

     -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 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 under
               /usr/obj/bin, /usr/obj/lib, and so forth.

     -o        Set the value of MKOBJDIRS to ``no''.

     -R rel    Set the value of RELEASEDIR to rel.  Setting this option will
               cause build.sh to run ``make release'' instead of ``make
               build''.

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

     -t        Build and install the host tools from src/tools only.  This op-
               tion implies -b.

     -U        Set the UNPRIVED variable.

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

   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.

EXAMPLES
     ./build.sh -t
               Build a new toolchain.

     cd ${KERNCONFDIR} ; ${TOOLDIR}/bin/nbconfig GENERIC
               Use the new version of config(8) to prepare to build a new
               GENERIC kernel.

     cd ${KERNOBJDIR}/GENERIC ; ${TOOLDIR}/bin/nbmake-${MACHINE} dependall
               Use the new toolchain to build a new GENERIC kernel.

     ./build.sh -t -k GENERIC
               Build a new toolchain, and use the new toolchain to configure
               and build a new GENERIC kernel.

     ./build.sh -U -d
               Using unprivileged mode, build a complete distribution in
               DESTDIR.

     ./build.sh -U -R /some/dir/RELEASE
               Using unprivileged mode, build a complete release in the speci-
               fied release directory.

OBSOLETE VARIABLES
     NBUILDJOBS  Use the make(1) option -j, instead.

     USE_NEW_TOOLCHAIN
                 The new toolchain is now the default.  To disable, use
                 TOOLCHAIN_MISSING=yes.

SEE ALSO
     make(1), hier(7), release(7)

HISTORY
     The build.sh based build scheme was introduced for NetBSD 1.6 as
     USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.

BUGS
     A few platforms are not yet using this build system.

NetBSD                         December 8, 2002                              9