Home | History | Annotate | Line # | Download | only in src
BUILDING revision 1.46
      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
     13      implementation 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
     46                     native 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
     65                     native 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      MAKEVERBOSE
    145                  Level of verbosity of status messages.  Supported values:
    146 
    147                  0    No descriptive messages are shown.
    148 
    149                  1    Descriptive messages are shown.
    150 
    151                  2    Descriptive messages (prefixed with a `#') and command
    152                       output is not suppressed.
    153 
    154                  Default: 2
    155 
    156      MKCATPAGES  Can be set to ``yes'' or ``no''.  Indicates whether prefor-
    157                  matted plaintext manual pages will be created during a build.
    158 
    159                  Default: ``yes''
    160 
    161      MKCRYPTO    Can be set to ``yes'' or ``no''.  Indicates whether crypto-
    162                  graphic code will be included in a build; provided for the
    163                  benefit of countries that do not allow strong cryptography.
    164                  Will not affect use of the standard low-security password
    165                  encryption system, crypt(3).
    166 
    167                  Default: ``yes''
    168 
    169      MKDOC       Can be set to ``yes'' or ``no''.  Indicates whether system
    170                  documentation destined for DESTDIR/usr/share/doc will be
    171                  installed during a build.
    172 
    173                  Default: ``yes''
    174 
    175      MKHOSTOBJ   Can be set to ``yes'' or ``no''.  If set to ``yes'', then for
    176                  programs intended to be run on the compile host, the name,
    177                  release, and architecture of the host operating system will
    178                  be suffixed to the name of the object directory created by
    179                  ``make obj''.  (This allows multiple host systems to compile
    180                  NetBSD for a single target.)  If set to ``no'', then programs
    181                  built to be run on the compile host will use the same object
    182                  directory names as programs built to be run on the target.
    183 
    184                  Default: ``no''
    185 
    186      MKINFO      Can be set to ``yes'' or ``no''.  Indicates whether GNU Info
    187                  files, used for the documentation for most of the compilation
    188                  tools, will be created and installed during a build.
    189 
    190                  Default: ``yes''
    191 
    192      MKLINT      Can be set to ``yes'' or ``no''.  Indicates whether lint(1)
    193                  will be run against portions of the NetBSD source code during
    194                  the build, and whether lint libraries will be installed into
    195                  DESTDIR/usr/libdata/lint.
    196 
    197                  Default: ``yes''
    198 
    199      MKMAN       Can be set to ``yes'' or ``no''.  Indicates whether manual
    200                  pages will be installed during a build.
    201 
    202                  Default: ``yes''
    203 
    204      MKNLS       Can be set to ``yes'' or ``no''.  Indicates whether Native
    205                  Language System locale zone files will be compiled and
    206                  installed during a build.
    207 
    208                  Default: ``yes''
    209 
    210      MKOBJ       Can be set to ``yes'' or ``no''.  Indicates whether object
    211                  directories will be created when running ``make obj''.  If
    212                  set to ``no'', then all built files will be located inside
    213                  the regular source tree.
    214 
    215                  Default: ``yes''
    216 
    217      MKPIC       Can be set to ``yes'' or ``no''.  Indicates whether shared
    218                  objects and libraries will be created and installed during a
    219                  build.  If set to ``no'', the entire built system will be
    220                  statically linked.
    221 
    222                  Default: Platform dependent.  As of this writing, all plat-
    223                  forms except sh3 default to ``yes''.
    224 
    225      MKPICINSTALL
    226                  Can be set to ``yes'' or ``no''.  Indicates whether the ar(1)
    227                  format libraries (lib*_pic.a), used to generate shared
    228                  libraries, are installed during a build.
    229 
    230                  Default: ``yes''
    231 
    232      MKPROFILE   Can be set to ``yes'' or ``no''.  Indicates whether profiled
    233                  libraries (lib*_p.a) will be built and installed during a
    234                  build.
    235 
    236                  Default: ``yes''; however, some platforms turn off MKPROFILE
    237                  by default at times due to toolchain problems with profiled
    238                  code.
    239 
    240      MKSHARE     Can be set to ``yes'' or ``no''.  Indicates whether files
    241                  destined to reside in DESTDIR/usr/share will be built and
    242                  installed during a build.  If set to ``no'', then all of
    243                  MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to
    244                  ``no'' unconditionally.
    245 
    246                  Default: ``yes''
    247 
    248      MKUNPRIVED  Can be set to ``yes'' or ``no''.  Indicates whether an
    249                  unprivileged install will occur.  The user, group, permis-
    250                  sions, and file flags, will not be set on the installed item;
    251                  instead the information will be appended to a file called
    252                  METALOG in DESTDIR.  The contents of METALOG is used during
    253                  the generation of the distribution tar files to ensure that
    254                  the appropriate file ownership is stored.
    255 
    256                  Default: ``no''
    257 
    258      MKUPDATE    Can be set to ``yes'' or ``no''.  Indicates whether all
    259                  install operations intended to write to DESTDIR will compare
    260                  file timestamps before installing, and skip the install phase
    261                  if the destination files are up-to-date.  This also has
    262                  implications on full builds (see next subsection).
    263 
    264                  Default: ``no''
    265 
    266      TOOLDIR     Directory to hold the host tools, once built.  This directory
    267                  should be unique to a given host system and NetBSD source
    268                  tree.  (However, multiple targets may share the same TOOLDIR;
    269                  the target-dependent files have unique names.)  If unset, a
    270                  default based on the uname(1) information of the host plat-
    271                  form will be created in the .OBJDIR of src.
    272 
    273                  Default: Unset.
    274 
    275      USETOOLS    Indicates whether the tools specified by TOOLDIR should be
    276                  used as part of a build in progress.  Must be set to ``yes''
    277                  if cross-compiling.
    278 
    279                  yes    Use the tools from TOOLDIR.
    280 
    281                  no     Do not use the tools from TOOLDIR, but refuse to build
    282                         native compilation tool components that are version-
    283                         specific for that tool.
    284 
    285                  never  Do not use the tools from TOOLDIR, even when building
    286                         native tool components.  This is similar to the tradi-
    287                         tional NetBSD build method, but does not verify that
    288                         the compilation tools in use are up-to-date enough in
    289                         order to build the tree successfully.  This may cause
    290                         build or runtime problems when building the whole
    291                         NetBSD source tree.
    292 
    293                  Default: ``yes'' if building all or part of a whole NetBSD
    294                  source tree (detected automatically); ``no'' otherwise (to
    295                  preserve traditional semantics of the <bsd.*.mk> make(1)
    296                  include files).
    297 
    298    "make" variables for full builds
    299      These variables only affect the top level ``Makefile'' and do not affect
    300      manually building subtrees of the NetBSD source code.
    301 
    302      INSTALLWORLDDIR  Location for the ``make installworld'' target to install
    303                       to.
    304 
    305                       Default: ``/''
    306 
    307      MKOBJDIRS        Can be set to ``yes'' or ``no''.  Indicates whether
    308                       object directories will be created automatically (via a
    309                       ``make obj'' pass) at the start of a build.
    310 
    311                       Default: ``no''
    312 
    313      MKUPDATE         Can be set to ``yes'' or ``no''.  If set, then in addi-
    314                       tion to the effects described for MKUPDATE=yes above,
    315                       this implies the effects of NOCLEANDIR (i.e., ``make
    316                       cleandir'' is avoided).
    317 
    318                       Default: ``no''
    319 
    320      NBUILDJOBS       Now obsolete.  Use the make(1) option -j, instead (see
    321                       below)
    322 
    323                       Default: Unset.
    324 
    325      NOCLEANDIR       If set, avoids the ``make cleandir'' phase of a full
    326                       build.  This has the effect of allowing only changed
    327                       files in a source tree to be recompiled.  This can speed
    328                       up builds when updating only a few files in the tree.
    329 
    330                       Default: Unset.
    331 
    332      NODISTRIBDIRS    If set, avoids the ``make distrib-dirs'' phase of a full
    333                       build.  This skips running mtree(8) on DESTDIR, useful
    334                       on systems where building as an unprivileged user, or
    335                       where it is known that the system-wide mtree files have
    336                       not changed.
    337 
    338                       Default: Unset.
    339 
    340      NOINCLUDES       If set, avoids the ``make includes'' phase of a full
    341                       build.  This has the effect of preventing make(1) from
    342                       thinking that some programs are out-of-date simply
    343                       because the system include files have changed.  However,
    344                       this option should not be used when updating the entire
    345                       NetBSD source tree arbitrarily; it is suggested to use
    346                       MKUPDATE=yes in that case.
    347 
    348                       Default: Unset.
    349 
    350      RELEASEDIR       If set, specifies the directory to which a release(7)
    351                       layout will be written at the end of a ``make release''.
    352 
    353                       Default: Unset.
    354 
    355                       Note: build.sh will provide a default of releasedir (in
    356                       the top-level .OBJDIR) unless run in `expert' mode
    357 
    358 BUILDING
    359    "make" command line options
    360      This is only a summary of options available to make(1); only the options
    361      used most frequently with NetBSD builds are listed here.
    362 
    363      -j njob    Run up to njob make(1) subjobs in parallel.  Makefiles should
    364                 use .WAIT or have explicit dependancies as necessary to
    365                 enforce build ordering.  If you see build failures with -j,
    366                 please save complete build logs so the failures can be ana-
    367                 lyzed.
    368 
    369      -m dir     Specify the default directory for searching for system Make-
    370                 file segments, mainly the <bsd.*.mk> files.  When building any
    371                 full NetBSD source tree, this should be set to the
    372                 ``share/mk'' directory in the source tree.  (This is set auto-
    373                 matically when building from the top level.)
    374 
    375      -n         Display the commands that would have been executed, but do not
    376                 actually execute them.  This will still cause recursion to
    377                 take place.
    378 
    379      -v var     Print make(1)'s idea of the value of var.  Does not build any
    380                 targets.
    381 
    382      var=value  Set the variable var to value, overriding any setting speci-
    383                 fied by the process environment, the MAKECONF configuration
    384                 file, or the system Makefile segments.
    385 
    386    "make" targets
    387      These default targets may be built by running make(1) in any subtree of
    388      the NetBSD source code.  It is recommended that none of these be used
    389      from the top level Makefile; as a specific exception, ``make obj'' and
    390      ``make cleandir'' are useful in that context.
    391 
    392      all        Build programs, libraries, and preformatted documentation.
    393 
    394      clean      Remove program and library object code files.
    395 
    396      cleandir   Same as clean, but also remove preformatted documentation,
    397                 dependency files generated by ``make depend'', and any other
    398                 files known to be created at build time.  ``make distclean''
    399                 may be used as a synonym, for familiarity with a similar well-
    400                 known convention.
    401 
    402      depend     Create dependency files (.depend) containing more detailed
    403                 information about the dependencies of source code on header
    404                 files.  Allows programs to be recompiled automatically when a
    405                 dependency changes.
    406 
    407      dependall  Does a ``make depend'' immediately followed by a ``make all''.
    408                 This improves cache locality of the build since both passes
    409                 read the source files in their entirety.
    410 
    411      includes   Build and install system header files.  Typically needed
    412                 before any system libraries or programs can be built.
    413 
    414      install    Install programs, libraries, and documentation into DESTDIR.
    415                 Few files will be installed to DESTDIR/dev, DESTDIR/etc,
    416                 DESTDIR/root or DESTDIR/var in order to prevent user supplied
    417                 configuration data from being overwritten.
    418 
    419      lint       Run lint(1) against the C source code, where appropriate, and
    420                 generate system-installed lint libraries.
    421 
    422      obj        Create object directories to be used for built files, instead
    423                 of building directly in the source tree.
    424 
    425      tags       Create ctags(1) searchable function lists usable by the ex(1)
    426                 and vi(1) text editors.
    427 
    428    "make" targets for the top level
    429      Additional make(1) targets are usable specifically from the top source
    430      level to facilitate building the entire NetBSD source tree.
    431 
    432      build         Build the entire NetBSD system.  This orders portions of
    433                    the source tree such that prerequisites will be built in
    434                    the proper order.
    435 
    436      distribution  Do a ``make build'', and then install a full distribution
    437                    into DESTDIR, including files in DESTDIR/dev, DESTDIR/etc,
    438                    DESTDIR/root and DESTDIR/var.
    439 
    440      buildworld    As per ``make distribution'', except that it ensures that
    441                    DESTDIR is not the root directory.
    442 
    443      installworld  Install the distribution from DESTDIR to INSTALLWORLDDIR
    444                    (which defaults to the root directory).  Ensures that
    445                    INSTALLWORLDDIR is the not root directory if cross compil-
    446                    ing.
    447 
    448                    Note: It is highly recommended that you upgrade your kernel
    449                    and reboot before performing this operation.
    450 
    451      sets          Create distribution sets from DESTDIR into
    452                    RELEASEDIR/MACHINE/binary/sets.  Should be run after ``make
    453                    distribution'' (as ``make build'' does not install all of
    454                    the required files).
    455 
    456      sourcesets    Create source sets of the source tree into
    457                    RELEASEDIR/source/sets.
    458 
    459      release       Do a ``make distribution'', build kernels, distribution
    460                    media, and install sets (this as per ``make sets''), and
    461                    then package the system into a standard release layout as
    462                    described by release(7).  This requires that RELEASEDIR be
    463                    set (see above).
    464 
    465      regression-tests
    466                    Can only be run after building the regression tests in the
    467                    directory ``regress''.  Runs the compiled regression tests
    468                    on the local host.
    469 
    470    The "build.sh" script
    471      This script file is a Bourne shell script designed to build the entire
    472      NetBSD system on any host with a Bourne shell in /bin/sh, including many
    473      that are not POSIX compliant.  Note that if a host system's /bin/sh is
    474      unusually old and broken, the Korn Shell (/bin/ksh), if available, may be
    475      a usable alternative.
    476 
    477      All cross-compile builds, and most native builds, of the entire system
    478      should make use of build.sh rather than just running ``make''.  This way,
    479      the make(1) program will be bootstrapped properly, in case the host sys-
    480      tem has an older or incompatible ``make'' program.
    481 
    482      When compiling the entire system via build.sh, many make(1) variables are
    483      set for you in order to help encapsulate the build process.  In the list
    484      of options below, variables that are automatically set by build.sh are
    485      noted where applicable.
    486 
    487      The following operations are supported by build.sh:
    488 
    489      build         Build the system as per ``make build''.  This option
    490                    implies the obj and tools operations.
    491 
    492      distribution  Build a full distribution as per ``make distribution''.
    493                    This option implies the build operation.
    494 
    495      release       Build a full release as per ``make release''.  This option
    496                    implies the distribution operation.
    497 
    498      makewrapper   Create the nbmake-MACHINE wrapper.  This operation is auto-
    499                    matically performed for any of the other operations.
    500 
    501      obj           Perform ``make obj''.
    502 
    503      tools         Build and install the host tools from src/tools.
    504 
    505      install=idir  Install the contents of DESTDIR to idir, using ``make
    506                    installworld''.
    507 
    508      kernel=kconf  Build a new kernel.  The kconf argument is the name of a
    509                    configuration file suitable for use by config(8).  If kconf
    510                    does not contain any `/' characters, the configuration file
    511                    is expected to be found in the KERNCONFDIR directory, which
    512                    is typically sys/arch/MACHINE/conf.  The new kernel will be
    513                    built in a subdirectory of KERNOBJDIR, which is typically
    514                    sys/arch/MACHINE/compile or an associated object directory.
    515                    In order to ensure that the kernel is built using up-to-
    516                    date tools, it is strongly recommended that the tools be
    517                    rebuilt (using the tools operation).
    518 
    519      releasekernel=kconf
    520                    Install a gzip(1)ed copy of the kernel built by
    521                    kernel=kconf into RELEASEDIR/MACHINE/binary/kernel, usually
    522                    as netbsd-kconf.gz, although the ``netbsd'' prefix is
    523                    determined from the ``config'' directives in kconf.
    524 
    525      sets          Perform ``make sets''.
    526 
    527      sourcesets    Perform ``make sourcesets''.
    528 
    529      The following command line options alter the behaviour of the above oper-
    530      ations: The following command line options alter the behaviour of the
    531      build.sh operations described above:
    532 
    533      -a arch   Set the value of MACHINE_ARCH to arch.
    534 
    535      -B buildid
    536                Set the value of BUILDID to buildid.  This will also append the
    537                build idenfitier to the name of the ``make'' wrapper script so
    538                that the resulting name is of the form
    539                ``nbmake-MACHINE-BUILDID''.
    540 
    541      -D dest   Set the value of DESTDIR to dest.
    542 
    543      -E        Set `expert' mode.  This overrides various sanity checks, and
    544                allows: DESTDIR does not have to be set to a non-root path for
    545                builds, and MKUNPRIVED=yes does not have to be set when build-
    546                ing as a non-root user.
    547 
    548                Note: It is highly recommended that you know what you are doing
    549                when you use this option.
    550 
    551      -j njob   Passed through to make(1).  Makefiles should use .WAIT or have
    552                explicit dependancies as necessary to enforce build ordering.
    553                If you see build failures with -j, please save complete build
    554                logs so the failures can be analyzed.
    555 
    556      -M obj    Set MAKEOBJDIRPREFIX to obj.  Unsets MAKEOBJDIR.
    557 
    558      -m mach   Set the value of MACHINE to mach.  This will also override any
    559                value of MACHINE_ARCH in the process environment with a value
    560                deduced from mach, unless -a is specified, or mach is a special
    561                case listed below.  All cross builds require -m, but if unset
    562                on a NetBSD host, the host's value of MACHINE will be detected
    563                and used automatically.
    564 
    565                Some machines support multiple values for MACHINE_ARCH.  For a
    566                given value of mach, the following MACHINE and MACHINE_ARCH
    567                values will result:
    568 
    569                      mach          MACHINE    MACHINE_ARCH
    570                      evbmips       evbmips    (not set)
    571                      evbmips-eb    evbmips    mipseb
    572                      evbmips-el    evbmips    mipsel
    573                      evbsh3        evbsh3     (not set)
    574                      evbsh3-eb     evbsh3     sh3eb
    575                      evbsh3-el     evbsh3     sh3el
    576                      sbmips        sbmips     (not set)
    577                      sbmips-eb     sbmips     mipseb
    578                      sbmips-el     sbmips     mipsel
    579 
    580      -N noiselevel
    581                Set the ``noisyness'' level of the build, by setting
    582                MAKEVERBOSE to noiselevel.
    583 
    584      -n        Show the commands that would be executed by build.sh, but do
    585                not make any changes.  This is similar in concept to ``make
    586                -n''.
    587 
    588      -O obj    Create an appropriate transform macro for MAKEOBJDIR that will
    589                place the built object files under obj.  For instance, a set-
    590                ting of /usr/obj will place build-time files under
    591                /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, and so forth.
    592                Unsets MAKEOBJDIRPREFIX.
    593 
    594      -o        Set the value of MKOBJDIRS to ``no''.  Otherwise, it will be
    595                automatically set to ``yes'' (which is opposite to the default
    596                behaviour).
    597 
    598      -R rel    Set the value of RELEASEDIR to rel.
    599 
    600      -r        Remove the contents of DESTDIR and TOOLDIR before building
    601                (provides a clean starting point).  This will skip deleting
    602                DESTDIR if building on a native system to the root directory.
    603 
    604      -T tools  Set the value of TOOLDIR to tools.  If set, the bootstrap
    605                ``make'' will only be rebuilt as needed (when the source files
    606                for make(1) change).
    607 
    608      -U        Set MKUNPRIVED=yes.
    609 
    610      -u        Set MKUPDATE=yes.
    611 
    612      -V var=[value]
    613                Set the environment variable var to an optional value.  This is
    614                propagated to the nbmake wrapper.
    615 
    616      -w wrapper
    617                Create the nbmake wrapper script (see below) in a custom loca-
    618                tion, specified by wrapper.  This allows, for instance, to
    619                place the wrapper in PATH automatically.  Note that wrapper is
    620                the full name of the file, not just a directory name.
    621 
    622      -Z var    Unset ("zap") the environment variable var.  This is propagated
    623                to the nbmake wrapper.
    624 
    625    The "nbmake-MACHINE" wrapper script
    626      If using the build.sh script to build NetBSD, a nbmake-MACHINE script
    627      will be created in TOOLDIR/bin upon the first build to assist in building
    628      subtrees on a cross-compile host.
    629 
    630      nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
    631      the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with sev-
    632      eral key variables pre-set, including MACHINE, MACHINE_ARCH, and TOOLDIR.
    633      build.sh will also set variables specified with -V, and unset variables
    634      specified with -Z.
    635 
    636      This script can be symlinked into a directory listed in PATH, or called
    637      with an absolute path.
    638 
    639 EXAMPLES
    640      1.   % ./build.sh tools kernel=GENERIC
    641 
    642           Build a new toolchain, and use the new toolchain to configure and
    643           build a new GENERIC kernel.
    644 
    645      2.   % ./build.sh -U distribution
    646 
    647           Using unprivileged mode, build a complete distribution to a DESTDIR
    648           directory that build.sh selects (and will display).
    649 
    650      3.   # ./build.sh -U install=/
    651 
    652           As root, install to / the distribution that was built by example 2.
    653           Even though this is run as root, -U is required so that the permis-
    654           sions stored in DESTDIR/METALOG are correctly applied to the files
    655           as they're copied to /.
    656 
    657      4.   % ./build.sh -U -u release
    658 
    659           Using unprivileged mode, build a complete release to DESTDIR and
    660           RELEASEDIR directories that build.sh selects (and will display).
    661           MKUPDATE=yes (-u) is set to prevent the ``make cleandir'', so that
    662           if this is run after example 2, it doesn't need to redo that portion
    663           of the release build.
    664 
    665 OBSOLETE VARIABLES
    666      NBUILDJOBS  Use the make(1) option -j, instead.
    667 
    668      USE_NEW_TOOLCHAIN
    669                  The new toolchain is now the default.  To disable, use
    670                  TOOLCHAIN_MISSING=yes.
    671 
    672 SEE ALSO
    673      make(1), hier(7), release(7)
    674 
    675 HISTORY
    676      The build.sh based build scheme was introduced for NetBSD 1.6 as
    677      USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.
    678 
    679 BUGS
    680      A few platforms are not yet using this build system.
    681 
    682 NetBSD                         October 25, 2003                         NetBSD
    683