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
     13      host system to create a build toolchain for the target architecture.  The
     14      host 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)
     49                     ``reachover'' Makefile semantics when building these
     50                     programs for a 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
     85                     programs 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,
    106                        such 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
    176                  a 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
    196                  a file system which supports long file names and hard links.
    197 
    198                  Default: Empty string if USETOOLS is ``yes''; unset
    199                  otherwise.
    200 
    201                  Note: build.sh will provide a default of destdir.MACHINE (in
    202                  the top-level .OBJDIR) unless run in `expert' mode.
    203 
    204      EXTSRCSRCDIR
    205                  Directory containing sources of externally added programs and
    206                  libraries.  If specified, must be an absolute path.
    207 
    208                  Default: NETBSDRCDIR/../extsrc, if that exists; otherwise
    209                  /usr/extsrc.
    210 
    211      MAKECONF    The name of the make(1) configuration file.  Only settable in
    212                  the process environment.
    213 
    214                  Default: ``/etc/mk.conf''
    215 
    216      MAKEVERBOSE
    217                  Level of verbosity of status messages.  Supported values:
    218 
    219                  0    No descriptive messages or commands executed by make(1)
    220                       are shown.
    221 
    222                  1    Brief messages are shown describing what is being done,
    223                       but the actual commands executed by make(1) are not
    224                       displayed.
    225 
    226                  2    Descriptive messages are shown as above (prefixed with a
    227                       `#'), and ordinary commands performed by make(1) are
    228                       displayed.
    229 
    230                  3    In addition to the above, all commands performed by
    231                       make(1) are displayed, even if they would ordinarily
    232                       have been hidden through use of the ``@'' prefix in the
    233                       relevant makefile.
    234 
    235                  4    In addition to the above, commands executed by make(1)
    236                       are traced through use of the sh(1) ``-x'' flag.
    237 
    238                  Default: 2
    239 
    240      MKCATPAGES  Can be set to ``yes'' or ``no''.  Indicates whether
    241                  preformatted plaintext manual pages will be created during a
    242                  build.
    243 
    244                  Default: ``no''
    245 
    246      MKCROSSGDB  Can be set to ``yes'' or ``no''.  Create a cross-gdb as a
    247                  host tool.
    248 
    249                  Default: ``no''
    250 
    251      MKCRYPTO    Can be set to ``yes'' or ``no''.  Indicates whether
    252                  cryptographic code will be included in a build; provided for
    253                  the benefit of countries that do not allow strong
    254                  cryptography.  Will not affect use of the standard low-
    255                  security password encryption system, crypt(3).
    256 
    257                  Default: ``yes''
    258 
    259      MKDEBUG     Can be set to ``yes'' or ``no''.  Indicates whether debug
    260                  information should be generated for all userland binaries
    261                  compiled.  The result is collected as an additional debug.tgz
    262                  and xdebug.tgz set and installed in /usr/libdata/debug.
    263 
    264                  Default: ``no''
    265 
    266      MKDEBUGLIB  Can be set to ``yes'' or ``no''.  Indicates whether debug
    267                  information (see MKDEBUG) should also be generated for all
    268                  libraries build.
    269 
    270                  Default: ``no''
    271 
    272      MKDOC       Can be set to ``yes'' or ``no''.  Indicates whether system
    273                  documentation destined for DESTDIR/usr/share/doc will be
    274                  installed during a build.
    275 
    276                  Default: ``yes''
    277 
    278      MKEXTSRC    Can be set to ``yes'' or ``no''.  Indicates whether extsrc is
    279                  built from EXTSRCSRCDIR.
    280 
    281                  Default: ``no''
    282 
    283      MKHTML      Can be set to ``yes'' or ``no''.  Indicates whether
    284                  preformatted HTML manual pages will be built and installed
    285 
    286                  Default: ``yes''
    287 
    288      MKHOSTOBJ   Can be set to ``yes'' or ``no''.  If set to ``yes'', then for
    289                  programs intended to be run on the compile host, the name,
    290                  release, and architecture of the host operating system will
    291                  be suffixed to the name of the object directory created by
    292                  ``make obj''.  (This allows multiple host systems to compile
    293                  NetBSD for a single target.)  If set to ``no'', then programs
    294                  built to be run on the compile host will use the same object
    295                  directory names as programs built to be run on the target.
    296 
    297                  Default: ``no''
    298 
    299      MKINFO      Can be set to ``yes'' or ``no''.  Indicates whether GNU Info
    300                  files, used for the documentation for most of the compilation
    301                  tools, will be created and installed during a build.
    302 
    303                  Default: ``yes''
    304 
    305      MKKDEBUG    Can be set to ``yes'' or ``no''.  Force generation of full-
    306                  debug symbol versions of all kernels compiled.  Alongside of
    307                  the netbsd kernel file, an unstripped version netbsd.gdb is
    308                  created.  This is useful if a cross-gdb is built as well (see
    309                  MKCROSSGDB).
    310 
    311                  Default: ``no''
    312 
    313      MKKMOD      Can be set to ``yes'' or ``no''.  Indicates whether kernel
    314                  modules are built and installed.
    315 
    316                  Default: ``yes''
    317 
    318      MKLINT      Can be set to ``yes'' or ``no''.  Indicates whether lint(1)
    319                  will be run against portions of the NetBSD source code during
    320                  the build, and whether lint libraries will be installed into
    321                  DESTDIR/usr/libdata/lint.
    322 
    323                  Default: ``yes''
    324 
    325      MKMAN       Can be set to ``yes'' or ``no''.  Indicates whether manual
    326                  pages will be installed during a build.
    327 
    328                  Default: ``yes''
    329 
    330      MKNLS       Can be set to ``yes'' or ``no''.  Indicates whether Native
    331                  Language System locale zone files will be compiled and
    332                  installed during a build.
    333 
    334                  Default: ``yes''
    335 
    336      MKOBJ       Can be set to ``yes'' or ``no''.  Indicates whether object
    337                  directories will be created when running ``make obj''.  If
    338                  set to ``no'', then all built files will be located inside
    339                  the regular source tree.
    340 
    341                  Default: ``yes''
    342 
    343                  Note that setting MKOBJ to ``no'' is not recommended and may
    344                  cause problems when updating the tree with cvs(1).
    345 
    346      MKPIC       Can be set to ``yes'' or ``no''.  Indicates whether shared
    347                  objects and libraries will be created and installed during a
    348                  build.  If set to ``no'', the entire built system will be
    349                  statically linked.
    350 
    351                  Default: Platform dependent.  As of this writing, all
    352                  platforms except m68000 default to ``yes''.
    353 
    354      MKPICINSTALL
    355                  Can be set to ``yes'' or ``no''.  Indicates whether the ar(1)
    356                  format libraries (lib*_pic.a), used to generate shared
    357                  libraries, are installed during a build.
    358 
    359                  Default: ``yes''
    360 
    361      MKPROFILE   Can be set to ``yes'' or ``no''.  Indicates whether profiled
    362                  libraries (lib*_p.a) will be built and installed during a
    363                  build.
    364 
    365                  Default: ``yes''; however, some platforms turn off MKPROFILE
    366                  by default at times due to toolchain problems with profiled
    367                  code.
    368 
    369      MKREPRO     Can be set to ``yes'' or ``no''.  Create reproducible builds.
    370                  This enables different switches to make two builds from the
    371                  same source tree result in the same build results.
    372 
    373                  Default: ``no'' This may be set to ``yes'' by giving build.sh
    374                  the -P option.
    375 
    376      MKREPRO_TIMESTAMP
    377                  Unix timestamp.  When MKREPRO is set, the timestamp of all
    378                  files in the sets will be set to this value.
    379 
    380                  Default: Unset.  This may be set automatically to the latest
    381                  source tree timestamp using cvslatest(1) by giving build.sh
    382                  the -P option.
    383 
    384      MKSHARE     Can be set to ``yes'' or ``no''.  Indicates whether files
    385                  destined to reside in DESTDIR/usr/share will be built and
    386                  installed during a build.  If set to ``no'', then all of
    387                  MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to
    388                  ``no'' unconditionally.
    389 
    390                  Default: ``yes''
    391 
    392      MKSTRIPIDENT
    393                  Can be set to ``yes'' or ``no''.  Indicates whether RCS IDs,
    394                  for use with ident(1), should be stripped from program
    395                  binaries and shared libraries.
    396 
    397                  Default: ``no''
    398 
    399      MKUNPRIVED  Can be set to ``yes'' or ``no''.  Indicates whether an
    400                  unprivileged install will occur.  The user, group,
    401                  permissions, and file flags, will not be set on the installed
    402                  items; instead the information will be appended to a file
    403                  called METALOG in DESTDIR.  The contents of METALOG are used
    404                  during the generation of the distribution tar files to ensure
    405                  that the appropriate file ownership is stored.
    406 
    407                  Default: ``no''
    408 
    409      MKUPDATE    Can be set to ``yes'' or ``no''.  Indicates whether all
    410                  install operations intended to write to DESTDIR will compare
    411                  file timestamps before installing, and skip the install phase
    412                  if the destination files are up-to-date.  This also has
    413                  implications on full builds (see next subsection).
    414 
    415                  Default: ``no''
    416 
    417      MKX11       Can be set to ``yes'' or ``no''.  Indicates whether X11 is
    418                  built from X11SRCDIR.
    419 
    420                  Default: ``no''
    421 
    422      TOOLDIR     Directory to hold the host tools, once built.  If specified,
    423                  must be an absolute path.  This directory should be unique to
    424                  a given host system and NetBSD source tree.  (However,
    425                  multiple targets may share the same TOOLDIR; the target-
    426                  dependent files have unique names.)  If unset, a default
    427                  based on the uname(1) information of the host platform will
    428                  be created in the .OBJDIR of src.
    429 
    430                  Default: Unset.
    431 
    432      USETOOLS    Indicates whether the tools specified by TOOLDIR should be
    433                  used as part of a build in progress.  Must be set to ``yes''
    434                  if cross-compiling.
    435 
    436                  yes    Use the tools from TOOLDIR.
    437 
    438                  no     Do not use the tools from TOOLDIR, but refuse to build
    439                         native compilation tool components that are version-
    440                         specific for that tool.
    441 
    442                  never  Do not use the tools from TOOLDIR, even when building
    443                         native tool components.  This is similar to the
    444                         traditional NetBSD build method, but does not verify
    445                         that the compilation tools in use are up-to-date
    446                         enough in order to build the tree successfully.  This
    447                         may cause build or runtime problems when building the
    448                         whole NetBSD source tree.
    449 
    450                  Default: ``yes'', unless TOOLCHAIN_MISSING is set to ``yes''.
    451 
    452                  USETOOLS is also set to ``no'' when using <bsd.*.mk> outside
    453                  the NetBSD source tree.
    454 
    455      X11SRCDIR   Directory containing the modular Xorg source.  If specified,
    456                  must be an absolute path.  The main modular Xorg source is
    457                  found in X11SRCDIR/external/mit.
    458 
    459                  Default: NETBSDRCDIR/../xsrc, if that exists; otherwise
    460                  /usr/xsrc.
    461 
    462    "make" variables for full builds
    463      These variables only affect the top level ``Makefile'' and do not affect
    464      manually building subtrees of the NetBSD source code.
    465 
    466      INSTALLWORLDDIR  Location for the ``make installworld'' target to install
    467                       to.  If specified, must be an absolute path.
    468 
    469                       Default: ``/''
    470 
    471      MKOBJDIRS        Can be set to ``yes'' or ``no''.  Indicates whether
    472                       object directories will be created automatically (via a
    473                       ``make obj'' pass) at the start of a build.
    474 
    475                       Default: ``no''
    476 
    477                       If using build.sh, the default is ``yes''.  This may be
    478                       set back to ``no'' by giving build.sh the -o option.
    479 
    480      MKUPDATE         Can be set to ``yes'' or ``no''.  If set, then in
    481                       addition to the effects described for MKUPDATE=yes
    482                       above, this implies the effects of NOCLEANDIR (i.e.,
    483                       ``make cleandir'' is avoided).
    484 
    485                       Default: ``no''
    486 
    487                       If using build.sh, this may be set by giving the -u
    488                       option.
    489 
    490      NBUILDJOBS       Now obsolete.  Use the make(1) option -j, instead.  See
    491                       below.
    492 
    493                       Default: Unset.
    494 
    495      NOCLEANDIR       If set, avoids the ``make cleandir'' phase of a full
    496                       build.  This has the effect of allowing only changed
    497                       files in a source tree to be recompiled.  This can speed
    498                       up builds when updating only a few files in the tree.
    499 
    500                       Default: Unset.
    501 
    502                       See also MKUPDATE.
    503 
    504      NODISTRIBDIRS    If set, avoids the ``make distrib-dirs'' phase of a full
    505                       build.  This skips running mtree(8) on DESTDIR, useful
    506                       on systems where building as an unprivileged user, or
    507                       where it is known that the system-wide mtree files have
    508                       not changed.
    509 
    510                       Default: Unset.
    511 
    512      NOINCLUDES       If set, avoids the ``make includes'' phase of a full
    513                       build.  This has the effect of preventing make(1) from
    514                       thinking that some programs are out-of-date simply
    515                       because the system include files have changed.  However,
    516                       this option should not be used when updating the entire
    517                       NetBSD source tree arbitrarily; it is suggested to use
    518                       MKUPDATE=yes instead in that case.
    519 
    520                       Default: Unset.
    521 
    522      RELEASEDIR       If set, specifies the directory to which a release(7)
    523                       layout will be written at the end of a ``make release''.
    524                       If specified, must be an absolute path.
    525 
    526                       Default: Unset.
    527 
    528                       Note: build.sh will provide a default of releasedir (in
    529                       the top-level .OBJDIR) unless run in `expert' mode.
    530 
    531 BUILDING
    532    "make" command line options
    533      This is not a summary of all the options available to make(1); only the
    534      options used most frequently with NetBSD builds are listed here.
    535 
    536      -j njob    Run up to njob make(1) subjobs in parallel.  Makefiles should
    537                 use .WAIT or have explicit dependencies as necessary to
    538                 enforce build ordering.
    539 
    540      -m dir     Specify the default directory for searching for system
    541                 Makefile segments, mainly the <bsd.*.mk> files.  When building
    542                 any full NetBSD source tree, this should be set to the
    543                 ``share/mk'' directory in the source tree.  This is set
    544                 automatically when building from the top level, or when using
    545                 build.sh.
    546 
    547      -n         Display the commands that would have been executed, but do not
    548                 actually execute them.  This will still cause recursion to
    549                 take place.
    550 
    551      -V var     Print make(1)'s idea of the value of var.  Does not build any
    552                 targets.
    553 
    554      var=value  Set the variable var to value, overriding any setting
    555                 specified by the process environment, the MAKECONF
    556                 configuration file, or the system Makefile segments.
    557 
    558    "make" targets
    559      These default targets may be built by running make(1) in any subtree of
    560      the NetBSD source code.  It is recommended that none of these be used
    561      from the top level Makefile; as a specific exception, ``make obj'' and
    562      ``make cleandir'' are useful in that context.
    563 
    564      all        Build programs, libraries, and preformatted documentation.
    565 
    566      clean      Remove program and library object code files.
    567 
    568      cleandir   Same as clean, but also remove preformatted documentation,
    569                 dependency files generated by ``make depend'', and any other
    570                 files known to be created at build time.
    571 
    572      depend     Create dependency files (.depend) containing more detailed
    573                 information about the dependencies of source code on header
    574                 files.  Allows programs to be recompiled automatically when a
    575                 dependency changes.
    576 
    577      dependall  Does a ``make depend'' immediately followed by a ``make all''.
    578                 This improves cache locality of the build since both passes
    579                 read the source files in their entirety.
    580 
    581      distclean  Synonym for cleandir.
    582 
    583      includes   Build and install system header files.  Typically needed
    584                 before any system libraries or programs can be built.
    585 
    586      install    Install programs, libraries, and documentation into DESTDIR.
    587                 Few files will be installed to DESTDIR/dev, DESTDIR/etc,
    588                 DESTDIR/root or DESTDIR/var in order to prevent user supplied
    589                 configuration data from being overwritten.
    590 
    591      lint       Run lint(1) against the C source code, where appropriate, and
    592                 generate system-installed lint libraries.
    593 
    594      obj        Create object directories to be used for built files, instead
    595                 of building directly in the source tree.
    596 
    597      tags       Create ctags(1) searchable function lists usable by the ex(1)
    598                 and vi(1) text editors.
    599 
    600    "make" targets for the top level
    601      Additional make(1) targets are usable specifically from the top source
    602      level to facilitate building the entire NetBSD source tree.
    603 
    604      build         Build the entire NetBSD system (except the kernel).  This
    605                    orders portions of the source tree such that prerequisites
    606                    will be built in the proper order.
    607 
    608      distribution  Do a ``make build'', and then install a full distribution
    609                    (which does not include a kernel) into DESTDIR, including
    610                    files in DESTDIR/dev, DESTDIR/etc, DESTDIR/root and
    611                    DESTDIR/var.
    612 
    613      buildworld    As per ``make distribution'', except that it ensures that
    614                    DESTDIR is not the root directory.
    615 
    616      installworld  Install the distribution from DESTDIR to INSTALLWORLDDIR,
    617                    which defaults to the root directory.  Ensures that
    618                    INSTALLWORLDDIR is not the root directory if cross
    619                    compiling.
    620 
    621                    The INSTALLSETS environment variable may be set to a space-
    622                    separated list of distribution sets to be installed.  By
    623                    default, all sets except ``etc'' and ``xetc'' are
    624                    installed, so most files in INSTALLWORLDDIR/etc will not be
    625                    installed or modified.
    626 
    627                    Note: Before performing this operation with
    628                    INSTALLWORLDDIR=/, it is highly recommended that you
    629                    upgrade your kernel and reboot.  After performing this
    630                    operation, it is recommended that you use etcupdate(8) to
    631                    update files in INSTALLWORLDDIR/etc, and postinstall(8) to
    632                    check for or fix inconsistencies.
    633 
    634      sets          Create distribution sets from DESTDIR into
    635                    RELEASEDIR/RELEASEMACHINEDIR/binary/sets.  Should be run
    636                    after ``make distribution'', as ``make build'' alone does
    637                    not install all of the required files.
    638 
    639      sourcesets    Create source sets of the source tree into
    640                    RELEASEDIR/source/sets.
    641 
    642      syspkgs       Create syspkgs from DESTDIR into
    643                    RELEASEDIR/RELEASEMACHINEDIR/binary/syspkgs.  Should be run
    644                    after ``make distribution'', as ``make build'' alone does
    645                    not install all of the required files.
    646 
    647      release       Do a ``make distribution'', build kernels, distribution
    648                    media, and install sets (this as per ``make sets''), and
    649                    then package the system into a standard release layout as
    650                    described by release(7).  This requires that RELEASEDIR be
    651                    set (see above).
    652 
    653      iso-image     Create a NetBSD installation CD-ROM image in the
    654                    RELEASEDIR/images directory.  The CD-ROM file system will
    655                    have a layout as described in release(7).
    656 
    657                    For most machine types, the CD-ROM will be bootable, and
    658                    will automatically run the sysinst(8) menu-based
    659                    installation program, which can be used to install or
    660                    upgrade a NetBSD system.  Bootable CD-ROMs also contain
    661                    tools that may be useful in repairing a damaged NetBSD
    662                    installation.
    663 
    664                    Before ``make iso-image'' is attempted, RELEASEDIR must be
    665                    populated by ``make release'' or equivalent.
    666 
    667                    Note that other, smaller, CD-ROM images may be created in
    668                    the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom
    669                    directory by ``make release''.  These smaller images
    670                    usually contain the same tools as the larger images in
    671                    RELEASEDIR/images, but do not contain additional content
    672                    such as the distribution sets.
    673 
    674                    Note that the mac68k port still uses an older method of
    675                    creating CD-ROM images.  This requires the mkisofs(1)
    676                    utility, which is not part of NetBSD, but which can be
    677                    installed from pkgsrc/sysutils/cdrtools.
    678 
    679      iso-image-source
    680                    Create a NetBSD installation CD-ROM image in the
    681                    RELEASEDIR/images directory.  The CD-ROM file system will
    682                    have a layout as described in release(7).  It will have top
    683                    level directories for the machine type and source.
    684 
    685                    For most machine types, the CD-ROM will be bootable, and
    686                    will automatically run the sysinst(8) menu-based
    687                    installation program, which can be used to install or
    688                    upgrade a NetBSD system.  Bootable CD-ROMs also contain
    689                    tools that may be useful in repairing a damaged NetBSD
    690                    installation.
    691 
    692                    Before ``make iso-image-source'' is attempted, RELEASEDIR
    693                    must be populated by ``make sourcesets release'' or
    694                    equivalent.
    695 
    696                    Note that other, smaller, CD-ROM images may be created in
    697                    the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom
    698                    directory by ``make release''.  These smaller images
    699                    usually contain the same tools as the larger images in
    700                    RELEASEDIR/images, but do not contain additional content
    701                    such as the distribution sets.
    702 
    703                    Note that the mac68k port still uses an older method of
    704                    creating CD-ROM images.  This requires the mkisofs(1)
    705                    utility, which is not part of NetBSD, but which can be
    706                    installed from pkgsrc/sysutils/cdrtools.
    707 
    708      install-image
    709                    Create a bootable NetBSD installation disk image in the
    710                    RELEASEDIR/RELEASEMACHINEDIR/installation/installimage
    711                    directory.  The installation disk image is suitable for
    712                    copying to bootable USB flash memory sticks, etc., for
    713                    machines which are able to boot from such devices.  The
    714                    file system in the bootable disk image will have a layout
    715                    as described in release(7).
    716 
    717                    The installation image is bootable, and will automatically
    718                    run the sysinst(8) menu-based installation program, which
    719                    can be used to install or upgrade a NetBSD system.  The
    720                    image also contains tools that may be useful in repairing a
    721                    damaged NetBSD installation.
    722 
    723                    Before ``make install-image'' is attempted, RELEASEDIR must
    724                    be populated by ``make release'' or equivalent.  The build
    725                    must have been performed with MKUNPRIVED=yes because ``make
    726                    install-image'' relies on information in DESTDIR/METALOG.
    727 
    728      live-image    Create NetBSD live images in the RELEASEDIR/images
    729                    directory.  The live image contains all necessary files to
    730                    boot NetBSD up to multi-user mode, including all files
    731                    which should be extracted during installation, NetBSD
    732                    disklabel, bootloaders, etc.
    733 
    734                    The live image is suitable for use as a disk image in
    735                    virtual machine environments such as QEMU, and also useful
    736                    to boot NetBSD from a USB flash memory stick on a real
    737                    machine, without the need for installation.
    738 
    739                    Before ``make live-image'' is attempted, RELEASEDIR must be
    740                    populated by ``make release'' or equivalent.  The build
    741                    must have been performed with MKUNPRIVED=yes because ``make
    742                    install-image'' relies on information in DESTDIR/METALOG.
    743 
    744      regression-tests
    745                    Can only be run after building the regression tests in the
    746                    directory ``regress''.  Runs those compiled regression
    747                    tests on the local host.  Note that most tests are now
    748                    managed instead using atf(7); this target should probably
    749                    run those as well but currently does not.
    750 
    751    The "build.sh" script
    752      This script file is a shell script designed to build the entire NetBSD
    753      system on any host with a suitable modern shell and some common
    754      utilities.  The required shell features are described under the HOST_SH
    755      variable.
    756 
    757      If a host system's default shell does support the required features, then
    758      we suggest that you explicitly specify a suitable shell using a command
    759      like
    760 
    761            /path/to/suitable/shell build.sh [options]
    762 
    763      The above command will usually enable build.sh to automatically set
    764      HOST_SH=/path/to/suitable/shell, but if that fails, then the following
    765      set of commands may be used instead:
    766 
    767            HOST_SH=/path/to/suitable/shell
    768            export HOST_SH
    769            ${HOST_SH} build.sh [options]
    770 
    771      If build.sh detects that it is being executed under an unsuitable shell,
    772      it attempts to exec a suitable shell instead, or prints an error message.
    773      If HOST_SH is not set explicitly, then build.sh sets a default using
    774      heuristics dependent on the host platform, or from the shell under which
    775      build.sh is executed (if that can be determined), or using the first copy
    776      of sh found in PATH.
    777 
    778      All cross-compile builds, and most native builds, of the entire system
    779      should make use of build.sh rather than just running ``make''.  This way,
    780      the make(1) program will be bootstrapped properly, in case the host
    781      system has an older or incompatible ``make'' program.
    782 
    783      When compiling the entire system via build.sh, many make(1) variables are
    784      set for you in order to help encapsulate the build process.  In the list
    785      of options below, variables that are automatically set by build.sh are
    786      noted where applicable.
    787 
    788      The following operations are supported by build.sh:
    789 
    790      build         Build the system as per ``make build''.  Before the main
    791                    part of the build commences, this command runs the obj
    792                    operation (unless the -o option is given), ``make
    793                    cleandir'' (unless the -u option is given), and the tools
    794                    operation.
    795 
    796      distribution  Build a full distribution as per ``make distribution''.
    797                    This 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''
    811                    in 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
    816                    ``etc'' or ``xetc'' sets will not be installed, unless
    817                    overridden by 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
    855                    determined 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
    900                root 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
    931                obj'' 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
    962                MAKEVERBOSE 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
    966                -n''.
    967 
    968      -O obj    Create an appropriate transform macro for MAKEOBJDIR that will
    969                place the built object files under obj.  Unsets
    970                MAKEOBJDIRPREFIX.
    971 
    972                For instance, a setting of ``-O /usr/obj'' will place build-
    973                time files under /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin,
    974                and so forth.
    975 
    976                If a relative path is specified, it will be converted to an
    977                absolute path before being used.  build.sh imposes the
    978                restriction that the argument to the -O option must not contain
    979                a ``$'' (dollar sign) character.  If the directory does not
    980                already exist, build.sh will create it.
    981 
    982                In normal use, exactly one of the -M or -O options should be
    983                specified.  If neither -M nor -O is specified, then a default
    984                object directory will be chosen according to rules in
    985                <bsd.obj.mk>.  Relying on this default is not recommended
    986                because it is determined by complex rules that are influenced
    987                by the values of several variables and by the location of the
    988                source directory.
    989 
    990                Note that placing the obj directory location outside of the
    991                default source tree hierarchy makes it easier to manually clear
    992                out old files in the event the ``make cleandir'' operation is
    993                unable to do so.  (See CAVEATS below.)
    994 
    995                Note also that use of one of -M or -O is the only means of
    996                building multiple machine architecture userlands from the same
    997                source tree without cleaning between builds (in which case, one
    998                would specify distinct obj locations for each).
    999 
   1000      -o        Set the value of MKOBJDIRS to ``no''.  Otherwise, it will be
   1001                automatically set to ``yes''.  This default is opposite to the
   1002                behaviour when not using build.sh.
   1003 
   1004      -R rel    Set the value of RELEASEDIR to rel.  If a relative path is
   1005                specified, it will be converted to an absolute path before
   1006                being used.
   1007 
   1008      -r        Remove the contents of DESTDIR and TOOLDIR before building
   1009                (provides a clean starting point).  This will skip deleting
   1010                DESTDIR if building on a native system to the root directory.
   1011 
   1012      -S seed   Change the value of BUILDSEED to seed.  This should rarely be
   1013                necessary.
   1014 
   1015      -T tools  Set the value of TOOLDIR to tools.  If a relative path is
   1016                specified, it will be converted to an absolute path before
   1017                being used.  If set, the bootstrap ``make'' will only be
   1018                rebuilt if the source files for make(1) have changed.
   1019 
   1020      -U        Set MKUNPRIVED=yes.
   1021 
   1022      -u        Set MKUPDATE=yes.
   1023 
   1024      -V var=[value]
   1025                Set the environment variable var to an optional value.  This is
   1026                propagated to the nbmake wrapper.
   1027 
   1028      -w wrapper
   1029                Create the nbmake wrapper script (see below) in a custom
   1030                location, specified by wrapper.  This allows, for instance, to
   1031                place the wrapper in PATH automatically.  Note that wrapper is
   1032                the full name of the file, not just a directory name.  If a
   1033                relative path is specified, it will be converted to an absolute
   1034                path before being used.
   1035 
   1036      -X x11src
   1037                Set the value of X11SRCDIR to x11src.  If a relative path is
   1038                specified, it will be converted to an absolute path before
   1039                being used.
   1040 
   1041      -x        Set MKX11=yes.
   1042 
   1043      -Y extsrcdir
   1044                Set the value of EXTSRCSRCDIR to extsrcdir.  If a relative path
   1045                is specified, it will be converted to an absolute path before
   1046                being used.
   1047 
   1048      -y        Set MKEXTSRC=yes.
   1049 
   1050      -Z var    Unset ("zap") the environment variable var.  This is propagated
   1051                to the nbmake wrapper.
   1052 
   1053    The "nbmake-MACHINE" wrapper script
   1054      If using the build.sh script to build NetBSD, a nbmake-MACHINE script
   1055      will be created in TOOLDIR/bin upon the first build to assist in building
   1056      subtrees on a cross-compile host.
   1057 
   1058      nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
   1059      the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with
   1060      several key variables pre-set, including MACHINE, MACHINE_ARCH, and
   1061      TOOLDIR.  nbmake-MACHINE will also set variables specified with -V, and
   1062      unset variables specified with -Z.
   1063 
   1064      This script can be symlinked into a directory listed in PATH, or called
   1065      with an absolute path.
   1066 
   1067 EXAMPLES
   1068      1.   % ./build.sh [options] tools kernel=GENERIC
   1069 
   1070           Build a new toolchain, and use the new toolchain to configure and
   1071           build a new GENERIC kernel.
   1072 
   1073      2.   % ./build.sh [options] -U distribution
   1074 
   1075           Using unprivileged mode, build a complete distribution to a DESTDIR
   1076           directory that build.sh selects (and will display).
   1077 
   1078      3.   # ./build.sh [options] -U install=/
   1079 
   1080           As root, install to / the distribution that was built by example 2.
   1081           Even though this is run as root, -U is required so that the
   1082           permissions stored in DESTDIR/METALOG are correctly applied to the
   1083           files as they're copied to /.
   1084 
   1085      4.   % ./build.sh [options] -U -u release
   1086 
   1087           Using unprivileged mode, build a complete release to DESTDIR and
   1088           RELEASEDIR directories that build.sh selects (and will display).
   1089           MKUPDATE=yes (-u) is set to prevent the ``make cleandir'', so that
   1090           if this is run after example 2, it doesn't need to redo that portion
   1091           of the release build.
   1092 
   1093 OBSOLETE VARIABLES
   1094      NBUILDJOBS  Use the make(1) option -j instead.
   1095 
   1096      USE_NEW_TOOLCHAIN
   1097                  The new toolchain is now the default.  To disable, use
   1098                  TOOLCHAIN_MISSING=yes.
   1099 
   1100 SEE ALSO
   1101      make(1), hier(7), release(7), etcupdate(8), postinstall(8), sysinst(8),
   1102      pkgsrc/sysutils/cdrtools
   1103 
   1104 HISTORY
   1105      The build.sh based build scheme was introduced for NetBSD 1.6 as
   1106      USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.
   1107 
   1108 CAVEATS
   1109      After significant updates to third-party components in the source tree,
   1110      the ``make cleandir'' operation may be insufficient to clean out old
   1111      files in object directories.  Instead, one may have to manually remove
   1112      the files.  Consult the UPDATING file for notices concerning this.
   1113 
   1114 NetBSD                         February 20, 2017                        NetBSD
   1115