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