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      MKCRYPTO    Can be set to "yes" or "no".  Indicates whether cryptographic
    250                  code will be included in a build; provided for the benefit of
    251                  countries that do not allow strong cryptography.  Will not
    252                  affect use of the standard low-security password encryption
    253                  system, crypt(3).
    254 
    255                  Default: "yes"
    256 
    257      MKDEBUG     Can be set to "yes" or "no".  Indicates whether debug
    258                  information should be generated for all userland binaries
    259                  compiled.  The result is collected as an additional debug.tgz
    260                  and xdebug.tgz set and installed in /usr/libdata/debug.
    261 
    262                  Default: "no"
    263 
    264      MKDEBUGLIB  Can be set to "yes" or "no".  Indicates whether debug
    265                  information (see MKDEBUG) should also be generated for all
    266                  libraries build.
    267 
    268                  Default: "no"
    269 
    270      MKDOC       Can be set to "yes" or "no".  Indicates whether system
    271                  documentation destined for DESTDIR/usr/share/doc will be
    272                  installed during a build.
    273 
    274                  Default: "yes"
    275 
    276      MKEXTSRC    Can be set to "yes" or "no".  Indicates whether extsrc is
    277                  built from EXTSRCSRCDIR.
    278 
    279                  Default: "no"
    280 
    281      MKHTML      Can be set to "yes" or "no".  Indicates whether preformatted
    282                  HTML manual pages will be built and installed
    283 
    284                  Default: "yes"
    285 
    286      MKHOSTOBJ   Can be set to "yes" or "no".  If set to "yes", then for
    287                  programs intended to be run on the compile host, the name,
    288                  release, and architecture of the host operating system will
    289                  be suffixed to the name of the object directory created by
    290                  "make obj".  (This allows multiple host systems to compile
    291                  NetBSD for a single target.)  If set to "no", then programs
    292                  built to be run on the compile host will use the same object
    293                  directory names as programs built to be run on the target.
    294 
    295                  Default: "no"
    296 
    297      MKINFO      Can be set to "yes" or "no".  Indicates whether GNU Info
    298                  files, used for the documentation for most of the compilation
    299                  tools, will be created and installed during a build.
    300 
    301                  Default: "yes"
    302 
    303      MKKDEBUG    Can be set to "yes" or "no".  Force generation of full-debug
    304                  symbol versions of all kernels compiled.  Alongside of the
    305                  netbsd kernel file, an unstripped version netbsd.gdb is
    306                  created.  This is useful if a cross-gdb is built as well (see
    307                  MKCROSSGDB).
    308 
    309                  Default: "no"
    310 
    311      MKKMOD      Can be set to "yes" or "no".  Indicates whether kernel
    312                  modules are built and installed.
    313 
    314                  Default: "yes"
    315 
    316      MKLINT      Can be set to "yes" or "no".  Indicates whether lint(1) will
    317                  be run against portions of the NetBSD source code during the
    318                  build, and whether lint libraries will be installed into
    319                  DESTDIR/usr/libdata/lint.
    320 
    321                  Default: "yes"
    322 
    323      MKMAN       Can be set to "yes" or "no".  Indicates whether manual pages
    324                  will be installed during a build.
    325 
    326                  Default: "yes"
    327 
    328      MKNLS       Can be set to "yes" or "no".  Indicates whether Native
    329                  Language System locale zone files will be compiled and
    330                  installed during a build.
    331 
    332                  Default: "yes"
    333 
    334      MKOBJ       Can be set to "yes" or "no".  Indicates whether object
    335                  directories will be created when running "make obj".  If set
    336                  to "no", then all built files will be located inside the
    337                  regular source tree.
    338 
    339                  Default: "yes"
    340 
    341                  Note that setting MKOBJ to "no" is not recommended and may
    342                  cause problems when updating the tree with cvs(1).
    343 
    344      MKPIC       Can be set to "yes" or "no".  Indicates whether shared
    345                  objects and libraries will be created and installed during a
    346                  build.  If set to "no", the entire built system will be
    347                  statically linked.
    348 
    349                  Default: Platform dependent.  As of this writing, all
    350                  platforms except sh3 default to "yes".
    351 
    352      MKPICINSTALL
    353                  Can be set to "yes" or "no".  Indicates whether the ar(1)
    354                  format libraries (lib*_pic.a), used to generate shared
    355                  libraries, are installed during a build.
    356 
    357                  Default: "yes"
    358 
    359      MKPROFILE   Can be set to "yes" or "no".  Indicates whether profiled
    360                  libraries (lib*_p.a) will be built and installed during a
    361                  build.
    362 
    363                  Default: "yes"; however, some platforms turn off MKPROFILE by
    364                  default at times due to toolchain problems with profiled
    365                  code.
    366 
    367      MKREPRO     Can be set to "yes" or "no".  Create reproducible builds.
    368                  This enables different switches to make two builds from the
    369                  same source tree result in the same build results.
    370 
    371                  Default: "no" This may be set to "yes" by giving build.sh the
    372                  -P option.
    373 
    374      MKREPRO_TIMESTAMP
    375                  Unix timestamp.  When MKREPRO is set, the timestamp of all
    376                  files in the sets will be set to this value.
    377 
    378                  Default: Unset.  This may be set automatically to the latest
    379                  source tree timestamp using cvslatest(1) by giving build.sh
    380                  the -P option.
    381 
    382      MKSHARE     Can be set to "yes" or "no".  Indicates whether files
    383                  destined to reside in DESTDIR/usr/share will be built and
    384                  installed during a build.  If set to "no", then all of
    385                  MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to
    386                  "no" unconditionally.
    387 
    388                  Default: "yes"
    389 
    390      MKSTRIPIDENT
    391                  Can be set to "yes" or "no".  Indicates whether RCS IDs, for
    392                  use with ident(1), should be stripped from program binaries
    393                  and shared libraries.
    394 
    395                  Default: "no"
    396 
    397      MKSTRIPSYM  Can be set to "yes" or "no".  Indicates whether all local
    398                  symbols should be stripped from shared libraries.  If "yes",
    399                  strip all local symbols from shared libraries; the affect is
    400                  equivalent to the -x option of ld(1).  If "no", strip only
    401                  temporary local symbols; the affect is equivalent to the -X
    402                  option of ld(1).  Keeping non-temporary local symbols such as
    403                  static function names is useful on using DTrace for userland
    404                  libraries and getting a backtrace from a rump kernel loading
    405                  shared libraries.
    406 
    407                  Default: "yes"
    408 
    409      MKUNPRIVED  Can be set to "yes" or "no".  Indicates whether an
    410                  unprivileged install will occur.  The user, group,
    411                  permissions, and file flags, will not be set on the installed
    412                  items; instead the information will be appended to a file
    413                  called METALOG in DESTDIR.  The contents of METALOG are used
    414                  during the generation of the distribution tar files to ensure
    415                  that the appropriate file ownership is stored.
    416 
    417                  Default: "no"
    418 
    419      MKUPDATE    Can be set to "yes" or "no".  Indicates whether all install
    420                  operations intended to write to DESTDIR will compare file
    421                  timestamps before installing, and skip the install phase if
    422                  the destination files are up-to-date.  This also has
    423                  implications on full builds (see next subsection).
    424 
    425                  Default: "no"
    426 
    427      MKX11       Can be set to "yes" or "no".  Indicates whether X11 is built
    428                  from X11SRCDIR.
    429 
    430                  Default: "no"
    431 
    432      TOOLDIR     Directory to hold the host tools, once built.  If specified,
    433                  must be an absolute path.  This directory should be unique to
    434                  a given host system and NetBSD source tree.  (However,
    435                  multiple targets may share the same TOOLDIR; the target-
    436                  dependent files have unique names.)  If unset, a default
    437                  based on the uname(1) information of the host platform will
    438                  be created in the .OBJDIR of src.
    439 
    440                  Default: Unset.
    441 
    442      USETOOLS    Indicates whether the tools specified by TOOLDIR should be
    443                  used as part of a build in progress.  Must be set to "yes" if
    444                  cross-compiling.
    445 
    446                  yes    Use the tools from TOOLDIR.
    447 
    448                  no     Do not use the tools from TOOLDIR, but refuse to build
    449                         native compilation tool components that are version-
    450                         specific for that tool.
    451 
    452                  never  Do not use the tools from TOOLDIR, even when building
    453                         native tool components.  This is similar to the
    454                         traditional NetBSD build method, but does not verify
    455                         that the compilation tools in use are up-to-date
    456                         enough in order to build the tree successfully.  This
    457                         may cause build or runtime problems when building the
    458                         whole NetBSD source tree.
    459 
    460                  Default: "yes", unless TOOLCHAIN_MISSING is set to "yes".
    461 
    462                  USETOOLS is also set to "no" when using <bsd.*.mk> outside
    463                  the NetBSD source tree.
    464 
    465      X11SRCDIR   Directory containing the modular Xorg source.  If specified,
    466                  must be an absolute path.  The main modular Xorg source is
    467                  found in X11SRCDIR/external/mit.
    468 
    469                  Default: NETBSDRCDIR/../xsrc, if that exists; otherwise
    470                  /usr/xsrc.
    471 
    472    "make" variables for full builds
    473      These variables only affect the top level "Makefile" and do not affect
    474      manually building subtrees of the NetBSD source code.
    475 
    476      INSTALLWORLDDIR  Location for the "make installworld" target to install
    477                       to.  If specified, must be an absolute path.
    478 
    479                       Default: "/"
    480 
    481      MKOBJDIRS        Can be set to "yes" or "no".  Indicates whether object
    482                       directories will be created automatically (via a "make
    483                       obj" pass) at the start of a build.
    484 
    485                       Default: "no"
    486 
    487                       If using build.sh, the default is "yes".  This may be
    488                       set back to "no" by giving build.sh the -o option.
    489 
    490      MKUPDATE         Can be set to "yes" or "no".  If set, then in addition
    491                       to the effects described for MKUPDATE=yes above, this
    492                       implies the effects of NOCLEANDIR (i.e., "make cleandir"
    493                       is avoided).
    494 
    495                       Default: "no"
    496 
    497                       If using build.sh, this may be set by giving the -u
    498                       option.
    499 
    500      NBUILDJOBS       Now obsolete.  Use the make(1) option -j, instead.  See
    501                       below.
    502 
    503                       Default: Unset.
    504 
    505      NOCLEANDIR       If set, avoids the "make cleandir" phase of a full
    506                       build.  This has the effect of allowing only changed
    507                       files in a source tree to be recompiled.  This can speed
    508                       up builds when updating only a few files in the tree.
    509 
    510                       Default: Unset.
    511 
    512                       See also MKUPDATE.
    513 
    514      NODISTRIBDIRS    If set, avoids the "make distrib-dirs" phase of a full
    515                       build.  This skips running mtree(8) on DESTDIR, useful
    516                       on systems where building as an unprivileged user, or
    517                       where it is known that the system-wide mtree files have
    518                       not changed.
    519 
    520                       Default: Unset.
    521 
    522      NOINCLUDES       If set, avoids the "make includes" phase of a full
    523                       build.  This has the effect of preventing make(1) from
    524                       thinking that some programs are out-of-date simply
    525                       because the system include files have changed.  However,
    526                       this option should not be used when updating the entire
    527                       NetBSD source tree arbitrarily; it is suggested to use
    528                       MKUPDATE=yes instead in that case.
    529 
    530                       Default: Unset.
    531 
    532      RELEASEDIR       If set, specifies the directory to which a release(7)
    533                       layout will be written at the end of a "make release".
    534                       If specified, must be an absolute path.
    535 
    536                       Default: Unset.
    537 
    538                       Note: build.sh will provide a default of releasedir (in
    539                       the top-level .OBJDIR) unless run in `expert' mode.
    540 
    541 BUILDING
    542    "make" command line options
    543      This is not a summary of all the options available to make(1); only the
    544      options used most frequently with NetBSD builds are listed here.
    545 
    546      -j njob    Run up to njob make(1) subjobs in parallel.  Makefiles should
    547                 use .WAIT or have explicit dependencies as necessary to
    548                 enforce build ordering.
    549 
    550      -m dir     Specify the default directory for searching for system
    551                 Makefile segments, mainly the <bsd.*.mk> files.  When building
    552                 any full NetBSD source tree, this should be set to the
    553                 "share/mk" directory in the source tree.  This is set
    554                 automatically when building from the top level, or when using
    555                 build.sh.
    556 
    557      -n         Display the commands that would have been executed, but do not
    558                 actually execute them.  This will still cause recursion to
    559                 take place.
    560 
    561      -V var     Print make(1)'s idea of the value of var.  Does not build any
    562                 targets.
    563 
    564      var=value  Set the variable var to value, overriding any setting
    565                 specified by the process environment, the MAKECONF
    566                 configuration file, or the system Makefile segments.
    567 
    568    "make" targets
    569      These default targets may be built by running make(1) in any subtree of
    570      the NetBSD source code.  It is recommended that none of these be used
    571      from the top level Makefile; as a specific exception, "make obj" and
    572      "make cleandir" are useful in that context.
    573 
    574      all        Build programs, libraries, and preformatted documentation.
    575 
    576      clean      Remove program and library object code files.
    577 
    578      cleandir   Same as clean, but also remove preformatted documentation,
    579                 dependency files generated by "make depend", and any other
    580                 files known to be created at build time.
    581 
    582      depend     Create dependency files (.depend) containing more detailed
    583                 information about the dependencies of source code on header
    584                 files.  Allows programs to be recompiled automatically when a
    585                 dependency changes.
    586 
    587      dependall  Does a "make depend" immediately followed by a "make all".
    588                 This improves cache locality of the build since both passes
    589                 read the source files in their entirety.
    590 
    591      distclean  Synonym for cleandir.
    592 
    593      includes   Build and install system header files.  Typically needed
    594                 before any system libraries or programs can be built.
    595 
    596      install    Install programs, libraries, and documentation into DESTDIR.
    597                 Few files will be installed to DESTDIR/dev, DESTDIR/etc,
    598                 DESTDIR/root or DESTDIR/var in order to prevent user supplied
    599                 configuration data from being overwritten.
    600 
    601      lint       Run lint(1) against the C source code, where appropriate, and
    602                 generate system-installed lint libraries.
    603 
    604      obj        Create object directories to be used for built files, instead
    605                 of building directly in the source tree.
    606 
    607      tags       Create ctags(1) searchable function lists usable by the ex(1)
    608                 and vi(1) text editors.
    609 
    610    "make" targets for the top level
    611      Additional make(1) targets are usable specifically from the top source
    612      level to facilitate building the entire NetBSD source tree.
    613 
    614      build         Build the entire NetBSD system (except the kernel).  This
    615                    orders portions of the source tree such that prerequisites
    616                    will be built in the proper order.
    617 
    618      distribution  Do a "make build", and then install a full distribution
    619                    (which does not include a kernel) into DESTDIR, including
    620                    files in DESTDIR/dev, DESTDIR/etc, DESTDIR/root and
    621                    DESTDIR/var.
    622 
    623      buildworld    As per "make distribution", except that it ensures that
    624                    DESTDIR is not the root directory.
    625 
    626      installworld  Install the distribution from DESTDIR to INSTALLWORLDDIR,
    627                    which defaults to the root directory.  Ensures that
    628                    INSTALLWORLDDIR is not the root directory if cross
    629                    compiling.
    630 
    631                    The INSTALLSETS environment variable may be set to a space-
    632                    separated list of distribution sets to be installed.  By
    633                    default, all sets except "etc" and "xetc" are installed, so
    634                    most files in INSTALLWORLDDIR/etc will not be installed or
    635                    modified.
    636 
    637                    Note: Before performing this operation with
    638                    INSTALLWORLDDIR=/, it is highly recommended that you
    639                    upgrade your kernel and reboot.  After performing this
    640                    operation, it is recommended that you use etcupdate(8) to
    641                    update files in INSTALLWORLDDIR/etc, and postinstall(8) to
    642                    check for or fix inconsistencies.
    643 
    644      sets          Create distribution sets from DESTDIR into
    645                    RELEASEDIR/RELEASEMACHINEDIR/binary/sets.  Should be run
    646                    after "make distribution", as "make build" alone does not
    647                    install all of the required files.
    648 
    649      sourcesets    Create source sets of the source tree into
    650                    RELEASEDIR/source/sets.
    651 
    652      syspkgs       Create syspkgs from DESTDIR into
    653                    RELEASEDIR/RELEASEMACHINEDIR/binary/syspkgs.  Should be run
    654                    after "make distribution", as "make build" alone does not
    655                    install all of the required files.
    656 
    657      release       Do a "make distribution", build kernels, distribution
    658                    media, and install sets (this as per "make sets"), and then
    659                    package the system into a standard release layout as
    660                    described by release(7).  This requires that RELEASEDIR be
    661                    set (see above).
    662 
    663      iso-image     Create a NetBSD installation CD-ROM image in the
    664                    RELEASEDIR/images directory.  The CD-ROM file system will
    665                    have a layout as described in release(7).
    666 
    667                    For most machine types, the CD-ROM will be bootable, and
    668                    will automatically run the sysinst(8) menu-based
    669                    installation program, which can be used to install or
    670                    upgrade a NetBSD system.  Bootable CD-ROMs also contain
    671                    tools that may be useful in repairing a damaged NetBSD
    672                    installation.
    673 
    674                    Before "make iso-image" is attempted, RELEASEDIR must be
    675                    populated by "make release" or equivalent.
    676 
    677                    Note that other, smaller, CD-ROM images may be created in
    678                    the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom
    679                    directory by "make release".  These smaller images usually
    680                    contain the same tools as the larger images in
    681                    RELEASEDIR/images, but do not contain additional content
    682                    such as the distribution sets.
    683 
    684                    Note that the mac68k port still uses an older method of
    685                    creating CD-ROM images.  This requires the mkisofs(1)
    686                    utility, which is not part of NetBSD, but which can be
    687                    installed from pkgsrc/sysutils/cdrtools.
    688 
    689      iso-image-source
    690                    Create a NetBSD installation CD-ROM image in the
    691                    RELEASEDIR/images directory.  The CD-ROM file system will
    692                    have a layout as described in release(7).  It will have top
    693                    level directories for the machine type and source.
    694 
    695                    For most machine types, the CD-ROM will be bootable, and
    696                    will automatically run the sysinst(8) menu-based
    697                    installation program, which can be used to install or
    698                    upgrade a NetBSD system.  Bootable CD-ROMs also contain
    699                    tools that may be useful in repairing a damaged NetBSD
    700                    installation.
    701 
    702                    Before "make iso-image-source" is attempted, RELEASEDIR
    703                    must be populated by "make sourcesets release" or
    704                    equivalent.
    705 
    706                    Note that other, smaller, CD-ROM images may be created in
    707                    the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom
    708                    directory by "make release".  These smaller images usually
    709                    contain the same tools as the larger images in
    710                    RELEASEDIR/images, but do not contain additional content
    711                    such as the distribution sets.
    712 
    713                    Note that the mac68k port still uses an older method of
    714                    creating CD-ROM images.  This requires the mkisofs(1)
    715                    utility, which is not part of NetBSD, but which can be
    716                    installed from pkgsrc/sysutils/cdrtools.
    717 
    718      install-image
    719                    Create a bootable NetBSD installation disk image in the
    720                    RELEASEDIR/images directory.  The installation disk image
    721                    is suitable for copying to bootable USB flash memory
    722                    sticks, etc., for machines which are able to boot from such
    723                    devices.  The file system in the bootable disk image will
    724                    have a layout as described in release(7).
    725 
    726                    The installation image is bootable, and will automatically
    727                    run the sysinst(8) menu-based installation program, which
    728                    can be used to install or upgrade a NetBSD system.  The
    729                    image also contains tools that may be useful in repairing a
    730                    damaged NetBSD installation.
    731 
    732                    Before "make install-image" is attempted, RELEASEDIR must
    733                    be populated by "make release" or equivalent.  The build
    734                    must have been performed with MKUNPRIVED=yes because "make
    735                    install-image" relies on information in DESTDIR/METALOG.
    736 
    737      live-image    Create NetBSD live images in the RELEASEDIR/images
    738                    directory.  The live image contains all necessary files to
    739                    boot NetBSD up to multi-user mode, including all files
    740                    which should be extracted during installation, NetBSD
    741                    disklabel, bootloaders, etc.
    742 
    743                    The live image is suitable for use as a disk image in
    744                    virtual machine environments such as QEMU, and also useful
    745                    to boot NetBSD from a USB flash memory stick on a real
    746                    machine, without the need for installation.
    747 
    748                    Before "make live-image" is attempted, RELEASEDIR must be
    749                    populated by "make release" or equivalent.  The build must
    750                    have been performed with MKUNPRIVED=yes because "make
    751                    install-image" relies on information in DESTDIR/METALOG.
    752 
    753      regression-tests
    754                    Can only be run after building the regression tests in the
    755                    directory "regress".  Runs those compiled regression tests
    756                    on the local host.  Note that most tests are now managed
    757                    instead using atf(7); this target should probably run those
    758                    as well but currently does not.
    759 
    760    The "build.sh" script
    761      This script file is a shell script designed to build the entire NetBSD
    762      system on any host with a suitable modern shell and some common
    763      utilities.  The required shell features are described under the HOST_SH
    764      variable.
    765 
    766      If a host system's default shell does support the required features, then
    767      we suggest that you explicitly specify a suitable shell using a command
    768      like
    769 
    770            /path/to/suitable/shell build.sh [options]
    771 
    772      The above command will usually enable build.sh to automatically set
    773      HOST_SH=/path/to/suitable/shell, but if that fails, then the following
    774      set of commands may be used instead:
    775 
    776            HOST_SH=/path/to/suitable/shell
    777            export HOST_SH
    778            ${HOST_SH} build.sh [options]
    779 
    780      If build.sh detects that it is being executed under an unsuitable shell,
    781      it attempts to exec a suitable shell instead, or prints an error message.
    782      If HOST_SH is not set explicitly, then build.sh sets a default using
    783      heuristics dependent on the host platform, or from the shell under which
    784      build.sh is executed (if that can be determined), or using the first copy
    785      of sh found in PATH.
    786 
    787      All cross-compile builds, and most native builds, of the entire system
    788      should make use of build.sh rather than just running "make".  This way,
    789      the make(1) program will be bootstrapped properly, in case the host
    790      system has an older or incompatible "make" program.
    791 
    792      When compiling the entire system via build.sh, many make(1) variables are
    793      set for you in order to help encapsulate the build process.  In the list
    794      of options below, variables that are automatically set by build.sh are
    795      noted where applicable.
    796 
    797      The following operations are supported by build.sh:
    798 
    799      build         Build the system as per "make build".  Before the main part
    800                    of the build commences, this command runs the obj operation
    801                    (unless the -o option is given), "make cleandir" (unless
    802                    the -u option is given), and the tools operation.
    803 
    804      distribution  Build a full distribution as per "make distribution".  This
    805                    command first runs the build operation.
    806 
    807      release       Build a full release as per "make release".  This command
    808                    first runs the distribution operation.
    809 
    810      makewrapper   Create the nbmake-MACHINE wrapper.  This operation is
    811                    automatically performed for any of the other operations.
    812 
    813      cleandir      Perform "make cleandir".
    814 
    815      obj           Perform "make obj".
    816 
    817      tools         Build and install the host tools from src/tools.  This
    818                    command will first run "make obj" and "make cleandir" in
    819                    the tools subdirectory unless the -o or -u options
    820                    (respectively) are given.
    821 
    822      install=idir  Install the contents of DESTDIR to idir, using "make
    823                    installworld".  Note that files that are part of the "etc"
    824                    or "xetc" sets will not be installed, unless overridden by
    825                    the INSTALLSETS environment variable.
    826 
    827      kernel=kconf  Build a new kernel.  The kconf argument is the name of a
    828                    configuration file suitable for use by config(1).  If kconf
    829                    does not contain any `/' characters, the configuration file
    830                    is expected to be found in the KERNCONFDIR directory, which
    831                    is typically sys/arch/MACHINE/conf.  The new kernel will be
    832                    built in a subdirectory of KERNOBJDIR, which is typically
    833                    sys/arch/MACHINE/compile or an associated object directory.
    834 
    835                    This command does not imply the tools command; run the
    836                    tools command first unless it is certain that the tools
    837                    already exist and are up to date.
    838 
    839                    This command will run "make cleandir" on the kernel in
    840                    question first unless the -u option is given.
    841 
    842      kernel.gdb=kconf
    843                    Build a new kernel with debug information.  Similar to the
    844                    above kernel=kconf operation, but creates a netbsd.gdb file
    845                    alongside of the kernel netbsd, which contains a full
    846                    symbol table and can be used for debugging (for example
    847                    with a cross-gdb built by MKCROSSGDB).
    848 
    849      kernels       This command will build all kernels defined in port
    850                    specific release build procedure.
    851 
    852                    This command internally calls the kernel=kconf operation
    853                    for each found kernel configuration file.
    854 
    855      modules       This command will build kernel modules and install them
    856                    into DESTDIR.
    857 
    858      releasekernel=kconf
    859                    Install a gzip(1)ed copy of the kernel previously built by
    860                    kernel=kconf into
    861                    RELEASEDIR/RELEASEMACHINEDIR/binary/kernel, usually as
    862                    netbsd-kconf.gz, although the "netbsd" prefix is determined
    863                    from the "config" directives in kconf.
    864 
    865      sets          Perform "make sets".
    866 
    867      sourcesets    Perform "make sourcesets".
    868 
    869      syspkgs       Perform "make syspkgs".
    870 
    871      iso-image     Perform "make iso-image".
    872 
    873      iso-image-source
    874                    Perform "make iso-image-source".
    875 
    876      install-image
    877                    Perform "make install-image".
    878 
    879      live-image    Perform "make live-image".
    880 
    881      list-arch     Prints a list of valid MACHINE and MACHINE_ARCH settings,
    882                    the default MACHINE_ARCH for each MACHINE, and aliases for
    883                    MACHINE/MACHINE_ARCH pairs, and then exits.  The -m or -a
    884                    options (or both) may be used to specify glob patterns that
    885                    will be used to narrow the list of results; for example,
    886                    "build.sh -m 'evm*' -a '*arm*' list-arch" will list all
    887                    known MACHINE/MACHINE_ARCH values in which either MACHINE
    888                    or ALIAS matches the pattern `evb*', and MACHINE_ARCH
    889                    matches the pattern `*arm*'.
    890 
    891      The following command line options alter the behaviour of the build.sh
    892      operations described above:
    893 
    894      -a arch   Set the value of MACHINE_ARCH to arch.  See the -m option for
    895                more information.
    896 
    897      -B buildid
    898                Set the value of BUILDID to buildid.  This will also append the
    899                build identifier to the name of the "make" wrapper script so
    900                that the resulting name is of the form
    901                "nbmake-MACHINE-BUILDID".
    902 
    903      -C cdextras
    904                Append cdextras to the CDEXTRA variable, which is a space-
    905                separated list of files or directories that will be added to
    906                the CD-ROM image that may be create by the "iso-image" or
    907                "iso-image-source" operations.  Files will be added to the root
    908                of the CD-ROM image, whereas directories will be copied
    909                recursively.  If relative paths are specified, they will be
    910                converted to absolute paths before being used.  Multiple paths
    911                may be specified via multiple -C options, or via a single
    912                option whose argument contains multiple space-separated paths.
    913 
    914      -D dest   Set the value of DESTDIR to dest.  If a relative path is
    915                specified, it will be converted to an absolute path before
    916                being used.
    917 
    918      -E        Set `expert' mode.  This overrides various sanity checks, and
    919                allows: DESTDIR does not have to be set to a non-root path for
    920                builds, and MKUNPRIVED=yes does not have to be set when
    921                building as a non-root user.
    922 
    923                Note: It is highly recommended that you know what you are doing
    924                when you use this option.
    925 
    926      -h        Print a help message.
    927 
    928      -j njob   Run up to njob make(1) subjobs in parallel; passed through to
    929                make(1).  If you see failures for reasons other than running
    930                out of memory while using build.sh with -j, please save
    931                complete build logs so the failures can be analyzed.
    932 
    933                To achieve the fastest builds, -j values between (1 + the
    934                number of CPUs) and (2 * the number of CPUs) are recommended.
    935                Use lower values on machines with limited memory or I/O
    936                bandwidth.
    937 
    938      -M obj    Set MAKEOBJDIRPREFIX to obj.  Unsets MAKEOBJDIR.  See "-O obj"
    939                for more information.
    940 
    941                For instance, if the source directory is /usr/src, a setting of
    942                "-M /usr/obj" will place build-time files under
    943                /usr/obj/usr/src/bin, /usr/obj/usr/src/lib,
    944                /usr/obj/usr/src/usr.bin, and so forth.
    945 
    946                If a relative path is specified, it will be converted to an
    947                absolute path before being used.  build.sh imposes the
    948                restriction that the argument to the -M option must not begin
    949                with a "$" (dollar sign) character; otherwise it would be too
    950                difficult to determine whether the value is an absolute or a
    951                relative path.  If the directory does not already exist,
    952                build.sh will create it.
    953 
    954      -m mach   Set the value of MACHINE to mach, unless the mach argument is
    955                an alias that refers to a MACHINE/MACHINE_ARCH pair, in which
    956                case both MACHINE and MACHINE_ARCH are set from the alias.
    957                Such aliases are interpreted entirely by build.sh; they are not
    958                used by any other part of the build system.  The MACHINE_ARCH
    959                setting implied by mach will override any value of MACHINE_ARCH
    960                in the process environment, but will not override a value set
    961                by the -a option.  All cross builds require -m, but if unset on
    962                a NetBSD host, the host's value of MACHINE will be detected and
    963                used automatically.
    964 
    965                See the list-arch operation for a way to get a list of valid
    966                MACHINE and MACHINE_ARCH settings.
    967 
    968      -N noiselevel
    969                Set the "noisyness" level of the build, by setting MAKEVERBOSE
    970                to noiselevel.
    971 
    972      -n        Show the commands that would be executed by build.sh, but do
    973                not make any changes.  This is similar in concept to "make -n".
    974 
    975      -O obj    Create an appropriate transform macro for MAKEOBJDIR that will
    976                place the built object files under obj.  Unsets
    977                MAKEOBJDIRPREFIX.
    978 
    979                For instance, a setting of "-O /usr/obj" will place build-time
    980                files under /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, and
    981                so forth.
    982 
    983                If a relative path is specified, it will be converted to an
    984                absolute path before being used.  build.sh imposes the
    985                restriction that the argument to the -O option must not contain
    986                a "$" (dollar sign) character.  If the directory does not
    987                already exist, build.sh will create it.
    988 
    989                In normal use, exactly one of the -M or -O options should be
    990                specified.  If neither -M nor -O is specified, then a default
    991                object directory will be chosen according to rules in
    992                <bsd.obj.mk>.  Relying on this default is not recommended
    993                because it is determined by complex rules that are influenced
    994                by the values of several variables and by the location of the
    995                source directory.
    996 
    997                Note that placing the obj directory location outside of the
    998                default source tree hierarchy makes it easier to manually clear
    999                out old files in the event the "make cleandir" operation is
   1000                unable to do so.  (See CAVEATS below.)
   1001 
   1002                Note also that use of one of -M or -O is the only means of
   1003                building multiple machine architecture userlands from the same
   1004                source tree without cleaning between builds (in which case, one
   1005                would specify distinct obj locations for each).
   1006 
   1007      -o        Set the value of MKOBJDIRS to "no".  Otherwise, it will be
   1008                automatically set to "yes".  This default is opposite to the
   1009                behaviour when not using build.sh.
   1010 
   1011      -R rel    Set the value of RELEASEDIR to rel.  If a relative path is
   1012                specified, it will be converted to an absolute path before
   1013                being used.
   1014 
   1015      -r        Remove the contents of DESTDIR and TOOLDIR before building
   1016                (provides a clean starting point).  This will skip deleting
   1017                DESTDIR if building on a native system to the root directory.
   1018 
   1019      -S seed   Change the value of BUILDSEED to seed.  This should rarely be
   1020                necessary.
   1021 
   1022      -T tools  Set the value of TOOLDIR to tools.  If a relative path is
   1023                specified, it will be converted to an absolute path before
   1024                being used.  If set, the bootstrap "make" will only be rebuilt
   1025                if the source files for make(1) have changed.
   1026 
   1027      -U        Set MKUNPRIVED=yes.
   1028 
   1029      -u        Set MKUPDATE=yes.
   1030 
   1031      -V var=[value]
   1032                Set the environment variable var to an optional value.  This is
   1033                propagated to the nbmake wrapper.
   1034 
   1035      -w wrapper
   1036                Create the nbmake wrapper script (see below) in a custom
   1037                location, specified by wrapper.  This allows, for instance, to
   1038                place the wrapper in PATH automatically.  Note that wrapper is
   1039                the full name of the file, not just a directory name.  If a
   1040                relative path is specified, it will be converted to an absolute
   1041                path before being used.
   1042 
   1043      -X x11src
   1044                Set the value of X11SRCDIR to x11src.  If a relative path is
   1045                specified, it will be converted to an absolute path before
   1046                being used.
   1047 
   1048      -x        Set MKX11=yes.
   1049 
   1050      -Y extsrcdir
   1051                Set the value of EXTSRCSRCDIR to extsrcdir.  If a relative path
   1052                is specified, it will be converted to an absolute path before
   1053                being used.
   1054 
   1055      -y        Set MKEXTSRC=yes.
   1056 
   1057      -Z var    Unset ("zap") the environment variable var.  This is propagated
   1058                to the nbmake wrapper.
   1059 
   1060    The "nbmake-MACHINE" wrapper script
   1061      If using the build.sh script to build NetBSD, a nbmake-MACHINE script
   1062      will be created in TOOLDIR/bin upon the first build to assist in building
   1063      subtrees on a cross-compile host.
   1064 
   1065      nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
   1066      the up-to-date version of "nbmake" installed into TOOLDIR/bin with
   1067      several key variables pre-set, including MACHINE, MACHINE_ARCH, and
   1068      TOOLDIR.  nbmake-MACHINE will also set variables specified with -V, and
   1069      unset variables specified with -Z.
   1070 
   1071      This script can be symlinked into a directory listed in PATH, or called
   1072      with an absolute path.
   1073 
   1074 EXAMPLES
   1075      1.   % ./build.sh [options] tools kernel=GENERIC
   1076 
   1077           Build a new toolchain, and use the new toolchain to configure and
   1078           build a new GENERIC kernel.
   1079 
   1080      2.   % ./build.sh [options] -U distribution
   1081 
   1082           Using unprivileged mode, build a complete distribution to a DESTDIR
   1083           directory that build.sh selects (and will display).
   1084 
   1085      3.   # ./build.sh [options] -U install=/
   1086 
   1087           As root, install to / the distribution that was built by example 2.
   1088           Even though this is run as root, -U is required so that the
   1089           permissions stored in DESTDIR/METALOG are correctly applied to the
   1090           files as they're copied to /.
   1091 
   1092      4.   % ./build.sh [options] -U -u release
   1093 
   1094           Using unprivileged mode, build a complete release to DESTDIR and
   1095           RELEASEDIR directories that build.sh selects (and will display).
   1096           MKUPDATE=yes (-u) is set to prevent the "make cleandir", so that if
   1097           this is run after example 2, it doesn't need to redo that portion of
   1098           the release build.
   1099 
   1100 OBSOLETE VARIABLES
   1101      NBUILDJOBS  Use the make(1) option -j instead.
   1102 
   1103      USE_NEW_TOOLCHAIN
   1104                  The new toolchain is now the default.  To disable, use
   1105                  TOOLCHAIN_MISSING=yes.
   1106 
   1107 SEE ALSO
   1108      make(1), hier(7), release(7), etcupdate(8), postinstall(8), sysinst(8),
   1109      pkgsrc/sysutils/cdrtools
   1110 
   1111 HISTORY
   1112      The build.sh based build scheme was introduced for NetBSD 1.6 as
   1113      USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.
   1114 
   1115 CAVEATS
   1116      After significant updates to third-party components in the source tree,
   1117      the "make cleandir" operation may be insufficient to clean out old files
   1118      in object directories.  Instead, one may have to manually remove the
   1119      files.  Consult the UPDATING file for notices concerning this.
   1120 
   1121 NetBSD                          April 13, 2017                          NetBSD
   1122