Home | History | Annotate | Line # | Download | only in src
BUILDING revision 1.41
      1 BUILDING(8)             NetBSD System Manager's Manual             BUILDING(8)
      2 
      3 NAME
      4      BUILDING - Procedure for building NetBSD from source code.
      5 
      6 STATUS
      7      This document is a work-in-progress.  As such, the information described
      8      here may not match the reality of the build system as of this writing.
      9      Once this document is completely in sync with reality, this paragraph
     10      will be removed.
     11 
     12      Discrepancies between this documentation and the current reality of im-
     13      plementation are noted specially, as with the note below:
     14 
     15      Note: This document applies only to platforms which use the new toolchain
     16      as indicated by the default setting of TOOLCHAIN_MISSING in <bsd.own.mk>.
     17      Platforms which have not yet been switched to the new toolchain should
     18      continue building traditionally, using the notes specified in the file
     19      UPDATING.
     20 
     21 REQUIREMENTS
     22      NetBSD is designed to be buildable on most POSIX-compliant host systems.
     23      The basic build procedure is the same whether compiling natively (on the
     24      same NetBSD architecture) or cross compiling (on another architecture or
     25      OS).
     26 
     27      This source tree contains a special subtree, ``tools'', which uses the
     28      host system to create a build toolchain for the target architecture.  The
     29      host system must have at least C and C++ compilers in order to create the
     30      toolchain (make is not required); all other tools are created as part of
     31      the NetBSD build process.
     32 
     33            Note: A couple of host toolchain components are not yet available
     34            in the tools directory.  Also, some tools use non-POSIX, non-ANSI C
     35            extensions and need to be standardized.  As a result, cross-compil-
     36            ing from systems other than NetBSD is not currently supported.
     37 
     38 FILES
     39    Source tree layout
     40      doc/BUILDING.mdoc
     41                     This document (in -mdoc troff format; the original copy).
     42 
     43      BUILDING       This document (in plaintext).
     44 
     45      Makefile       The main Makefile for NetBSD; should only be run for na-
     46                     tive builds with an appropriately up-to-date version of
     47                     NetBSD make(1).  (For building from out-of-date systems or
     48                     on a non-native host, see the build.sh shell script.)
     49 
     50      UPDATING       Special notes for updating from an earlier revision of
     51                     NetBSD.  It is important to read this file before every
     52                     build of an updated source tree.
     53 
     54      build.sh       Bourne-compatible shell script used for building the host
     55                     build tools and the NetBSD system from scratch.  Can be
     56                     used for both native and cross builds, and should be used
     57                     instead of make(1) for any source tree that is updated and
     58                     recompiled regularly.
     59 
     60      crypto/dist/, dist/, gnu/dist/
     61                     Sources imported verbatim from third parties, without man-
     62                     gling the existing build structure.  Other source trees in
     63                     bin through usr.sbin use the NetBSD make(1) ``reachover''
     64                     Makefile semantics when building these programs for a na-
     65                     tive host.
     66 
     67      distrib/, etc/
     68                     Sources for items used when making a full release snap-
     69                     shot, such as files installed in DESTDIR/etc on the desti-
     70                     nation system, boot media, and release notes.
     71 
     72      regress/       Regression test harness.  Can be cross-compiled, but only
     73                     run natively.
     74 
     75      sys/           NetBSD kernel sources.
     76 
     77      tools/         ``Reachover'' build structure for the host build tools.
     78                     This has a special method of determining out-of-date sta-
     79                     tus.
     80 
     81      bin/ ... usr.sbin/
     82                     Sources to the NetBSD userland (non-kernel) programs.  If
     83                     any of these directories are missing, they will be skipped
     84                     during the build.
     85 
     86    Build tree layout
     87      The NetBSD build tree is described in hier(7), and the release layout is
     88      described in release(7).
     89 
     90 CONFIGURATION
     91    Environment variables
     92      Several environment variables control the behaviour of NetBSD builds.
     93 
     94      MACHINE           Machine type.
     95 
     96      MACHINE_ARCH      Machine architecture.
     97 
     98      MAKE              Path name to invoke make(1) as.
     99 
    100      MAKEFLAGS         Flags to invoke make(1) with.
    101 
    102      MAKEOBJDIR        Directory to use as the .OBJDIR for the current direc-
    103                        tory.  Used only if MAKEOBJDIRPREFIX is not defined.
    104                        MAKEOBJDIR can only be provided in the environment or
    105                        via the -O flag of build.sh.
    106 
    107      MAKEOBJDIRPREFIX  Top level directory of the object directory tree.  If
    108                        this is defined, ${MAKEOBJDIRPREFIX}/${.CURDIR} is used
    109                        as the .OBJDIR for the current directory.  The current
    110                        directory may be read only.  MAKEOBJDIRPREFIX can only
    111                        be provided in the environment or via the -M flag of
    112                        build.sh.
    113 
    114    "make" variables
    115      Several variables control the behavior of NetBSD builds.  Unless other-
    116      wise specified, these variables may be set in either the process environ-
    117      ment or the make(1) configuration file specified by MAKECONF.
    118 
    119      BUILDID     Identifier for the build.  The identifier will be appended to
    120                  object directory names, and can be consulted in the make(1)
    121                  configuration file in order to set additional build parame-
    122                  ters, such as compiler flags.
    123 
    124      DESTDIR     Directory to contain the built NetBSD system.  If set, spe-
    125                  cial options are passed to the compilation tools to prevent
    126                  their default use of the host system's /usr/include,
    127                  /usr/lib, and so forth.  This pathname should not end with a
    128                  slash (/) character (for installation into the system's root
    129                  directory, set DESTDIR to an empty string).  The directory
    130                  must reside on a file system which supports long file names
    131                  and hard links.
    132 
    133                  Default: Empty string if USETOOLS is ``yes''; unset other-
    134                  wise.
    135 
    136                  Note: build.sh will provide a default of destdir.MACHINE (in
    137                  the top-level .OBJDIR) unless run in `expert' mode
    138 
    139      MAKECONF    The name of the make(1) configuration file.  Only settable in
    140                  the process environment.
    141 
    142                  Default: ``/etc/mk.conf''
    143 
    144      MKCATPAGES  Can be set to ``yes'' or ``no''.  Indicates whether prefor-
    145                  matted plaintext manual pages will be created during a build.
    146 
    147                  Default: ``yes''
    148 
    149      MKCRYPTO    Can be set to ``yes'' or ``no''.  Indicates whether crypto-
    150                  graphic code will be included in a build; provided for the
    151                  benefit of countries that do not allow strong cryptography.
    152                  Will not affect use of the standard low-security password en-
    153                  cryption system, crypt(3).
    154 
    155                  Default: ``yes''
    156 
    157      MKDOC       Can be set to ``yes'' or ``no''.  Indicates whether system
    158                  documentation destined for DESTDIR/usr/share/doc will be in-
    159                  stalled during a build.
    160 
    161                  Default: ``yes''
    162 
    163      MKHOSTOBJ   Can be set to ``yes'' or ``no''.  If set to ``yes'', then for
    164                  programs intended to be run on the compile host, the name,
    165                  release, and architecture of the host operating system will
    166                  be suffixed to the name of the object directory created by
    167                  ``make obj''.  (This allows multiple host systems to compile
    168                  NetBSD for a single target.)  If set to ``no'', then programs
    169                  built to be run on the compile host will use the same object
    170                  directory names as programs built to be run on the target.
    171 
    172                  Default: ``no''
    173 
    174      MKINFO      Can be set to ``yes'' or ``no''.  Indicates whether GNU Info
    175                  files, used for the documentation for most of the compilation
    176                  tools, will be created and installed during a build.
    177 
    178                  Default: ``yes''
    179 
    180      MKLINT      Can be set to ``yes'' or ``no''.  Indicates whether lint(1)
    181                  will be run against portions of the NetBSD source code during
    182                  the build, and whether lint libraries will be installed into
    183                  DESTDIR/usr/libdata/lint.
    184 
    185                  Default: ``yes''
    186 
    187      MKMAN       Can be set to ``yes'' or ``no''.  Indicates whether manual
    188                  pages will be installed during a build.
    189 
    190                  Default: ``yes''
    191 
    192      MKNLS       Can be set to ``yes'' or ``no''.  Indicates whether Native
    193                  Language System locale zone files will be compiled and in-
    194                  stalled during a build.
    195 
    196                  Default: ``yes''
    197 
    198      MKOBJ       Can be set to ``yes'' or ``no''.  Indicates whether object
    199                  directories will be created when running ``make obj''.  If
    200                  set to ``no'', then all built files will be located inside
    201                  the regular source tree.
    202 
    203                  Default: ``yes''
    204 
    205      MKPIC       Can be set to ``yes'' or ``no''.  Indicates whether shared
    206                  objects and libraries will be created and installed during a
    207                  build.  If set to ``no'', the entire built system will be
    208                  statically linked.
    209 
    210                  Default: Platform dependent.  As of this writing, all plat-
    211                  forms except sh3 default to ``yes''.
    212 
    213      MKPICINSTALL
    214                  Can be set to ``yes'' or ``no''.  Indicates whether the ar(1)
    215                  format libraries (lib*_pic.a), used to generate shared li-
    216                  braries, are installed during a build.
    217 
    218                  Default: ``yes''
    219 
    220      MKPROFILE   Can be set to ``yes'' or ``no''.  Indicates whether profiled
    221                  libraries (lib*_p.a) will be built and installed during a
    222                  build.
    223 
    224                  Default: ``yes''; however, some platforms turn off MKPROFILE
    225                  by default at times due to toolchain problems with profiled
    226                  code.
    227 
    228      MKSHARE     Can be set to ``yes'' or ``no''.  Indicates whether files
    229                  destined to reside in DESTDIR/usr/share will be built and in-
    230                  stalled during a build.  If set to ``no'', then all of
    231                  MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to
    232                  ``no'' unconditionally.
    233 
    234                  Default: ``yes''
    235 
    236      MKUNPRIVED  Can be set to ``yes'' or ``no''.  Indicates whether an un-
    237                  privileged install will occur.  The user, group, permissions,
    238                  and file flags, will not be set on the installed item; in-
    239                  stead the information will be appended to a file called
    240                  METALOG in DESTDIR.  The contents of METALOG is used during
    241                  the generation of the distribution tar files to ensure that
    242                  the appropriate file ownership is stored.
    243 
    244                  Default: ``no''
    245 
    246      MKUPDATE    Can be set to ``yes'' or ``no''.  Indicates whether all in-
    247                  stall operations intended to write to DESTDIR will compare
    248                  file timestamps before installing, and skip the install phase
    249                  if the destination files are up-to-date.  This also has im-
    250                  plications on full builds (see next subsection).
    251 
    252                  Default: ``no''
    253 
    254      TOOLDIR     Directory to hold the host tools, once built.  This directory
    255                  should be unique to a given host system and NetBSD source
    256                  tree.  (However, multiple targets may share the same TOOLDIR;
    257                  the target-dependent files have unique names.)  If unset, a
    258                  default based on the uname(1) information of the host plat-
    259                  form will be created in the .OBJDIR of src.
    260 
    261                  Default: Unset.
    262 
    263      USETOOLS    Indicates whether the tools specified by TOOLDIR should be
    264                  used as part of a build in progress.  Must be set to ``yes''
    265                  if cross-compiling.
    266 
    267                  yes    Use the tools from TOOLDIR.
    268 
    269                  no     Do not use the tools from TOOLDIR, but refuse to build
    270                         native compilation tool components that are version-
    271                         specific for that tool.
    272 
    273                  never  Do not use the tools from TOOLDIR, even when building
    274                         native tool components.  This is similar to the tradi-
    275                         tional NetBSD build method, but does not verify that
    276                         the compilation tools in use are up-to-date enough in
    277                         order to build the tree successfully.  This may cause
    278                         build or runtime problems when building the whole
    279                         NetBSD source tree.
    280 
    281                  Default: ``yes'' if building all or part of a whole NetBSD
    282                  source tree (detected automatically); ``no'' otherwise (to
    283                  preserve traditional semantics of the <bsd.*.mk> make(1) in-
    284                  clude files).
    285 
    286    "make" variables for full builds
    287      These variables only affect the top level ``Makefile'' and do not affect
    288      manually building subtrees of the NetBSD source code.
    289 
    290      INSTALLWORLDDIR  Location for the ``make installworld'' target to install
    291                       to.
    292 
    293                       Default: ``/''
    294 
    295      MKOBJDIRS        Can be set to ``yes'' or ``no''.  Indicates whether ob-
    296                       ject directories will be created automatically (via a
    297                       ``make obj'' pass) at the start of a build.
    298 
    299                       Default: ``no''
    300 
    301      MKUPDATE         Can be set to ``yes'' or ``no''.  If set, then in addi-
    302                       tion to the effects described for MKUPDATE=yes above,
    303                       this implies the effects of NOCLEANDIR (i.e., ``make
    304                       cleandir'' is avoided).
    305 
    306                       Default: ``no''
    307 
    308      NBUILDJOBS       Now obsolete.  Use the make(1) option -j, instead (see
    309                       below)
    310 
    311                       Default: Unset.
    312 
    313      NOCLEANDIR       If set, avoids the ``make cleandir'' phase of a full
    314                       build.  This has the effect of allowing only changed
    315                       files in a source tree to be recompiled.  This can speed
    316                       up builds when updating only a few files in the tree.
    317 
    318                       Default: Unset.
    319 
    320      NODISTRIBDIRS    If set, avoids the ``make distrib-dirs'' phase of a full
    321                       build.  This skips running mtree(8) on DESTDIR, useful
    322                       on systems where building as an unprivileged user, or
    323                       where it is known that the system-wide mtree files have
    324                       not changed.
    325 
    326                       Default: Unset.
    327 
    328      NOINCLUDES       If set, avoids the ``make includes'' phase of a full
    329                       build.  This has the effect of preventing make(1) from
    330                       thinking that some programs are out-of-date simply be-
    331                       cause the system include files have changed.  However,
    332                       this option should not be used when updating the entire
    333                       NetBSD source tree arbitrarily; it is suggested to use
    334                       MKUPDATE=yes in that case.
    335 
    336                       Default: Unset.
    337 
    338      RELEASEDIR       If set, specifies the directory to which a release(7)
    339                       layout will be written at the end of a ``make release''.
    340 
    341                       Default: Unset.
    342 
    343                       Note: build.sh will provide a default of releasedir (in
    344                       the top-level .OBJDIR) unless run in `expert' mode
    345 
    346 BUILDING
    347    "make" command line options
    348      This is only a summary of options available to make(1); only the options
    349      used most frequently with NetBSD builds are listed here.
    350 
    351      -j njob    Run up to njob make(1) subjobs in parallel.  Makefiles should
    352                 use .WAIT or have explicit dependancies as necessary to en-
    353                 force build ordering.  If you see build failures with -j,
    354                 please save complete build logs so the failures can be ana-
    355                 lyzed.
    356 
    357      -m dir     Specify the default directory for searching for system Make-
    358                 file segments, mainly the <bsd.*.mk> files.  When building any
    359                 full NetBSD source tree, this should be set to the
    360                 ``share/mk'' directory in the source tree.  (This is set auto-
    361                 matically when building from the top level.)
    362 
    363      -n         Display the commands that would have been executed, but do not
    364                 actually execute them.  This will still cause recursion to
    365                 take place.
    366 
    367      -v var     Print make(1)'s idea of the value of var.  Does not build any
    368                 targets.
    369 
    370      var=value  Set the variable var to value, overriding any setting speci-
    371                 fied by the process environment, the MAKECONF configuration
    372                 file, or the system Makefile segments.
    373 
    374    "make" targets
    375      These default targets may be built by running make(1) in any subtree of
    376      the NetBSD source code.  It is recommended that none of these be used
    377      from the top level Makefile; as a specific exception, ``make obj'' and
    378      ``make cleandir'' are useful in that context.
    379 
    380      all        Build programs, libraries, and preformatted documentation.
    381 
    382      clean      Remove program and library object code files.
    383 
    384      cleandir   Same as clean, but also remove preformatted documentation, de-
    385                 pendency files generated by ``make depend'', and any other
    386                 files known to be created at build time.  ``make distclean''
    387                 may be used as a synonym, for familiarity with a similar well-
    388                 known convention.
    389 
    390      depend     Create dependency files (.depend) containing more detailed in-
    391                 formation about the dependencies of source code on header
    392                 files.  Allows programs to be recompiled automatically when a
    393                 dependency changes.
    394 
    395      dependall  Does a ``make depend'' immediately followed by a ``make all''.
    396                 This improves cache locality of the build since both passes
    397                 read the source files in their entirety.
    398 
    399      includes   Build and install system header files.  Typically needed be-
    400                 fore any system libraries or programs can be built.
    401 
    402      install    Install programs, libraries, and documentation into DESTDIR.
    403                 Few files will be installed to DESTDIR/dev, DESTDIR/etc,
    404                 DESTDIR/root or DESTDIR/var in order to prevent user supplied
    405                 configuration data from being overwritten.
    406 
    407      lint       Run lint(1) against the C source code, where appropriate, and
    408                 generate system-installed lint libraries.
    409 
    410      obj        Create object directories to be used for built files, instead
    411                 of building directly in the source tree.
    412 
    413      tags       Create ctags(1) searchable function lists usable by the ex(1)
    414                 and vi(1) text editors.
    415 
    416    "make" targets for the top level
    417      Additional make(1) targets are usable specifically from the top source
    418      level to facilitate building the entire NetBSD source tree.
    419 
    420      build         Build the entire NetBSD system.  This orders portions of
    421                    the source tree such that prerequisites will be built in
    422                    the proper order.
    423 
    424      distribution  Do a ``make build'', and then install a full distribution
    425                    into DESTDIR, including files in DESTDIR/dev, DESTDIR/etc,
    426                    DESTDIR/root and DESTDIR/var.
    427 
    428      buildworld    As per ``make distribution'', except that it ensures that
    429                    DESTDIR is not the root directory.
    430 
    431      installworld  Install the distribution from DESTDIR to INSTALLWORLDDIR
    432                    (which defaults to the root directory).  Ensures that
    433                    INSTALLWORLDDIR is the not root directory if cross compil-
    434                    ing.
    435 
    436                    Note: It is highly recommended that you upgrade your kernel
    437                    and reboot before performing this operation.
    438 
    439      sets          Create distribution sets from DESTDIR into
    440                    RELEASEDIR/MACHINE/binary/sets.  Should be run after ``make
    441                    distribution'' (as ``make build'' does not install all of
    442                    the required files).
    443 
    444      sourcesets    Create source sets of the source tree into
    445                    RELEASEDIR/source/sets.
    446 
    447      release       Do a ``make distribution'', build kernels, distribution me-
    448                    dia, and install sets (this as per ``make sets''), and then
    449                    package the system into a standard release layout as de-
    450                    scribed by release(7).  This requires that RELEASEDIR be
    451                    set (see above).
    452 
    453      regression-tests
    454                    Can only be run after building the regression tests in the
    455                    directory ``regress''.  Runs the compiled regression tests
    456                    on the local host.
    457 
    458    The "build.sh" script
    459      This script file is a Bourne shell script designed to build the entire
    460      NetBSD system on any host with a Bourne shell in /bin/sh, including many
    461      that are not POSIX compliant.  Note that if a host system's /bin/sh is
    462      unusually old and broken, the Korn Shell (/bin/ksh), if available, may be
    463      a usable alternative.
    464 
    465      All cross-compile builds, and most native builds, of the entire system
    466      should make use of build.sh rather than just running ``make''.  This way,
    467      the make(1) program will be bootstrapped properly, in case the host sys-
    468      tem has an older or incompatible ``make'' program.
    469 
    470      When compiling the entire system via build.sh, many make(1) variables are
    471      set for you in order to help encapsulate the build process.  In the list
    472      of options below, variables that are automatically set by build.sh are
    473      noted where applicable.
    474 
    475      The following operations are supported by build.sh:
    476 
    477      build         Build the system as per ``make build''.  This option im-
    478                    plies the obj and tools operations.
    479 
    480      distribution  Build a full distribution as per ``make distribution''.
    481                    This option implies the build operation.
    482 
    483      release       Build a full release as per ``make release''.  This option
    484                    implies the distribution operation.
    485 
    486      makewrapper   Create the nbmake-MACHINE wrapper.  This operation is auto-
    487                    matically performed for any of the other operations.
    488 
    489      obj           Perform ``make obj''.
    490 
    491      tools         Build and install the host tools from src/tools.
    492 
    493      install=idir  Install the contents of DESTDIR to idir, using ``make
    494                    installworld''.
    495 
    496      kernel=kconf  Build a new kernel.  The kconf argument is the name of a
    497                    configuration file suitable for use by config(8).  If kconf
    498                    does not contain any `/' characters, the configuration file
    499                    is expected to be found in the KERNCONFDIR directory, which
    500                    is typically sys/arch/MACHINE/conf.  The new kernel will be
    501                    built in a subdirectory of KERNOBJDIR, which is typically
    502                    sys/arch/MACHINE/compile or an associated object directory.
    503                    In order to ensure that the kernel is built using up-to-
    504                    date tools, it is strongly recommended that the tools be
    505                    rebuilt (using the tools operation).
    506 
    507      releasekernel=kconf
    508                    Install a gzip(1)ed copy of the kernel built by
    509                    kernel=kconf into RELEASEDIR/MACHINE/binary/kernel, usually
    510                    as netbsd-kconf.gz, although the ``netbsd'' prefix is de-
    511                    termined from the ``config'' directives in kconf.
    512 
    513      sets          Perform ``make sets''.
    514 
    515      sourcesets    Perform ``make sourcesets''.
    516 
    517      The following command line options alter the behaviour of the above oper-
    518      ations: The following command line options alter the behaviour of the
    519      build.sh operations described above:
    520 
    521      -a arch   Set the value of MACHINE_ARCH to arch.
    522 
    523      -B buildid
    524                Set the value of BUILDID to buildid.  This will also append the
    525                build idenfitier to the name of the ``make'' wrapper script so
    526                that the resulting name is of the form
    527                ``nbmake-MACHINE-BUILDID''.
    528 
    529      -D dest   Set the value of DESTDIR to dest.
    530 
    531      -E        Set `expert' mode.  This overrides various sanity checks, and
    532                allows: DESTDIR does not have to be set to a non-root path for
    533                builds, and MKUNPRIVED=yes does not have to be set when build-
    534                ing as a non-root user.
    535 
    536                Note: It is highly recommended that you know what you are doing
    537                when you use this option.
    538 
    539      -j njob   Passed through to make(1).  Makefiles should use .WAIT or have
    540                explicit dependancies as necessary to enforce build ordering.
    541                If you see build failures with -j, please save complete build
    542                logs so the failures can be analyzed.
    543 
    544      -M obj    Set MAKEOBJDIRPREFIX to obj.  Unsets MAKEOBJDIR.
    545 
    546      -m mach   Set the value of MACHINE to mach.  This will also override any
    547                value of MACHINE_ARCH in the process environment with a value
    548                deduced from mach, unless -a is specified, or mach is a special
    549                case listed below.  All cross builds require -m, but if unset
    550                on a NetBSD host, the host's value of MACHINE will be detected
    551                and used automatically.
    552 
    553                Some machines support multiple values for MACHINE_ARCH.  For a
    554                given value of mach, the following MACHINE and MACHINE_ARCH
    555                values will result:
    556 
    557                      mach          MACHINE    MACHINE_ARCH
    558                      evbmips       evbmips    (not set)
    559                      evbmips-eb    evbmips    mipseb
    560                      evbmips-el    evbmips    mipsel
    561                      evbsh3        evbsh3     (not set)
    562                      evbsh3-eb     evbsh3     sh3eb
    563                      evbsh3-el     evbsh3     sh3el
    564                      sbmips        sbmips     (not set)
    565                      sbmips-eb     sbmips     mipseb
    566                      sbmips-el     sbmips     mipsel
    567 
    568      -n        Show the commands that would be executed by build.sh, but do
    569                not make any changes.  This is similar in concept to ``make
    570                -n''.
    571 
    572      -O obj    Create an appropriate transform macro for MAKEOBJDIR that will
    573                place the built object files under obj.  For instance, a set-
    574                ting of /usr/obj will place build-time files under
    575                /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, and so forth.
    576                Unsets MAKEOBJDIRPREFIX.
    577 
    578      -o        Set the value of MKOBJDIRS to ``no''.  Otherwise, it will be
    579                automatically set to ``yes'' (which is opposite to the default
    580                behaviour).
    581 
    582      -R rel    Set the value of RELEASEDIR to rel.
    583 
    584      -r        Remove the contents of DESTDIR and TOOLDIR before building
    585                (provides a clean starting point).  This will skip deleting
    586                DESTDIR if building on a native system to the root directory.
    587 
    588      -T tools  Set the value of TOOLDIR to tools.  If set, the bootstrap
    589                ``make'' will only be rebuilt as needed (when the source files
    590                for make(1) change).
    591 
    592      -U        Set MKUNPRIVED=yes.
    593 
    594      -u        Set MKUPDATE=yes.
    595 
    596      -V var=[value]
    597                Set the environment variable var to an optional value.  This is
    598                propagated to the nbmake wrapper.
    599 
    600      -w wrapper
    601                Create the nbmake wrapper script (see below) in a custom loca-
    602                tion, specified by wrapper.  This allows, for instance, to
    603                place the wrapper in PATH automatically.  Note that wrapper is
    604                the full name of the file, not just a directory name.
    605 
    606      -Z var    Unset ("zap") the environment variable var.  This is propagated
    607                to the nbmake wrapper.
    608 
    609    The "nbmake-MACHINE" wrapper script
    610      If using the build.sh script to build NetBSD, a nbmake-MACHINE script
    611      will be created in TOOLDIR/bin upon the first build to assist in building
    612      subtrees on a cross-compile host.
    613 
    614      nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
    615      the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with sev-
    616      eral key variables pre-set, including MACHINE, MACHINE_ARCH, and TOOLDIR.
    617      build.sh will also set variables specified with -V, and unset variables
    618      specified with -Z.
    619 
    620      This script can be symlinked into a directory listed in PATH, or called
    621      with an absolute path.
    622 
    623 EXAMPLES
    624      1.   ./build.sh tools kernel=GENERIC
    625 
    626           Build a new toolchain, and use the new toolchain to configure and
    627           build a new GENERIC kernel.
    628 
    629      2.   ./build.sh -U distribution
    630 
    631           Using unprivileged mode, build a complete distribution to a DESTDIR
    632           directory that build.sh selects (and will display).
    633 
    634      3.   # ./build.sh -U install=/
    635 
    636           As root, install to / the distribution that was built by example 2.
    637           Even though this is run as root, -U is required so that the permis-
    638           sions stored in DESTDIR/METALOG are correctly applied to the files
    639           as they're copied to /.
    640 
    641      4.   ./build.sh -U -u release
    642 
    643           Using unprivileged mode, build a complete release to DESTDIR and
    644           RELEASEDIR directories that build.sh selects (and will display).
    645           MKUPDATE=yes (-u) is set to prevent the ``make cleandir'', so that
    646           if this is run after example 2, it doesn't need to redo that portion
    647           of the release build.
    648 
    649 OBSOLETE VARIABLES
    650      NBUILDJOBS  Use the make(1) option -j, instead.
    651 
    652      USE_NEW_TOOLCHAIN
    653                  The new toolchain is now the default.  To disable, use
    654                  TOOLCHAIN_MISSING=yes.
    655 
    656 SEE ALSO
    657      make(1), hier(7), release(7)
    658 
    659 HISTORY
    660      The build.sh based build scheme was introduced for NetBSD 1.6 as
    661      USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.
    662 
    663 BUGS
    664      A few platforms are not yet using this build system.
    665 
    666 NetBSD                          August 7, 2003                          NetBSD
    667