Home | History | Annotate | Line # | Download | only in src
      1 BUILDING(8)                 System Manager's Manual                BUILDING(8)
      2 
      3 NAME
      4      BUILDING - Procedure for building NetBSD from source code.
      5 
      6 REQUIREMENTS
      7      NetBSD is designed to be buildable on most POSIX-compliant host systems.
      8      The basic build procedure is the same whether compiling natively (on the
      9      same NetBSD architecture) or cross compiling (on another architecture or
     10      OS).
     11 
     12      This source tree contains a special subtree, "tools", which uses the host
     13      system to create a build toolchain for the target architecture.  The host
     14      system must have at least C and C++ compilers in order to create the
     15      toolchain (make is not required); all other tools are created as part of
     16      the NetBSD build process.  (See the environment variables section below
     17      if you need to override or manually select your compilers.)
     18 
     19 FILES
     20    Source tree layout
     21      doc/BUILDING.mdoc
     22                     This document (in -mdoc troff format; the original copy).
     23 
     24      BUILDING       This document (in plaintext).
     25 
     26      tools/compat/README
     27                     Special notes for cross-hosting a NetBSD build on non-
     28                     NetBSD platforms.
     29 
     30      Makefile       The main Makefile for NetBSD; should only be run for
     31                     native builds with an appropriately up-to-date version of
     32                     NetBSD make(1).  (For building from out-of-date systems or
     33                     on a non-native host, see the build.sh shell script.)
     34 
     35      UPDATING       Special notes for updating from an earlier revision of
     36                     NetBSD.  It is important to read this file before every
     37                     build of an updated source tree.
     38 
     39      build.sh       Bourne-compatible shell script used for building the host
     40                     build tools and the NetBSD system from scratch.  Can be
     41                     used for both native and cross builds, and should be used
     42                     instead of make(1) for any source tree that is updated and
     43                     recompiled regularly.
     44 
     45      crypto/dist/, dist/, gnu/dist/
     46                     Sources imported verbatim from third parties, without
     47                     mangling the existing build structure.  Other source trees
     48                     in bin through usr.sbin use the NetBSD make(1) "reachover"
     49                     Makefile semantics when building these programs for a
     50                     native host.
     51 
     52      external, sys/external
     53                     Sources and build infrastructure for components imported
     54                     (mostly) unchanged from upstream maintainers, sorted by
     55                     applicable license.  This is (slowly) replacing the
     56                     crypto/dist, dist, and gnu/dist directories.
     57 
     58      distrib/, etc/
     59                     Sources for items used when making a full release
     60                     snapshot, such as files installed in DESTDIR/etc on the
     61                     destination system, boot media, and release notes.
     62 
     63      tests/, regress/
     64                     Regression test harness.  Can be cross-compiled, but only
     65                     run natively.  tests/ uses the atf(7) test framework;
     66                     regress/ contains older tests that have not yet been
     67                     migrated to atf(7).
     68 
     69      sys/           NetBSD kernel sources.
     70 
     71      tools/         "Reachover" build structure for the host build tools.
     72                     This has a special method of determining out-of-date
     73                     status.
     74 
     75      bin/ ... usr.sbin/
     76                     Sources to the NetBSD userland (non-kernel) programs.  If
     77                     any of these directories are missing, they will be skipped
     78                     during the build.
     79 
     80      external/mit/xorg/
     81                     "Reachover" build structure for modular Xorg; the source
     82                     is in X11SRCDIR.
     83 
     84      extsrc/        "Reachover" build structure for externally added programs
     85                     and libraries; the source is in EXTSRCSRCDIR.
     86 
     87    Build tree layout
     88      The NetBSD build tree is described in hier(7), and the release layout is
     89      described in release(7).
     90 
     91 CONFIGURATION
     92    Environment variables
     93      Several environment variables control the behaviour of NetBSD builds.
     94 
     95      HOST_SH           Path name to a shell available on the host system and
     96                        suitable for use during the build.  The NetBSD build
     97                        system requires a modern Bourne-like shell with POSIX-
     98                        compliant features, and also requires support for the
     99                        "local" keyword to declare local variables in shell
    100                        functions (which is a widely-implemented but non-
    101                        standardised feature).
    102 
    103                        Depending on the host system, a suitable shell may be
    104                        /bin/sh, /usr/xpg4/bin/sh, /bin/ksh (provided it is a
    105                        variant of ksh that supports the "local" keyword, such
    106                        as ksh88, but not ksh93), or /usr/local/bin/bash.
    107 
    108                        Most parts of the build require HOST_SH to be an
    109                        absolute path; however, build.sh allows it to be a
    110                        simple command name, which will be converted to an
    111                        absolute path by searching the PATH.
    112 
    113      HOST_CC           Path name to C compiler used to create the toolchain.
    114 
    115      HOST_CXX          Path name to C++ compiler used to create the toolchain.
    116 
    117      MACHINE           Machine type, e.g., "macppc".
    118 
    119      MACHINE_ARCH      Machine architecture, e.g., "powerpc".
    120 
    121      MAKE              Path name to invoke make(1) as.
    122 
    123      MAKEFLAGS         Flags to invoke make(1) with.  Note that build.sh
    124                        ignores the value of MAKEFLAGS passed in the
    125                        environment, but allows MAKEFLAGS to be set via the -V
    126                        option.
    127 
    128      MAKEOBJDIR        Directory to use as the .OBJDIR for the current
    129                        directory.  The value is subjected to variable
    130                        expansion by make(1).  Typical usage is to set this
    131                        variable to a value involving the use of
    132                        `${.CURDIR:S...}' or `${.CURDIR:C...}', to derive the
    133                        value of .OBJDIR from the value of .CURDIR.  Used only
    134                        if MAKEOBJDIRPREFIX is not defined.  MAKEOBJDIR can be
    135                        provided only in the environment or via the -O flag of
    136                        build.sh; it cannot usefully be set inside a Makefile,
    137                        including mk.conf or ${MAKECONF}.
    138 
    139      MAKEOBJDIRPREFIX  Top level directory of the object directory tree.  The
    140                        value is subjected to variable expansion by make(1).
    141                        build.sh will create the ${MAKEOBJDIRPREFIX} directory
    142                        if necessary, but if make(1) is used without build.sh,
    143                        then rules in <bsd.obj.mk> will abort the build if the
    144                        ${MAKEOBJDIRPREFIX} directory does not exist.  If the
    145                        value is defined and valid, then
    146                        ${MAKEOBJDIRPREFIX}/${.CURDIR} is used as the .OBJDIR
    147                        for the current directory.  The current directory may
    148                        be read only.  MAKEOBJDIRPREFIX can be provided only in
    149                        the environment or via the -M flag of build.sh; it
    150                        cannot usefully be set inside a Makefile, including
    151                        mk.conf or ${MAKECONF}.
    152 
    153    "make" variables
    154      Several variables control the behavior of NetBSD builds.  Unless
    155      otherwise specified, these variables may be set in either the process
    156      environment or the make(1) configuration file specified by MAKECONF.
    157 
    158      BUILDID     Identifier for the build.  If set, this should be a short
    159                  string that is suitable for use as part of a file or
    160                  directory name.  The identifier will be appended to object
    161                  directory names, and can be consulted in the make(1)
    162                  configuration file in order to set additional build
    163                  parameters, such as compiler flags.  It will also be used as
    164                  part of the kernel version string, which can be printed by
    165                  "uname -v".
    166 
    167                  Default: Unset.
    168 
    169      BUILDINFO   This may be a multi-line string containing information about
    170                  the build.  This will appear in DESTDIR/etc/release, and it
    171                  will be stored in the buildinfo variable in any kernels that
    172                  are built.  When such kernels are booted, the sysctl(7)
    173                  kern.buildinfo variable will report this value.  The string
    174                  may contain backslash escape sequences, such as "\\"
    175                  (representing a backslash character) and "\n" (representing a
    176                  newline).
    177 
    178                  Default: Unset.
    179 
    180      BUILDSEED   GCC uses random numbers when compiling C++ code.  This
    181                  variable seeds the gcc random number generator using the
    182                  -frandom-seed flag with this value.  By default, it is set to
    183                  NetBSD-(majorversion).  Using a fixed value causes C++
    184                  binaries to be the same when built from the same sources,
    185                  resulting in identical (reproducible) builds.  Additional
    186                  information is available in the GCC documentation of
    187                  -frandom-seed.
    188 
    189      DESTDIR     Directory to contain the built NetBSD system.  If set,
    190                  special options are passed to the compilation tools to
    191                  prevent their default use of the host system's /usr/include,
    192                  /usr/lib, and so forth.  This pathname must be an absolute
    193                  path, and should not end with a slash (/) character.  (For
    194                  installation into the system's root directory, set DESTDIR to
    195                  an empty string, not to "/").  The directory must reside on a
    196                  file system which supports long file names and hard links.
    197 
    198                  Default: Empty string if USETOOLS is "yes"; unset otherwise.
    199 
    200                  Note: build.sh will provide a default of destdir.MACHINE (in
    201                  the top-level .OBJDIR) unless run in `expert' mode.
    202 
    203      EXTSRCSRCDIR
    204                  Directory containing sources of externally added programs and
    205                  libraries.  If specified, must be an absolute path.
    206 
    207                  Default: NETBSDRCDIR/../extsrc, if that exists; otherwise
    208                  /usr/extsrc.
    209 
    210      MAKECONF    The name of the make(1) configuration file.  Only settable in
    211                  the process environment.
    212 
    213                  Default: "/etc/mk.conf"
    214 
    215      MAKEVERBOSE
    216                  Level of verbosity of status messages.  Supported values:
    217 
    218                  0    No descriptive messages or commands executed by make(1)
    219                       are shown.
    220 
    221                  1    Brief messages are shown describing what is being done,
    222                       but the actual commands executed by make(1) are not
    223                       displayed.
    224 
    225                  2    Descriptive messages are shown as above (prefixed with a
    226                       `#'), and ordinary commands performed by make(1) are
    227                       displayed.
    228 
    229                  3    In addition to the above, all commands performed by
    230                       make(1) are displayed, even if they would ordinarily
    231                       have been hidden through use of the "@" prefix in the
    232                       relevant makefile.
    233 
    234                  4    In addition to the above, commands executed by make(1)
    235                       are traced through use of the sh(1) "-x" flag.
    236 
    237                  Default: 2
    238 
    239      MKCATPAGES  Can be set to "yes" or "no".  Indicates whether preformatted
    240                  plaintext manual pages will be created during a build.
    241 
    242                  Default: "no"
    243 
    244      MKCROSSGDB  Can be set to "yes" or "no".  Create a cross-gdb as a host
    245                  tool.
    246 
    247                  Default: "no"
    248 
    249      MKDEBUG     Can be set to "yes" or "no".  Indicates whether debug
    250                  information should be generated for all userland binaries
    251                  compiled.  The result is collected as an additional debug.tgz
    252                  and xdebug.tgz set and installed in /usr/libdata/debug.
    253 
    254                  Default: "no"
    255 
    256      MKDEBUGLIB  Can be set to "yes" or "no".  Indicates whether debug
    257                  information (see MKDEBUG) should also be generated for all
    258                  libraries build.
    259 
    260                  Default: "no"
    261 
    262      MKDOC       Can be set to "yes" or "no".  Indicates whether system
    263                  documentation destined for DESTDIR/usr/share/doc will be
    264                  installed during a build.
    265 
    266                  Default: "yes"
    267 
    268      MKEXTSRC    Can be set to "yes" or "no".  Indicates whether extsrc is
    269                  built from EXTSRCSRCDIR.
    270 
    271                  Default: "no"
    272 
    273      MKHTML      Can be set to "yes" or "no".  Indicates whether preformatted
    274                  HTML manual pages will be built and installed
    275 
    276                  Default: "yes"
    277 
    278      MKHOSTOBJ   Can be set to "yes" or "no".  If set to "yes", then for
    279                  programs intended to be run on the compile host, the name,
    280                  release, and architecture of the host operating system will
    281                  be suffixed to the name of the object directory created by
    282                  "make obj".  (This allows multiple host systems to compile
    283                  NetBSD for a single target.)  If set to "no", then programs
    284                  built to be run on the compile host will use the same object
    285                  directory names as programs built to be run on the target.
    286 
    287                  Default: "no"
    288 
    289      MKINFO      Can be set to "yes" or "no".  Indicates whether GNU Info
    290                  files, used for the documentation for most of the compilation
    291                  tools, will be created and installed during a build.
    292 
    293                  Default: "yes"
    294 
    295      MKKDEBUG    Can be set to "yes" or "no".  Force generation of full-debug
    296                  symbol versions of all kernels compiled.  Alongside of the
    297                  netbsd kernel file, an unstripped version netbsd.gdb is
    298                  created.  This is useful if a cross-gdb is built as well (see
    299                  MKCROSSGDB).
    300 
    301                  Default: "no"
    302 
    303      MKKMOD      Can be set to "yes" or "no".  Indicates whether kernel
    304                  modules are built and installed.
    305 
    306                  Default: "yes"
    307 
    308      MKLINT      Can be set to "yes" or "no".  Indicates whether lint(1) will
    309                  be run against portions of the NetBSD source code during the
    310                  build, and whether lint libraries will be installed into
    311                  DESTDIR/usr/libdata/lint.
    312 
    313                  Default: "yes"
    314 
    315      MKMAN       Can be set to "yes" or "no".  Indicates whether manual pages
    316                  will be installed during a build.
    317 
    318                  Default: "yes"
    319 
    320      MKNLS       Can be set to "yes" or "no".  Indicates whether Native
    321                  Language System locale zone files will be compiled and
    322                  installed during a build.
    323 
    324                  Default: "yes"
    325 
    326      MKOBJ       Can be set to "yes" or "no".  Indicates whether object
    327                  directories will be created when running "make obj".  If set
    328                  to "no", then all built files will be located inside the
    329                  regular source tree.
    330 
    331                  Default: "yes"
    332 
    333                  Note that setting MKOBJ to "no" is not recommended and may
    334                  cause problems when updating the tree with cvs(1).
    335 
    336      MKPIC       Can be set to "yes" or "no".  Indicates whether shared
    337                  objects and libraries will be created and installed during a
    338                  build.  If set to "no", the entire built system will be
    339                  statically linked.
    340 
    341                  Default: Platform dependent.  As of this writing, all
    342                  platforms except sh3 default to "yes".
    343 
    344      MKPICINSTALL
    345                  Can be set to "yes" or "no".  Indicates whether the ar(1)
    346                  format libraries (lib*_pic.a), used to generate shared
    347                  libraries, are installed during a build.
    348 
    349                  Default: "yes"
    350 
    351      MKPROFILE   Can be set to "yes" or "no".  Indicates whether profiled
    352                  libraries (lib*_p.a) will be built and installed during a
    353                  build.
    354 
    355                  Default: "yes"; however, some platforms turn off MKPROFILE by
    356                  default at times due to toolchain problems with profiled
    357                  code.
    358 
    359      MKREPRO     Can be set to "yes" or "no".  Create reproducible builds.
    360                  This enables different switches to make two builds from the
    361                  same source tree result in the same build results.
    362 
    363                  Default: "no" This may be set to "yes" by giving build.sh the
    364                  -P option.
    365 
    366      MKREPRO_TIMESTAMP
    367                  Unix timestamp.  When MKREPRO is set, the timestamp of all
    368                  files in the sets will be set to this value.
    369 
    370                  Default: Unset.  This may be set automatically to the latest
    371                  source tree timestamp using cvslatest(1) by giving build.sh
    372                  the -P option.
    373 
    374      MKSHARE     Can be set to "yes" or "no".  Indicates whether files
    375                  destined to reside in DESTDIR/usr/share will be built and
    376                  installed during a build.  If set to "no", then all of
    377                  MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to
    378                  "no" unconditionally.
    379 
    380                  Default: "yes"
    381 
    382      MKSTRIPIDENT
    383                  Can be set to "yes" or "no".  Indicates whether RCS IDs, for
    384                  use with ident(1), should be stripped from program binaries
    385                  and shared libraries.
    386 
    387                  Default: "no"
    388 
    389      MKSTRIPSYM  Can be set to "yes" or "no".  Indicates whether all local
    390                  symbols should be stripped from shared libraries.  If "yes",
    391                  strip all local symbols from shared libraries; the affect is
    392                  equivalent to the -x option of ld(1).  If "no", strip only
    393                  temporary local symbols; the affect is equivalent to the -X
    394                  option of ld(1).  Keeping non-temporary local symbols such as
    395                  static function names is useful on using DTrace for userland
    396                  libraries and getting a backtrace from a rump kernel loading
    397                  shared libraries.
    398 
    399                  Default: "yes"
    400 
    401      MKUNPRIVED  Can be set to "yes" or "no".  Indicates whether an
    402                  unprivileged install will occur.  The user, group,
    403                  permissions, and file flags, will not be set on the installed
    404                  items; instead the information will be appended to a file
    405                  called METALOG in DESTDIR.  The contents of METALOG are used
    406                  during the generation of the distribution tar files to ensure
    407                  that the appropriate file ownership is stored.
    408 
    409                  Default: "no"
    410 
    411      MKUPDATE    Can be set to "yes" or "no".  Indicates whether all install
    412                  operations intended to write to DESTDIR will compare file
    413                  timestamps before installing, and skip the install phase if
    414                  the destination files are up-to-date.  This also has
    415                  implications on full builds (see next subsection).
    416 
    417                  Default: "no"
    418 
    419      MKX11       Can be set to "yes" or "no".  Indicates whether X11 is built
    420                  from X11SRCDIR.
    421 
    422                  Default: "no"
    423 
    424      TOOLDIR     Directory to hold the host tools, once built.  If specified,
    425                  must be an absolute path.  This directory should be unique to
    426                  a given host system and NetBSD source tree.  (However,
    427                  multiple targets may share the same TOOLDIR; the target-
    428                  dependent files have unique names.)  If unset, a default
    429                  based on the uname(1) information of the host platform will
    430                  be created in the .OBJDIR of src.
    431 
    432                  Default: Unset.
    433 
    434      USETOOLS    Indicates whether the tools specified by TOOLDIR should be
    435                  used as part of a build in progress.  Must be set to "yes" if
    436                  cross-compiling.
    437 
    438                  yes    Use the tools from TOOLDIR.
    439 
    440                  no     Do not use the tools from TOOLDIR, but refuse to build
    441                         native compilation tool components that are version-
    442                         specific for that tool.
    443 
    444                  never  Do not use the tools from TOOLDIR, even when building
    445                         native tool components.  This is similar to the
    446                         traditional NetBSD build method, but does not verify
    447                         that the compilation tools in use are up-to-date
    448                         enough in order to build the tree successfully.  This
    449                         may cause build or runtime problems when building the
    450                         whole NetBSD source tree.
    451 
    452                  Default: "yes", unless TOOLCHAIN_MISSING is set to "yes".
    453 
    454                  USETOOLS is also set to "no" when using <bsd.*.mk> outside
    455                  the NetBSD source tree.
    456 
    457      X11SRCDIR   Directory containing the modular Xorg source.  If specified,
    458                  must be an absolute path.  The main modular Xorg source is
    459                  found in X11SRCDIR/external/mit.
    460 
    461                  Default: NETBSDRCDIR/../xsrc, if that exists; otherwise
    462                  /usr/xsrc.
    463 
    464    "make" variables for full builds
    465      These variables only affect the top level "Makefile" and do not affect
    466      manually building subtrees of the NetBSD source code.
    467 
    468      INSTALLWORLDDIR  Location for the "make installworld" target to install
    469                       to.  If specified, must be an absolute path.
    470 
    471                       Default: "/"
    472 
    473      MKOBJDIRS        Can be set to "yes" or "no".  Indicates whether object
    474                       directories will be created automatically (via a "make
    475                       obj" pass) at the start of a build.
    476 
    477                       Default: "no"
    478 
    479                       If using build.sh, the default is "yes".  This may be
    480                       set back to "no" by giving build.sh the -o option.
    481 
    482      MKUPDATE         Can be set to "yes" or "no".  If set, then in addition
    483                       to the effects described for MKUPDATE=yes above, this
    484                       implies the effects of NOCLEANDIR (i.e., "make cleandir"
    485                       is avoided).
    486 
    487                       Default: "no"
    488 
    489                       If using build.sh, this may be set by giving the -u
    490                       option.
    491 
    492      NBUILDJOBS       Now obsolete.  Use the make(1) option -j, instead.  See
    493                       below.
    494 
    495                       Default: Unset.
    496 
    497      NOCLEANDIR       If set, avoids the "make cleandir" phase of a full
    498                       build.  This has the effect of allowing only changed
    499                       files in a source tree to be recompiled.  This can speed
    500                       up builds when updating only a few files in the tree.
    501 
    502                       Default: Unset.
    503 
    504                       See also MKUPDATE.
    505 
    506      NODISTRIBDIRS    If set, avoids the "make distrib-dirs" phase of a full
    507                       build.  This skips running mtree(8) on DESTDIR, useful
    508                       on systems where building as an unprivileged user, or
    509                       where it is known that the system-wide mtree files have
    510                       not changed.
    511 
    512                       Default: Unset.
    513 
    514      NOINCLUDES       If set, avoids the "make includes" phase of a full
    515                       build.  This has the effect of preventing make(1) from
    516                       thinking that some programs are out-of-date simply
    517                       because the system include files have changed.  However,
    518                       this option should not be used when updating the entire
    519                       NetBSD source tree arbitrarily; it is suggested to use
    520                       MKUPDATE=yes instead in that case.
    521 
    522                       Default: Unset.
    523 
    524      RELEASEDIR       If set, specifies the directory to which a release(7)
    525                       layout will be written at the end of a "make release".
    526                       If specified, must be an absolute path.
    527 
    528                       Default: Unset.
    529 
    530                       Note: build.sh will provide a default of releasedir (in
    531                       the top-level .OBJDIR) unless run in `expert' mode.
    532 
    533 BUILDING
    534    "make" command line options
    535      This is not a summary of all the options available to make(1); only the
    536      options used most frequently with NetBSD builds are listed here.
    537 
    538      -j njob    Run up to njob make(1) subjobs in parallel.  Makefiles should
    539                 use .WAIT or have explicit dependencies as necessary to
    540                 enforce build ordering.
    541 
    542      -m dir     Specify the default directory for searching for system
    543                 Makefile segments, mainly the <bsd.*.mk> files.  When building
    544                 any full NetBSD source tree, this should be set to the
    545                 "share/mk" directory in the source tree.  This is set
    546                 automatically when building from the top level, or when using
    547                 build.sh.
    548 
    549      -n         Display the commands that would have been executed, but do not
    550                 actually execute them.  This will still cause recursion to
    551                 take place.
    552 
    553      -V var     Print make(1)'s idea of the value of var.  Does not build any
    554                 targets.
    555 
    556      var=value  Set the variable var to value, overriding any setting
    557                 specified by the process environment, the MAKECONF
    558                 configuration file, or the system Makefile segments.
    559 
    560    "make" targets
    561      These default targets may be built by running make(1) in any subtree of
    562      the NetBSD source code.  It is recommended that none of these be used
    563      from the top level Makefile; as a specific exception, "make obj" and
    564      "make cleandir" are useful in that context.
    565 
    566      all        Build programs, libraries, and preformatted documentation.
    567 
    568      clean      Remove program and library object code files.
    569 
    570      cleandir   Same as clean, but also remove preformatted documentation,
    571                 dependency files generated by "make depend", and any other
    572                 files known to be created at build time.
    573 
    574      depend     Create dependency files (.depend) containing more detailed
    575                 information about the dependencies of source code on header
    576                 files.  Allows programs to be recompiled automatically when a
    577                 dependency changes.
    578 
    579      dependall  Does a "make depend" immediately followed by a "make all".
    580                 This improves cache locality of the build since both passes
    581                 read the source files in their entirety.
    582 
    583      distclean  Synonym for cleandir.
    584 
    585      includes   Build and install system header files.  Typically needed
    586                 before any system libraries or programs can be built.
    587 
    588      install    Install programs, libraries, and documentation into DESTDIR.
    589                 Few files will be installed to DESTDIR/dev, DESTDIR/etc,
    590                 DESTDIR/root or DESTDIR/var in order to prevent user supplied
    591                 configuration data from being overwritten.
    592 
    593      lint       Run lint(1) against the C source code, where appropriate, and
    594                 generate system-installed lint libraries.
    595 
    596      obj        Create object directories to be used for built files, instead
    597                 of building directly in the source tree.
    598 
    599      tags       Create ctags(1) searchable function lists usable by the ex(1)
    600                 and vi(1) text editors.
    601 
    602    "make" targets for the top level
    603      Additional make(1) targets are usable specifically from the top source
    604      level to facilitate building the entire NetBSD source tree.
    605 
    606      build         Build the entire NetBSD system (except the kernel).  This
    607                    orders portions of the source tree such that prerequisites
    608                    will be built in the proper order.
    609 
    610      distribution  Do a "make build", and then install a full distribution
    611                    (which does not include a kernel) into DESTDIR, including
    612                    files in DESTDIR/dev, DESTDIR/etc, DESTDIR/root and
    613                    DESTDIR/var.
    614 
    615      buildworld    As per "make distribution", except that it ensures that
    616                    DESTDIR is not the root directory.
    617 
    618      installworld  Install the distribution from DESTDIR to INSTALLWORLDDIR,
    619                    which defaults to the root directory.  Ensures that
    620                    INSTALLWORLDDIR is not the root directory if cross
    621                    compiling.
    622 
    623                    The INSTALLSETS environment variable may be set to a space-
    624                    separated list of distribution sets to be installed.  By
    625                    default, all sets except "etc" and "xetc" are installed, so
    626                    most files in INSTALLWORLDDIR/etc will not be installed or
    627                    modified.
    628 
    629                    Note: Before performing this operation with
    630                    INSTALLWORLDDIR=/, it is highly recommended that you
    631                    upgrade your kernel and reboot.  After performing this
    632                    operation, it is recommended that you use etcupdate(8) to
    633                    update files in INSTALLWORLDDIR/etc, and postinstall(8) to
    634                    check for or fix inconsistencies.
    635 
    636      sets          Create distribution sets from DESTDIR into
    637                    RELEASEDIR/RELEASEMACHINEDIR/binary/sets.  Should be run
    638                    after "make distribution", as "make build" alone does not
    639                    install all of the required files.
    640 
    641      sourcesets    Create source sets of the source tree into
    642                    RELEASEDIR/source/sets.
    643 
    644      syspkgs       Create syspkgs from DESTDIR into
    645                    RELEASEDIR/RELEASEMACHINEDIR/binary/syspkgs.  Should be run
    646                    after "make distribution", as "make build" alone does not
    647                    install all of the required files.
    648 
    649      release       Do a "make distribution", build kernels, distribution
    650                    media, and install sets (this as per "make sets"), and then
    651                    package the system into a standard release layout as
    652                    described by release(7).  This requires that RELEASEDIR be
    653                    set (see above).
    654 
    655      iso-image     Create a NetBSD installation CD-ROM image in the
    656                    RELEASEDIR/images directory.  The CD-ROM file system will
    657                    have a layout as described in release(7).
    658 
    659                    For most machine types, the CD-ROM will be bootable, and
    660                    will automatically run the sysinst(8) menu-based
    661                    installation program, which can be used to install or
    662                    upgrade a NetBSD system.  Bootable CD-ROMs also contain
    663                    tools that may be useful in repairing a damaged NetBSD
    664                    installation.
    665 
    666                    Before "make iso-image" is attempted, RELEASEDIR must be
    667                    populated by "make release" or equivalent.
    668 
    669                    Note that other, smaller, CD-ROM images may be created in
    670                    the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom
    671                    directory by "make release".  These smaller images usually
    672                    contain the same tools as the larger images in
    673                    RELEASEDIR/images, but do not contain additional content
    674                    such as the distribution sets.
    675 
    676                    Note that the mac68k port still uses an older method of
    677                    creating CD-ROM images.  This requires the mkisofs(1)
    678                    utility, which is not part of NetBSD, but which can be
    679                    installed from pkgsrc/sysutils/cdrtools.
    680 
    681      iso-image-source
    682                    Create a NetBSD installation CD-ROM image in the
    683                    RELEASEDIR/images directory.  The CD-ROM file system will
    684                    have a layout as described in release(7).  It will have top
    685                    level directories for the machine type and source.
    686 
    687                    For most machine types, the CD-ROM will be bootable, and
    688                    will automatically run the sysinst(8) menu-based
    689                    installation program, which can be used to install or
    690                    upgrade a NetBSD system.  Bootable CD-ROMs also contain
    691                    tools that may be useful in repairing a damaged NetBSD
    692                    installation.
    693 
    694                    Before "make iso-image-source" is attempted, RELEASEDIR
    695                    must be populated by "make sourcesets release" or
    696                    equivalent.
    697 
    698                    Note that other, smaller, CD-ROM images may be created in
    699                    the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom
    700                    directory by "make release".  These smaller images usually
    701                    contain the same tools as the larger images in
    702                    RELEASEDIR/images, but do not contain additional content
    703                    such as the distribution sets.
    704 
    705                    Note that the mac68k port still uses an older method of
    706                    creating CD-ROM images.  This requires the mkisofs(1)
    707                    utility, which is not part of NetBSD, but which can be
    708                    installed from pkgsrc/sysutils/cdrtools.
    709 
    710      install-image
    711                    Create a bootable NetBSD installation disk image in the
    712                    RELEASEDIR/images directory.  The installation disk image
    713                    is suitable for copying to bootable USB flash memory
    714                    sticks, etc., for machines which are able to boot from such
    715                    devices.  The file system in the bootable disk image will
    716                    have a layout as described in release(7).
    717 
    718                    The installation image is bootable, and will automatically
    719                    run the sysinst(8) menu-based installation program, which
    720                    can be used to install or upgrade a NetBSD system.  The
    721                    image also contains tools that may be useful in repairing a
    722                    damaged NetBSD installation.
    723 
    724                    Before "make install-image" is attempted, RELEASEDIR must
    725                    be populated by "make release" or equivalent.  The build
    726                    must have been performed with MKUNPRIVED=yes because "make
    727                    install-image" relies on information in DESTDIR/METALOG.
    728 
    729      live-image    Create NetBSD live images in the RELEASEDIR/images
    730                    directory.  The live image contains all necessary files to
    731                    boot NetBSD up to multi-user mode, including all files
    732                    which should be extracted during installation, NetBSD
    733                    disklabel, bootloaders, etc.
    734 
    735                    The live image is suitable for use as a disk image in
    736                    virtual machine environments such as QEMU, and also useful
    737                    to boot NetBSD from a USB flash memory stick on a real
    738                    machine, without the need for installation.
    739 
    740                    Before "make live-image" is attempted, RELEASEDIR must be
    741                    populated by "make release" or equivalent.  The build must
    742                    have been performed with MKUNPRIVED=yes because "make
    743                    install-image" relies on information in DESTDIR/METALOG.
    744 
    745      regression-tests
    746                    Can only be run after building the regression tests in the
    747                    directory "regress".  Runs those compiled regression tests
    748                    on the local host.  Note that most tests are now managed
    749                    instead using atf(7); this target should probably run those
    750                    as well but currently does not.
    751 
    752    The "build.sh" script
    753      This script file is a shell script designed to build the entire NetBSD
    754      system on any host with a suitable modern shell and some common
    755      utilities.  The required shell features are described under the HOST_SH
    756      variable.
    757 
    758      If a host system's default shell does support the required features, then
    759      we suggest that you explicitly specify a suitable shell using a command
    760      like
    761 
    762            /path/to/suitable/shell build.sh [options]
    763 
    764      The above command will usually enable build.sh to automatically set
    765      HOST_SH=/path/to/suitable/shell, but if that fails, then the following
    766      set of commands may be used instead:
    767 
    768            HOST_SH=/path/to/suitable/shell
    769            export HOST_SH
    770            ${HOST_SH} build.sh [options]
    771 
    772      If build.sh detects that it is being executed under an unsuitable shell,
    773      it attempts to exec a suitable shell instead, or prints an error message.
    774      If HOST_SH is not set explicitly, then build.sh sets a default using
    775      heuristics dependent on the host platform, or from the shell under which
    776      build.sh is executed (if that can be determined), or using the first copy
    777      of sh found in PATH.
    778 
    779      All cross-compile builds, and most native builds, of the entire system
    780      should make use of build.sh rather than just running "make".  This way,
    781      the make(1) program will be bootstrapped properly, in case the host
    782      system has an older or incompatible "make" program.
    783 
    784      When compiling the entire system via build.sh, many make(1) variables are
    785      set for you in order to help encapsulate the build process.  In the list
    786      of options below, variables that are automatically set by build.sh are
    787      noted where applicable.
    788 
    789      The following operations are supported by build.sh:
    790 
    791      build         Build the system as per "make build".  Before the main part
    792                    of the build commences, this command runs the obj operation
    793                    (unless the -o option is given), "make cleandir" (unless
    794                    the -u option is given), and the tools operation.
    795 
    796      distribution  Build a full distribution as per "make distribution".  This
    797                    command first runs the build operation.
    798 
    799      release       Build a full release as per "make release".  This command
    800                    first runs the distribution operation.
    801 
    802      makewrapper   Create the nbmake-MACHINE wrapper.  This operation is
    803                    automatically performed for any of the other operations.
    804 
    805      cleandir      Perform "make cleandir".
    806 
    807      obj           Perform "make obj".
    808 
    809      tools         Build and install the host tools from src/tools.  This
    810                    command will first run "make obj" and "make cleandir" in
    811                    the tools subdirectory unless the -o or -u options
    812                    (respectively) are given.
    813 
    814      install=idir  Install the contents of DESTDIR to idir, using "make
    815                    installworld".  Note that files that are part of the "etc"
    816                    or "xetc" sets will not be installed, unless overridden by
    817                    the INSTALLSETS environment variable.
    818 
    819      kernel=kconf  Build a new kernel.  The kconf argument is the name of a
    820                    configuration file suitable for use by config(1).  If kconf
    821                    does not contain any `/' characters, the configuration file
    822                    is expected to be found in the KERNCONFDIR directory, which
    823                    is typically sys/arch/MACHINE/conf.  The new kernel will be
    824                    built in a subdirectory of KERNOBJDIR, which is typically
    825                    sys/arch/MACHINE/compile or an associated object directory.
    826 
    827                    This command does not imply the tools command; run the
    828                    tools command first unless it is certain that the tools
    829                    already exist and are up to date.
    830 
    831                    This command will run "make cleandir" on the kernel in
    832                    question first unless the -u option is given.
    833 
    834      kernel.gdb=kconf
    835                    Build a new kernel with debug information.  Similar to the
    836                    above kernel=kconf operation, but creates a netbsd.gdb file
    837                    alongside of the kernel netbsd, which contains a full
    838                    symbol table and can be used for debugging (for example
    839                    with a cross-gdb built by MKCROSSGDB).
    840 
    841      kernels       This command will build all kernels defined in port
    842                    specific release build procedure.
    843 
    844                    This command internally calls the kernel=kconf operation
    845                    for each found kernel configuration file.
    846 
    847      modules       This command will build kernel modules and install them
    848                    into DESTDIR.
    849 
    850      releasekernel=kconf
    851                    Install a gzip(1)ed copy of the kernel previously built by
    852                    kernel=kconf into
    853                    RELEASEDIR/RELEASEMACHINEDIR/binary/kernel, usually as
    854                    netbsd-kconf.gz, although the "netbsd" prefix is determined
    855                    from the "config" directives in kconf.
    856 
    857      sets          Perform "make sets".
    858 
    859      sourcesets    Perform "make sourcesets".
    860 
    861      syspkgs       Perform "make syspkgs".
    862 
    863      iso-image     Perform "make iso-image".
    864 
    865      iso-image-source
    866                    Perform "make iso-image-source".
    867 
    868      install-image
    869                    Perform "make install-image".
    870 
    871      live-image    Perform "make live-image".
    872 
    873      list-arch     Prints a list of valid MACHINE and MACHINE_ARCH settings,
    874                    the default MACHINE_ARCH for each MACHINE, and aliases for
    875                    MACHINE/MACHINE_ARCH pairs, and then exits.  The -m or -a
    876                    options (or both) may be used to specify glob patterns that
    877                    will be used to narrow the list of results; for example,
    878                    "build.sh -m 'evm*' -a '*arm*' list-arch" will list all
    879                    known MACHINE/MACHINE_ARCH values in which either MACHINE
    880                    or ALIAS matches the pattern `evb*', and MACHINE_ARCH
    881                    matches the pattern `*arm*'.
    882 
    883      The following command line options alter the behaviour of the build.sh
    884      operations described above:
    885 
    886      -a arch   Set the value of MACHINE_ARCH to arch.  See the -m option for
    887                more information.
    888 
    889      -B buildid
    890                Set the value of BUILDID to buildid.  This will also append the
    891                build identifier to the name of the "make" wrapper script so
    892                that the resulting name is of the form
    893                "nbmake-MACHINE-BUILDID".
    894 
    895      -C cdextras
    896                Append cdextras to the CDEXTRA variable, which is a space-
    897                separated list of files or directories that will be added to
    898                the CD-ROM image that may be create by the "iso-image" or
    899                "iso-image-source" operations.  Files will be added to the root
    900                of the CD-ROM image, whereas directories will be copied
    901                recursively.  If relative paths are specified, they will be
    902                converted to absolute paths before being used.  Multiple paths
    903                may be specified via multiple -C options, or via a single
    904                option whose argument contains multiple space-separated paths.
    905 
    906      -D dest   Set the value of DESTDIR to dest.  If a relative path is
    907                specified, it will be converted to an absolute path before
    908                being used.
    909 
    910      -E        Set `expert' mode.  This overrides various sanity checks, and
    911                allows: DESTDIR does not have to be set to a non-root path for
    912                builds, and MKUNPRIVED=yes does not have to be set when
    913                building as a non-root user.
    914 
    915                Note: It is highly recommended that you know what you are doing
    916                when you use this option.
    917 
    918      -h        Print a help message.
    919 
    920      -j njob   Run up to njob make(1) subjobs in parallel; passed through to
    921                make(1).  If you see failures for reasons other than running
    922                out of memory while using build.sh with -j, please save
    923                complete build logs so the failures can be analyzed.
    924 
    925                To achieve the fastest builds, -j values between (1 + the
    926                number of CPUs) and (2 * the number of CPUs) are recommended.
    927                Use lower values on machines with limited memory or I/O
    928                bandwidth.
    929 
    930      -M obj    Set MAKEOBJDIRPREFIX to obj.  Unsets MAKEOBJDIR.  See "-O obj"
    931                for more information.
    932 
    933                For instance, if the source directory is /usr/src, a setting of
    934                "-M /usr/obj" will place build-time files under
    935                /usr/obj/usr/src/bin, /usr/obj/usr/src/lib,
    936                /usr/obj/usr/src/usr.bin, and so forth.
    937 
    938                If a relative path is specified, it will be converted to an
    939                absolute path before being used.  build.sh imposes the
    940                restriction that the argument to the -M option must not begin
    941                with a "$" (dollar sign) character; otherwise it would be too
    942                difficult to determine whether the value is an absolute or a
    943                relative path.  If the directory does not already exist,
    944                build.sh will create it.
    945 
    946      -m mach   Set the value of MACHINE to mach, unless the mach argument is
    947                an alias that refers to a MACHINE/MACHINE_ARCH pair, in which
    948                case both MACHINE and MACHINE_ARCH are set from the alias.
    949                Such aliases are interpreted entirely by build.sh; they are not
    950                used by any other part of the build system.  The MACHINE_ARCH
    951                setting implied by mach will override any value of MACHINE_ARCH
    952                in the process environment, but will not override a value set
    953                by the -a option.  All cross builds require -m, but if unset on
    954                a NetBSD host, the host's value of MACHINE will be detected and
    955                used automatically.
    956 
    957                See the list-arch operation for a way to get a list of valid
    958                MACHINE and MACHINE_ARCH settings.
    959 
    960      -N noiselevel
    961                Set the "noisyness" level of the build, by setting MAKEVERBOSE
    962                to noiselevel.
    963 
    964      -n        Show the commands that would be executed by build.sh, but do
    965                not make any changes.  This is similar in concept to "make -n".
    966 
    967      -O obj    Create an appropriate transform macro for MAKEOBJDIR that will
    968                place the built object files under obj.  Unsets
    969                MAKEOBJDIRPREFIX.
    970 
    971                For instance, a setting of "-O /usr/obj" will place build-time
    972                files under /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, and
    973                so forth.
    974 
    975                If a relative path is specified, it will be converted to an
    976                absolute path before being used.  build.sh imposes the
    977                restriction that the argument to the -O option must not contain
    978                a "$" (dollar sign) character.  If the directory does not
    979                already exist, build.sh will create it.
    980 
    981                In normal use, exactly one of the -M or -O options should be
    982                specified.  If neither -M nor -O is specified, then a default
    983                object directory will be chosen according to rules in
    984                <bsd.obj.mk>.  Relying on this default is not recommended
    985                because it is determined by complex rules that are influenced
    986                by the values of several variables and by the location of the
    987                source directory.
    988 
    989                Note that placing the obj directory location outside of the
    990                default source tree hierarchy makes it easier to manually clear
    991                out old files in the event the "make cleandir" operation is
    992                unable to do so.  (See CAVEATS below.)
    993 
    994                Note also that use of one of -M or -O is the only means of
    995                building multiple machine architecture userlands from the same
    996                source tree without cleaning between builds (in which case, one
    997                would specify distinct obj locations for each).
    998 
    999      -o        Set the value of MKOBJDIRS to "no".  Otherwise, it will be
   1000                automatically set to "yes".  This default is opposite to the
   1001                behaviour when not using build.sh.
   1002 
   1003      -R rel    Set the value of RELEASEDIR to rel.  If a relative path is
   1004                specified, it will be converted to an absolute path before
   1005                being used.
   1006 
   1007      -r        Remove the contents of DESTDIR and TOOLDIR before building
   1008                (provides a clean starting point).  This will skip deleting
   1009                DESTDIR if building on a native system to the root directory.
   1010 
   1011      -S seed   Change the value of BUILDSEED to seed.  This should rarely be
   1012                necessary.
   1013 
   1014      -T tools  Set the value of TOOLDIR to tools.  If a relative path is
   1015                specified, it will be converted to an absolute path before
   1016                being used.  If set, the bootstrap "make" will only be rebuilt
   1017                if the source files for make(1) have changed.
   1018 
   1019      -U        Set MKUNPRIVED=yes.
   1020 
   1021      -u        Set MKUPDATE=yes.
   1022 
   1023      -V var=[value]
   1024                Set the environment variable var to an optional value.  This is
   1025                propagated to the nbmake wrapper.
   1026 
   1027      -w wrapper
   1028                Create the nbmake wrapper script (see below) in a custom
   1029                location, specified by wrapper.  This allows, for instance, to
   1030                place the wrapper in PATH automatically.  Note that wrapper is
   1031                the full name of the file, not just a directory name.  If a
   1032                relative path is specified, it will be converted to an absolute
   1033                path before being used.
   1034 
   1035      -X x11src
   1036                Set the value of X11SRCDIR to x11src.  If a relative path is
   1037                specified, it will be converted to an absolute path before
   1038                being used.
   1039 
   1040      -x        Set MKX11=yes.
   1041 
   1042      -Y extsrcdir
   1043                Set the value of EXTSRCSRCDIR to extsrcdir.  If a relative path
   1044                is specified, it will be converted to an absolute path before
   1045                being used.
   1046 
   1047      -y        Set MKEXTSRC=yes.
   1048 
   1049      -Z var    Unset ("zap") the environment variable var.  This is propagated
   1050                to the nbmake wrapper.
   1051 
   1052    The "nbmake-MACHINE" wrapper script
   1053      If using the build.sh script to build NetBSD, a nbmake-MACHINE script
   1054      will be created in TOOLDIR/bin upon the first build to assist in building
   1055      subtrees on a cross-compile host.
   1056 
   1057      nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
   1058      the up-to-date version of "nbmake" installed into TOOLDIR/bin with
   1059      several key variables pre-set, including MACHINE, MACHINE_ARCH, and
   1060      TOOLDIR.  nbmake-MACHINE will also set variables specified with -V, and
   1061      unset variables specified with -Z.
   1062 
   1063      This script can be symlinked into a directory listed in PATH, or called
   1064      with an absolute path.
   1065 
   1066 EXAMPLES
   1067      1.   % ./build.sh [options] tools kernel=GENERIC
   1068 
   1069           Build a new toolchain, and use the new toolchain to configure and
   1070           build a new GENERIC kernel.
   1071 
   1072      2.   % ./build.sh [options] -U distribution
   1073 
   1074           Using unprivileged mode, build a complete distribution to a DESTDIR
   1075           directory that build.sh selects (and will display).
   1076 
   1077      3.   # ./build.sh [options] -U install=/
   1078 
   1079           As root, install to / the distribution that was built by example 2.
   1080           Even though this is run as root, -U is required so that the
   1081           permissions stored in DESTDIR/METALOG are correctly applied to the
   1082           files as they're copied to /.
   1083 
   1084      4.   % ./build.sh [options] -U -u release
   1085 
   1086           Using unprivileged mode, build a complete release to DESTDIR and
   1087           RELEASEDIR directories that build.sh selects (and will display).
   1088           MKUPDATE=yes (-u) is set to prevent the "make cleandir", so that if
   1089           this is run after example 2, it doesn't need to redo that portion of
   1090           the release build.
   1091 
   1092 OBSOLETE VARIABLES
   1093      NBUILDJOBS  Use the make(1) option -j instead.
   1094 
   1095      USE_NEW_TOOLCHAIN
   1096                  The new toolchain is now the default.  To disable, use
   1097                  TOOLCHAIN_MISSING=yes.
   1098 
   1099 SEE ALSO
   1100      make(1), hier(7), release(7), etcupdate(8), postinstall(8), sysinst(8),
   1101      pkgsrc/sysutils/cdrtools
   1102 
   1103 HISTORY
   1104      The build.sh based build scheme was introduced for NetBSD 1.6 as
   1105      USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.
   1106 
   1107 CAVEATS
   1108      After significant updates to third-party components in the source tree,
   1109      the "make cleandir" operation may be insufficient to clean out old files
   1110      in object directories.  Instead, one may have to manually remove the
   1111      files.  Consult the UPDATING file for notices concerning this.
   1112 
   1113 NetBSD                          April 13, 2017                          NetBSD
   1114