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 of 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 DESTDIR/etc on the desti-
                    nation 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 or
                       via the -M flag of build.sh.

     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 or via the -M flag of
                       build.sh.

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

                 Note: build.sh will provide a default of destdir.MACHINE (in
                 the top-level .OBJDIR) unless run in `expert' mode

     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 DESTDIR/usr/share/doc will be in-
                 stalled 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
                 DESTDIR/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 DESTDIR/usr/share will be built and in-
                 stalled during a build.  If set to ``no'', then all of
                 MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to
                 ``no'' unconditionally.

                 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.

     INSTALLWORLDDIR  Location for the ``make installworld'' target to install
                      to.

                      Default: ``/''

     MKOBJDIRS        Can be set to ``yes'' or ``no''.  Indicates whether ob-
                      ject directories will be created automatically (via a
                      ``make obj'' pass) at the start of a build.

                      Default: ``no''

     NBUILDJOBS       Now obsolete.  Use the make(1) option -j, instead (see
                      below)

                      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 be-
                      cause the system include files have changed.  However,
                      this option 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)
                      layout will be written at the end of a ``make release''.

                      Default: Unset.

                      Note: build.sh will provide a default of releasedir (in
                      the top-level .OBJDIR) unless run in `expert' mode

     UPDATE           If set, then in addition to the effects described for
                      UPDATE above, this implies the effects of NOCLEANDIR
                      (i.e., ``make cleandir'' is avoided).

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 DESTDIR/dev, DESTDIR/etc,
                DESTDIR/root or DESTDIR/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 proper order.

     distribution  Do a ``make build'', and then install a full distribution
                   into DESTDIR, including files in DESTDIR/dev, DESTDIR/etc,
                   DESTDIR/root and DESTDIR/var.

     buildworld    As per ``make distribution'', except that it ensures that
                   DESTDIR is not the root directory.

     installworld  Install the distribution from DESTDIR to INSTALLWORLDDIR
                   (which defaults to the root directory).  Ensures that
                   INSTALLWORLDDIR is the not root directory if cross compil-
                   ing.

                   Note: It is highly recommended that you upgrade your kernel
                   and reboot before performing this operation.

     sets          Create distribution sets from DESTDIR into
                   RELEASEDIR/MACHINE/binary/sets.  Should be run after ``make
                   distribution'' (as ``make build'' does not install all of
                   the required files).

     sourcesets    Create source sets of the source tree into
                   RELEASEDIR/source/sets.

     release       Do a ``make distribution'', build kernels, distribution me-
                   dia, and install sets (this as per ``make sets''), and then
                   package the system into a standard release layout as de-
                   scribed by release(7).  This requires that RELEASEDIR be
                   set (see above).

     regression-tests
                   Can only be run after building the regression tests in the
                   directory ``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 operations are supported by build.sh:

     build         Build the system as per ``make build''.  This option im-
                   plies the obj and tools operations.

     distribution  Build a full distribution as per ``make distribution''.
                   This option implies the build operation.

     release       Build a full release as per ``make release''.  This option
                   implies the distribution operation.

     makewrapper   Create the nbmake-MACHINE wrapper.  This operation is auto-
                   matically performed for any of the other operations.

     obj           Perform ``make obj''.

     tools         Build and install the host tools from src/tools.

     install=idir  Install the contents of DESTDIR to idir, using ``make
                   installworld''.

     kernel=kconf  Build a new kernel.  The kconf argument is the name of a
                   configuration file suitable for use by config(8).  If kconf
                   does not contain any `/' characters, the configuration file
                   is expected to be found in the KERNCONFDIR directory, which
                   is typically 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 tools operation).

     releasekernel=kconf
                   Install a gzip(1)ed copy of the kernel built by
                   kernel=kconf into RELEASEDIR/MACHINE/binary/kernel, usually
                   as netbsd-kconf.gz, although the ``netbsd'' prefix is de-
                   termined from the ``config'' directives in kconf.

     sets          Perform ``make sets''.

     sourcesets    Perform ``make sourcesets''.

     The following command line options alter the behaviour of the above oper-
     ations: The following command line options alter the behaviour of the
     build.sh operations described above:

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

     -D dest   Set the value of DESTDIR to dest.

     -E        Set `expert' mode.  This overrides various sanity checks, and
               allows: DESTDIR does not have to be set to a non-root path for
               builds, and UNPRIVED does not have to be set when building as a
               non-root user.

               Note: It is highly recommended that you know what you are doing
               when you use this option.

     -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 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, or mach is a special
               case listed below.  All cross builds require -m, but if unset
               on a NetBSD host, the host's value of MACHINE will be detected
               and used automatically.

               Some machines support multiple values for MACHINE_ARCH.  For a
               given value of mach, the following MACHINE and MACHINE_ARCH
               values will result:

                     mach          MACHINE    MACHINE_ARCH
                     evbmips       evbmips    (not set)
                     evbmips-eb    evbmips    mipseb
                     evbmips-el    evbmips    mipsel
                     evbsh3        evbsh3     (not set)
                     evbsh3-eb     evbsh3     sh3eb
                     evbsh3-el     evbsh3     sh3el
                     sbmips        sbmips     (not set)
                     sbmips-eb     sbmips     mipseb
                     sbmips-el     sbmips     mipsel

     -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''.  Otherwise, it will be
               automatically set to ``yes'' (which is opposite to the default
               behaviour).

     -R rel    Set the value of RELEASEDIR to rel.

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

     -U        Set the UNPRIVED variable.

     -u        Set the UPDATE variable.

     -V var=[value]
               Set the variable var to value (which is optional).

     -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
     1.   ./build.sh tools kernel=GENERIC

          Build a new toolchain, and use the new toolchain to configure and
          build a new GENERIC kernel.

     2.   ./build.sh -U distribution

          Using unprivileged mode, build a complete distribution to a DESTDIR
          directory that build.sh selects (and will display).

     3.   # ./build.sh -U install=/

          As root, install to / the distribution that was built by example 2.
          Even though this is run as root, -U is required so that the permis-
          sions stored in DESTDIR/METALOG are correctly applied to the files
          as they're copied to /.

     4.   ./build.sh -U -u release

          Using unprivileged mode, build a complete release to DESTDIR and
          RELEASEDIR directories that build.sh selects (and will display).
          UPDATE (-u) is set to prevent the ``make cleandir'', so that if this
          is run after example 2, it doesn't need to redo that portion of the
          release build.

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                           July 3, 2003                           NetBSD