Sync usage with man page.
[netbsd-mini2440.git] / BUILDING
blob68f8f445142f83f9c3c5d668fbf9312730183f72
1 BUILDING(8)             NetBSD System Manager's Manual             BUILDING(8)
3 NAME
4      BUILDING -- Procedure for building NetBSD from source code.
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).
12      This source tree contains a special subtree, ``tools'', which uses the
13      host system to create a build toolchain for the target architecture.  The
14      host system must have at least C and C++ compilers in order to create the
15      toolchain (make is not required); all other tools are created as part of
16      the NetBSD build process.  (See the environment variables section below
17      if you need to override or manually select your compilers.)
19 FILES
20    Source tree layout
21      doc/BUILDING.mdoc
22                     This document (in -mdoc troff format; the original copy).
24      BUILDING       This document (in plaintext).
26      tools/compat/README
27                     Special notes for cross-hosting a NetBSD build on non-
28                     NetBSD platforms.
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.)
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.
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.
45      crypto/dist/, dist/, gnu/dist/
46                     Sources imported verbatim from third parties, without man-
47                     gling the existing build structure.  Other source trees in
48                     bin through usr.sbin use the NetBSD make(1) ``reachover''
49                     Makefile semantics when building these programs for a
50                     native host.
52      distrib/, etc/
53                     Sources for items used when making a full release snap-
54                     shot, such as files installed in DESTDIR/etc on the desti-
55                     nation system, boot media, and release notes.
57      tests/, regress/
58                     Regression test harness.  Can be cross-compiled, but only
59                     run natively.  tests/ uses the atf(7) test framework;
60                     regress/ contains older tests that have not yet been
61                     migrated to atf(7).
63      sys/           NetBSD kernel sources.
65      tools/         ``Reachover'' build structure for the host build tools.
66                     This has a special method of determining out-of-date sta-
67                     tus.
69      bin/ ... usr.sbin/
70                     Sources to the NetBSD userland (non-kernel) programs.  If
71                     any of these directories are missing, they will be skipped
72                     during the build.
74      x11/           ``Reachover'' build structure for X11R6; the source is in
75                     X11SRCDIR.
77      extsrc/        ``Reachover'' build structure for externally added programs
78                     and libraries; the source is in EXTSRCSRCDIR.
80    Build tree layout
81      The NetBSD build tree is described in hier(7), and the release layout is
82      described in release(7).
84 CONFIGURATION
85    Environment variables
86      Several environment variables control the behaviour of NetBSD builds.
88      HOST_SH           Path name to a POSIX-compliant shell.  If this is not
89                        set explicitly, then the default is set using heuris-
90                        tics dependent on the host platform, or from the shell
91                        under which build.sh is executed (if that can be deter-
92                        mined), or using the first copy of sh found in PATH.
93                        If the host system's /bin/sh is not POSIX-compliant, we
94                        suggest that you build using commands like
96                              HOST_SH=/path/to/working/shell
97                              export HOST_SH
98                              ${HOST_SH} build.sh [options]
100      HOST_CC           Path name to C compiler used to create the toolchain.
102      HOST_CXX          Path name to C++ compiler used to create the toolchain.
104      MACHINE           Machine type, e.g., ``macppc''.
106      MACHINE_ARCH      Machine architecture, e.g., ``powerpc''.
108      MAKE              Path name to invoke make(1) as.
110      MAKEFLAGS         Flags to invoke make(1) with.
112      MAKEOBJDIR        Directory to use as the .OBJDIR for the current direc-
113                        tory.  The value is subjected to variable expansion by
114                        make(1).  Typical usage is to set this variable to a
115                        value involving the use of `${.CURDIR:S...}' or
116                        `${.CURDIR:C...}', to derive the value of .OBJDIR from
117                        the value of .CURDIR.  Used only if MAKEOBJDIRPREFIX is
118                        not defined.  MAKEOBJDIR can be provided only in the
119                        environment or via the -O flag of build.sh; it cannot
120                        usefully be set inside a Makefile, including mk.conf or
121                        ${MAKECONF}.
123      MAKEOBJDIRPREFIX  Top level directory of the object directory tree.  The
124                        value is subjected to variable expansion by make(1).
125                        build.sh will create the ${MAKEOBJDIRPREFIX} directory
126                        if necessary, but if make(1) is used without build.sh,
127                        then rules in <bsd.obj.mk> will abort the build if the
128                        ${MAKEOBJDIRPREFIX} directory does not exist.  If the
129                        value is defined and valid, then ${MAKEOBJDIRPRE-
130                        FIX}/${.CURDIR} is used as the .OBJDIR for the current
131                        directory.  The current directory may be read only.
132                        MAKEOBJDIRPREFIX can be provided only in the environ-
133                        ment or via the -M flag of build.sh; it cannot usefully
134                        be set inside a Makefile, including mk.conf or
135                        ${MAKECONF}.
137    "make" variables
138      Several variables control the behavior of NetBSD builds.  Unless other-
139      wise specified, these variables may be set in either the process environ-
140      ment or the make(1) configuration file specified by MAKECONF.
142      BUILDID     Identifier for the build.  The identifier will be appended to
143                  object directory names, and can be consulted in the make(1)
144                  configuration file in order to set additional build parame-
145                  ters, such as compiler flags.
147      BUILDSEED   GCC uses random numbers when compiling C++ code.  This vari-
148                  able seeds the gcc random number generator using the -fran-
149                  dom-seed flag with this value.  By default, it is set to
150                  NetBSD-(majorversion).  Using a fixed value causes C++ bina-
151                  ries to be the same when built from the same sources, result-
152                  ing in identical (reproducible) builds.  Additional informa-
153                  tion is available in the GCC documentation of -frandom-seed.
155      DESTDIR     Directory to contain the built NetBSD system.  If set, spe-
156                  cial options are passed to the compilation tools to prevent
157                  their default use of the host system's /usr/include,
158                  /usr/lib, and so forth.  This pathname must be an absolute
159                  path, and should not end with a slash (/) character.  (For
160                  installation into the system's root directory, set DESTDIR to
161                  an empty string, not to ``/'').  The directory must reside on
162                  a file system which supports long file names and hard links.
164                  Default: Empty string if USETOOLS is ``yes''; unset other-
165                  wise.
167                  Note: build.sh will provide a default of destdir.MACHINE (in
168                  the top-level .OBJDIR) unless run in `expert' mode.
170      EXTSRCSRCDIR
171                  Directory containing sources of externally added programs
172                  and libraries.  If specified, must be an absolute path.
174                  Default: NETBSDRCDIR/../extsrc, if that exists; otherwise
175                  /usr/extsrc.
177      MAKECONF    The name of the make(1) configuration file.  Only settable in
178                  the process environment.
180                  Default: ``/etc/mk.conf''
182      MAKEVERBOSE
183                  Level of verbosity of status messages.  Supported values:
185                  0    No descriptive messages or commands executed by make(1)
186                       are shown.
188                  1    Brief messages are shown describing what is being done,
189                       but the actual commands executed by make(1) are not dis-
190                       played.
192                  2    Descriptive messages are shown as above (prefixed with a
193                       `#'), and ordinary commands performed by make(1) are
194                       displayed.
196                  3    In addition to the above, all commands performed by
197                       make(1) are displayed, even if they would ordinarily
198                       have been hidden through use of the ``@'' prefix in the
199                       relevant makefile.
201                  4    In addition to the above, commands executed by make(1)
202                       are traced through use of the sh(1) ``-x'' flag.
204                  Default: 2
206      MKCATPAGES  Can be set to ``yes'' or ``no''.  Indicates whether prefor-
207                  matted plaintext manual pages will be created during a build.
209                  Default: ``yes''
211      MKCRYPTO    Can be set to ``yes'' or ``no''.  Indicates whether crypto-
212                  graphic code will be included in a build; provided for the
213                  benefit of countries that do not allow strong cryptography.
214                  Will not affect use of the standard low-security password
215                  encryption system, crypt(3).
217                  Default: ``yes''
219      MKDOC       Can be set to ``yes'' or ``no''.  Indicates whether system
220                  documentation destined for DESTDIR/usr/share/doc will be
221                  installed during a build.
223                  Default: ``yes''
225      MKEXTSRC    Can be set to ``yes'' or ``no''.  Indicates whether extsrc is
226                  built from EXTSRCSRCDIR.
228                  Default: ``no''
230      MKHTML      Can be set to ``yes'' or ``no''.  Indicates whether prefor-
231                  matted HTML manual pages will be built and installed
233                  Default: ``yes''
235      MKHOSTOBJ   Can be set to ``yes'' or ``no''.  If set to ``yes'', then for
236                  programs intended to be run on the compile host, the name,
237                  release, and architecture of the host operating system will
238                  be suffixed to the name of the object directory created by
239                  ``make obj''.  (This allows multiple host systems to compile
240                  NetBSD for a single target.)  If set to ``no'', then programs
241                  built to be run on the compile host will use the same object
242                  directory names as programs built to be run on the target.
244                  Default: ``no''
246      MKINFO      Can be set to ``yes'' or ``no''.  Indicates whether GNU Info
247                  files, used for the documentation for most of the compilation
248                  tools, will be created and installed during a build.
250                  Default: ``yes''
252      MKLINT      Can be set to ``yes'' or ``no''.  Indicates whether lint(1)
253                  will be run against portions of the NetBSD source code during
254                  the build, and whether lint libraries will be installed into
255                  DESTDIR/usr/libdata/lint.
257                  Default: ``yes''
259      MKMAN       Can be set to ``yes'' or ``no''.  Indicates whether manual
260                  pages will be installed during a build.
262                  Default: ``yes''
264      MKNLS       Can be set to ``yes'' or ``no''.  Indicates whether Native
265                  Language System locale zone files will be compiled and
266                  installed during a build.
268                  Default: ``yes''
270      MKOBJ       Can be set to ``yes'' or ``no''.  Indicates whether object
271                  directories will be created when running ``make obj''.  If
272                  set to ``no'', then all built files will be located inside
273                  the regular source tree.
275                  Default: ``yes''
277                  Note that setting MKOBJ to ``no'' is not recommended and may
278                  cause problems when updating the tree with cvs(1).
280      MKPIC       Can be set to ``yes'' or ``no''.  Indicates whether shared
281                  objects and libraries will be created and installed during a
282                  build.  If set to ``no'', the entire built system will be
283                  statically linked.
285                  Default: Platform dependent.  As of this writing, all plat-
286                  forms except sh3 default to ``yes''.
288      MKPICINSTALL
289                  Can be set to ``yes'' or ``no''.  Indicates whether the ar(1)
290                  format libraries (lib*_pic.a), used to generate shared
291                  libraries, are installed during a build.
293                  Default: ``yes''
295      MKPROFILE   Can be set to ``yes'' or ``no''.  Indicates whether profiled
296                  libraries (lib*_p.a) will be built and installed during a
297                  build.
299                  Default: ``yes''; however, some platforms turn off MKPROFILE
300                  by default at times due to toolchain problems with profiled
301                  code.
303      MKSHARE     Can be set to ``yes'' or ``no''.  Indicates whether files
304                  destined to reside in DESTDIR/usr/share will be built and
305                  installed during a build.  If set to ``no'', then all of
306                  MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to
307                  ``no'' unconditionally.
309                  Default: ``yes''
311      MKSTRIPIDENT
312                  Can be set to ``yes'' or ``no''.  Indicates whether program
313                  binaries and shared libraries should be built to include RCS
314                  IDs for use with ident(1).
316                  Default: ``no''
318      MKSUBPIXEL  Can be set to ``yes'' or ``no''.  For X builds, decides if
319                  subpixel rendering code in FreeType is turned on.  Turned off
320                  by default because of patent issues.
322                  Default: ``no''
324      MKTTINTERP  Can be set to ``yes'' or ``no''.  For X builds, decides if
325                  the TrueType bytecode interpreter is turned on.  See
326                  http://www.freetype.org/patents.html for details.
328                  Default: ``no''
330      MKUNPRIVED  Can be set to ``yes'' or ``no''.  Indicates whether an
331                  unprivileged install will occur.  The user, group, permis-
332                  sions, and file flags, will not be set on the installed
333                  items; instead the information will be appended to a file
334                  called METALOG in DESTDIR.  The contents of METALOG are used
335                  during the generation of the distribution tar files to ensure
336                  that the appropriate file ownership is stored.
338                  Default: ``no''
340      MKUPDATE    Can be set to ``yes'' or ``no''.  Indicates whether all
341                  install operations intended to write to DESTDIR will compare
342                  file timestamps before installing, and skip the install phase
343                  if the destination files are up-to-date.  This also has
344                  implications on full builds (see next subsection).
346                  Default: ``no''
348      MKX11       Can be set to ``yes'' or ``no''.  Indicates whether X11 is
349                  built from X11SRCDIR.
351                  Default: ``no''
353      TOOLDIR     Directory to hold the host tools, once built.  If specified,
354                  must be an absolute path.  This directory should be unique to
355                  a given host system and NetBSD source tree.  (However, multi-
356                  ple targets may share the same TOOLDIR; the target-dependent
357                  files have unique names.)  If unset, a default based on the
358                  uname(1) information of the host platform will be created in
359                  the .OBJDIR of src.
361                  Default: Unset.
363      USETOOLS    Indicates whether the tools specified by TOOLDIR should be
364                  used as part of a build in progress.  Must be set to ``yes''
365                  if cross-compiling.
367                  yes    Use the tools from TOOLDIR.
369                  no     Do not use the tools from TOOLDIR, but refuse to build
370                         native compilation tool components that are version-
371                         specific for that tool.
373                  never  Do not use the tools from TOOLDIR, even when building
374                         native tool components.  This is similar to the tradi-
375                         tional NetBSD build method, but does not verify that
376                         the compilation tools in use are up-to-date enough in
377                         order to build the tree successfully.  This may cause
378                         build or runtime problems when building the whole
379                         NetBSD source tree.
381                  Default: ``yes'', unless TOOLCHAIN_MISSING is set to ``yes''.
383                  USETOOLS is also set to ``no'' when using <bsd.*.mk> outside
384                  the NetBSD source tree.
386      X11SRCDIR   Directory containing the X11R6 source.  If specified, must be
387                  an absolute path.  The main X11R6 source is found in
388                  X11SRCDIR/xfree/xc.
390                  Default: NETBSDRCDIR/../xsrc, if that exists; otherwise
391                  /usr/xsrc.
393      X11FLAVOUR  The style of X11 cross-built, set to either ``Xorg'' or
394                  ``XFree86''.
396                  Default: ``Xorg'' on amd64, i386, macppc, shark and sparc64
397                  platforms, ``XFree86'' on everything else.
399    "make" variables for full builds
400      These variables only affect the top level ``Makefile'' and do not affect
401      manually building subtrees of the NetBSD source code.
403      INSTALLWORLDDIR  Location for the ``make installworld'' target to install
404                       to.  If specified, must be an absolute path.
406                       Default: ``/''
408      MKOBJDIRS        Can be set to ``yes'' or ``no''.  Indicates whether
409                       object directories will be created automatically (via a
410                       ``make obj'' pass) at the start of a build.
412                       Default: ``no''
414                       If using build.sh, the default is ``yes''.  This may be
415                       set back to ``no'' by giving build.sh the -o option.
417      MKUPDATE         Can be set to ``yes'' or ``no''.  If set, then in addi-
418                       tion to the effects described for MKUPDATE=yes above,
419                       this implies the effects of NOCLEANDIR (i.e., ``make
420                       cleandir'' is avoided).
422                       Default: ``no''
424                       If using build.sh, this may be set by giving the -u
425                       option.
427      NBUILDJOBS       Now obsolete.  Use the make(1) option -j, instead.  See
428                       below.
430                       Default: Unset.
432      NOCLEANDIR       If set, avoids the ``make cleandir'' phase of a full
433                       build.  This has the effect of allowing only changed
434                       files in a source tree to be recompiled.  This can speed
435                       up builds when updating only a few files in the tree.
437                       Default: Unset.
439                       See also MKUPDATE.
441      NODISTRIBDIRS    If set, avoids the ``make distrib-dirs'' phase of a full
442                       build.  This skips running mtree(8) on DESTDIR, useful
443                       on systems where building as an unprivileged user, or
444                       where it is known that the system-wide mtree files have
445                       not changed.
447                       Default: Unset.
449      NOINCLUDES       If set, avoids the ``make includes'' phase of a full
450                       build.  This has the effect of preventing make(1) from
451                       thinking that some programs are out-of-date simply
452                       because the system include files have changed.  However,
453                       this option should not be used when updating the entire
454                       NetBSD source tree arbitrarily; it is suggested to use
455                       MKUPDATE=yes instead in that case.
457                       Default: Unset.
459      RELEASEDIR       If set, specifies the directory to which a release(7)
460                       layout will be written at the end of a ``make release''.
461                       If specified, must be an absolute path.
463                       Default: Unset.
465                       Note: build.sh will provide a default of releasedir (in
466                       the top-level .OBJDIR) unless run in `expert' mode.
468 BUILDING
469    "make" command line options
470      This is not a summary of all the options available to make(1); only the
471      options used most frequently with NetBSD builds are listed here.
473      -j njob    Run up to njob make(1) subjobs in parallel.  Makefiles should
474                 use .WAIT or have explicit dependencies as necessary to
475                 enforce build ordering.
477      -m dir     Specify the default directory for searching for system Make-
478                 file segments, mainly the <bsd.*.mk> files.  When building any
479                 full NetBSD source tree, this should be set to the
480                 ``share/mk'' directory in the source tree.  This is set auto-
481                 matically when building from the top level, or when using
482                 build.sh.
484      -n         Display the commands that would have been executed, but do not
485                 actually execute them.  This will still cause recursion to
486                 take place.
488      -V var     Print make(1)'s idea of the value of var.  Does not build any
489                 targets.
491      var=value  Set the variable var to value, overriding any setting speci-
492                 fied by the process environment, the MAKECONF configuration
493                 file, or the system Makefile segments.
495    "make" targets
496      These default targets may be built by running make(1) in any subtree of
497      the NetBSD source code.  It is recommended that none of these be used
498      from the top level Makefile; as a specific exception, ``make obj'' and
499      ``make cleandir'' are useful in that context.
501      all        Build programs, libraries, and preformatted documentation.
503      clean      Remove program and library object code files.
505      cleandir   Same as clean, but also remove preformatted documentation,
506                 dependency files generated by ``make depend'', and any other
507                 files known to be created at build time.
509      depend     Create dependency files (.depend) containing more detailed
510                 information about the dependencies of source code on header
511                 files.  Allows programs to be recompiled automatically when a
512                 dependency changes.
514      dependall  Does a ``make depend'' immediately followed by a ``make all''.
515                 This improves cache locality of the build since both passes
516                 read the source files in their entirety.
518      distclean  Synonym for cleandir.
520      includes   Build and install system header files.  Typically needed
521                 before any system libraries or programs can be built.
523      install    Install programs, libraries, and documentation into DESTDIR.
524                 Few files will be installed to DESTDIR/dev, DESTDIR/etc,
525                 DESTDIR/root or DESTDIR/var in order to prevent user supplied
526                 configuration data from being overwritten.
528      lint       Run lint(1) against the C source code, where appropriate, and
529                 generate system-installed lint libraries.
531      obj        Create object directories to be used for built files, instead
532                 of building directly in the source tree.
534      tags       Create ctags(1) searchable function lists usable by the ex(1)
535                 and vi(1) text editors.
537    "make" targets for the top level
538      Additional make(1) targets are usable specifically from the top source
539      level to facilitate building the entire NetBSD source tree.
541      build         Build the entire NetBSD system (except the kernel).  This
542                    orders portions of the source tree such that prerequisites
543                    will be built in the proper order.
545      distribution  Do a ``make build'', and then install a full distribution
546                    (which does not include a kernel) into DESTDIR, including
547                    files in DESTDIR/dev, DESTDIR/etc, DESTDIR/root and
548                    DESTDIR/var.
550      buildworld    As per ``make distribution'', except that it ensures that
551                    DESTDIR is not the root directory.
553      installworld  Install the distribution from DESTDIR to INSTALLWORLDDIR,
554                    which defaults to the root directory.  Ensures that
555                    INSTALLWORLDDIR is not the root directory if cross compil-
556                    ing.
558                    The INSTALLSETS environment variable may be set to a list
559                    of distribution sets to be installed.  By default, all sets
560                    except ``etc'' and ``xetc'' are installed, so most files in
561                    INSTALLWORLDDIR/etc will not be installed or modified.
563                    Note: Before performing this operation with
564                    INSTALLWORLDDIR=/, it is highly recommended that you
565                    upgrade your kernel and reboot.  After performing this
566                    operation, it is recommended that you use etcupdate(8) to
567                    update files in INSTALLWORLDDIR/etc and that you use
568                    postinstall(8) to check for inconsistencies (and possibly
569                    to fix them).
571      sets          Create distribution sets from DESTDIR into
572                    RELEASEDIR/RELEASEMACHINEDIR/binary/sets.  Should be run
573                    after ``make distribution'', as ``make build'' alone does
574                    not install all of the required files.
576      sourcesets    Create source sets of the source tree into
577                    RELEASEDIR/source/sets.
579      syspkgs       Create syspkgs from DESTDIR into
580                    RELEASEDIR/RELEASEMACHINEDIR/binary/syspkgs.  Should be run
581                    after ``make distribution'', as ``make build'' alone does
582                    not install all of the required files.
584      release       Do a ``make distribution'', build kernels, distribution
585                    media, and install sets (this as per ``make sets''), and
586                    then package the system into a standard release layout as
587                    described by release(7).  This requires that RELEASEDIR be
588                    set (see above).
590      iso-image     Create a NetBSD installation CD-ROM image in the
591                    RELEASEDIR/iso directory.  The CD-ROM file system will have
592                    a layout as described in release(7).
594                    For most machine types, the CD-ROM will be bootable, and
595                    will automatically run the sysinst(8) menu-based installa-
596                    tion program, which can be used to install or upgrade a
597                    NetBSD system.  Bootable CD-ROMs also contain tools that
598                    may be useful in repairing a damaged NetBSD installation.
600                    Before ``make iso-image'' is attempted, RELEASEDIR must be
601                    populated by ``make release'' or equivalent.
603                    Note that other, smaller, CD-ROM images may be created in
604                    the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom direc-
605                    tory by ``make release''.  These smaller images usually
606                    contain the same tools as the larger images in
607                    RELEASEDIR/iso, but do not contain additional content such
608                    as the distribution sets.
610                    Note that the mac68k port still uses an older method of
611                    creating CD-ROM images.  This requires the mkisofs(1) util-
612                    ity, which is not part of NetBSD, but which can be
613                    installed from pkgsrc/sysutils/cdrtools.
615      iso-image-source
616                    Create a NetBSD installation CD-ROM image in the
617                    RELEASEDIR/iso directory.  The CD-ROM file system will have
618                    a layout as described in release(7).  It will have top
619                    level directories for the machine type and source.
621                    For most machine types, the CD-ROM will be bootable, and
622                    will automatically run the sysinst(8) menu-based installa-
623                    tion program, which can be used to install or upgrade a
624                    NetBSD system.  Bootable CD-ROMs also contain tools that
625                    may be useful in repairing a damaged NetBSD installation.
627                    Before ``make iso-image-source'' is attempted, RELEASEDIR
628                    must be populated by ``make sourcesets release'' or equiva-
629                    lent.
631                    Note that other, smaller, CD-ROM images may be created in
632                    the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom direc-
633                    tory by ``make release''.  These smaller images usually
634                    contain the same tools as the larger images in
635                    RELEASEDIR/iso, but do not contain additional content such
636                    as the distribution sets.
638                    Note that the mac68k port still uses an older method of
639                    creating CD-ROM images.  This requires the mkisofs(1) util-
640                    ity, which is not part of NetBSD, but which can be
641                    installed from pkgsrc/sysutils/cdrtools.
643      regression-tests
644                    Can only be run after building the regression tests in the
645                    directory ``regress''.  Runs those compiled regression
646                    tests on the local host.  Note that most tests are now man-
647                    aged instead using atf(7); this target should probably run
648                    those as well but currently does not.
650    The "build.sh" script
651      This script file is a Bourne shell script designed to build the entire
652      NetBSD system on any host with a Bourne shell in /bin/sh, including many
653      that are not POSIX compliant.  Note that if a host system's /bin/sh is
654      unusually old and broken, the Korn Shell (/bin/ksh), if available, may be
655      a usable alternative.
657      All cross-compile builds, and most native builds, of the entire system
658      should make use of build.sh rather than just running ``make''.  This way,
659      the make(1) program will be bootstrapped properly, in case the host sys-
660      tem has an older or incompatible ``make'' program.
662      When compiling the entire system via build.sh, many make(1) variables are
663      set for you in order to help encapsulate the build process.  In the list
664      of options below, variables that are automatically set by build.sh are
665      noted where applicable.
667      The following operations are supported by build.sh:
669      build         Build the system as per ``make build''.  Before the main
670                    part of the build commences, this command runs the obj
671                    operation (unless the -o option is given), ``make
672                    cleandir'' (unless the -u option is given), and the tools
673                    operation.
675      distribution  Build a full distribution as per ``make distribution''.
676                    This command first runs the build operation.
678      release       Build a full release as per ``make release''.  This command
679                    first runs the distribution operation.
681      makewrapper   Create the nbmake-MACHINE wrapper.  This operation is auto-
682                    matically performed for any of the other operations.
684      cleandir      Perform ``make cleandir''.
686      obj           Perform ``make obj''.
688      tools         Build and install the host tools from src/tools.  This com-
689                    mand will first run ``make obj'' and ``make cleandir'' in
690                    the tools subdirectory unless the -o or -u options (respec-
691                    tively) are given.
693      install=idir  Install the contents of DESTDIR to idir, using ``make
694                    installworld''.  Note that files that are part of the
695                    ``etc'' or ``xetc'' sets will not be installed.
697      kernel=kconf  Build a new kernel.  The kconf argument is the name of a
698                    configuration file suitable for use by config(1).  If kconf
699                    does not contain any `/' characters, the configuration file
700                    is expected to be found in the KERNCONFDIR directory, which
701                    is typically sys/arch/MACHINE/conf.  The new kernel will be
702                    built in a subdirectory of KERNOBJDIR, which is typically
703                    sys/arch/MACHINE/compile or an associated object directory.
705                    This command does not imply the tools command; run the
706                    tools command first unless it is certain that the tools
707                    already exist and are up to date.
709                    This command will run ``make cleandir'' on the kernel in
710                    question first unless the -u option is given.
712      modules       This command will build kernel modules and install them
713                    into DESTDIR.
715      releasekernel=kconf
716                    Install a gzip(1)ed copy of the kernel previously built by
717                    kernel=kconf into
718                    RELEASEDIR/RELEASEMACHINEDIR/binary/kernel, usually as
719                    netbsd-kconf.gz, although the ``netbsd'' prefix is deter-
720                    mined from the ``config'' directives in kconf.
722      sets          Perform ``make sets''.
724      sourcesets    Perform ``make sourcesets''.
726      syspkgs       Perform ``make syspkgs''.
728      iso-image     Perform ``make iso-image''.
730      iso-image-source
731                    Perform ``make iso-image-source''.
733      The following command line options alter the behaviour of the build.sh
734      operations described above:
736      -a arch   Set the value of MACHINE_ARCH to arch.
738      -B buildid
739                Set the value of BUILDID to buildid.  This will also append the
740                build identifier to the name of the ``make'' wrapper script so
741                that the resulting name is of the form
742                ``nbmake-MACHINE-BUILDID''.
744      -C cdextras
745                Append cdextras to the CDEXTRA variable, which is a space-sepa-
746                rated list of files or directories that will be added to the
747                CD-ROM image that may be create by the ``iso-image'' or
748                ``iso-image-source'' operations.  Files will be added to the
749                root of the CD-ROM image, whereas directories will be copied
750                recursively.  If relative paths are specified, they will be
751                converted to absolute paths before being used.  Multiple paths
752                may be specified via multiple -C options, or via a single
753                option whose argument contains multiple space-separated paths.
755      -D dest   Set the value of DESTDIR to dest.  If a relative path is speci-
756                fied, it will be converted to an absolute path before being
757                used.
759      -E        Set `expert' mode.  This overrides various sanity checks, and
760                allows: DESTDIR does not have to be set to a non-root path for
761                builds, and MKUNPRIVED=yes does not have to be set when build-
762                ing as a non-root user.
764                Note: It is highly recommended that you know what you are doing
765                when you use this option.
767      -h        Print a help message.
769      -j njob   Run up to njob make(1) subjobs in parallel; passed through to
770                make(1).  If you see failures for reasons other than running
771                out of memory while using build.sh with -j, please save com-
772                plete build logs so the failures can be analyzed.
774                To achieve the fastest builds, -j values between (1 + the num-
775                ber of CPUs) and (2 * the number of CPUs) are recommended.  Use
776                lower values on machines with limited memory or I/O bandwidth.
778      -M obj    Set MAKEOBJDIRPREFIX to obj.  Unsets MAKEOBJDIR.  See ``-O
779                -obj'' for more information.
781                For instance, if the source directory is /usr/src, a setting of
782                ``-M /usr/obj'' will place build-time files under
783                /usr/obj/usr/src/bin, /usr/obj/usr/src/lib,
784                /usr/obj/usr/src/usr.bin, and so forth.
786                If a relative path is specified, it will be converted to an
787                absolute path before being used.  build.sh imposes the restric-
788                tion that the argument to the -M option must not begin with a
789                ``$'' (dollar sign) character; otherwise it would be too diffi-
790                cult to determine whether the value is an absolute or a rela-
791                tive path.  If the directory does not already exist, build.sh
792                will create it.
794      -m mach   Set the value of MACHINE to mach, except in some special cases
795                listed below.  This will also override any value of
796                MACHINE_ARCH in the process environment with a value deduced
797                from mach, unless -a is specified.  All cross builds require
798                -m, but if unset on a NetBSD host, the host's value of MACHINE
799                will be detected and used automatically.
801                Some machines support multiple values for MACHINE_ARCH.  The
802                following special cases for the mach argument are defined to
803                set the listed values of MACHINE and MACHINE_ARCH:
805                      mach          MACHINE    MACHINE_ARCH
806                      evbarm        evbarm     (not set)
807                      evbarm-eb     evbarm     armeb
808                      evbarm-el     evbarm     arm
809                      evbmips       evbmips    (not set)
810                      evbmips-eb    evbmips    mipseb
811                      evbmips-el    evbmips    mipsel
812                      evbsh3        evbsh3     (not set)
813                      evbsh3-eb     evbsh3     sh3eb
814                      evbsh3-el     evbsh3     sh3el
815                      sbmips        sbmips     (not set)
816                      sbmips-eb     sbmips     mipseb
817                      sbmips-el     sbmips     mipsel
819      -N noiselevel
820                Set the ``noisyness'' level of the build, by setting
821                MAKEVERBOSE to noiselevel.
823      -n        Show the commands that would be executed by build.sh, but do
824                not make any changes.  This is similar in concept to ``make
825                -n''.
827      -O obj    Create an appropriate transform macro for MAKEOBJDIR that will
828                place the built object files under obj.  Unsets
829                MAKEOBJDIRPREFIX.
831                For instance, a setting of ``-O /usr/obj'' will place build-
832                time files under /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin,
833                and so forth.
835                If a relative path is specified, it will be converted to an
836                absolute path before being used.  build.sh imposes the restric-
837                tion that the argument to the -O option must not contain a
838                ``$'' (dollar sign) character.  If the directory does not
839                already exist, build.sh will create it.
841                In normal use, exactly one of the -M or -O options should be
842                specified.  If neither -M nor -O is specified, then a default
843                object directory will be chosen according to rules in
844                <bsd.obj.mk>.  Relying on this default is not recommended
845                because it is determined by complex rules that are influenced
846                by the values of several variables and by the location of the
847                source directory.
849      -o        Set the value of MKOBJDIRS to ``no''.  Otherwise, it will be
850                automatically set to ``yes''.  This default is opposite to the
851                behaviour when not using build.sh.
853      -R rel    Set the value of RELEASEDIR to rel.  If a relative path is
854                specified, it will be converted to an absolute path before
855                being used.
857      -r        Remove the contents of DESTDIR and TOOLDIR before building
858                (provides a clean starting point).  This will skip deleting
859                DESTDIR if building on a native system to the root directory.
861      -S seed   Change the value of BUILDSEED to seed.  This should rarely be
862                necessary.
864      -T tools  Set the value of TOOLDIR to tools.  If a relative path is spec-
865                ified, it will be converted to an absolute path before being
866                used.  If set, the bootstrap ``make'' will only be rebuilt if
867                the source files for make(1) have changed.
869      -U        Set MKUNPRIVED=yes.
871      -u        Set MKUPDATE=yes.
873      -V var=[value]
874                Set the environment variable var to an optional value.  This is
875                propagated to the nbmake wrapper.
877      -w wrapper
878                Create the nbmake wrapper script (see below) in a custom loca-
879                tion, specified by wrapper.  This allows, for instance, to
880                place the wrapper in PATH automatically.  Note that wrapper is
881                the full name of the file, not just a directory name.  If a
882                relative path is specified, it will be converted to an absolute
883                path before being used.
885      -X x11src
886                Set the value of X11SRCDIR to x11src.  If a relative path is
887                specified, it will be converted to an absolute path before
888                being used.
890      -x        Set MKX11=yes.
892      -Y extsrcsrc
893                Set the value of EXTSRCSRCDIR to extsrcsrc.  If a relative path is
894                specified, it will be converted to an absolute path before
895                being used.
897      -y        Set MKEXTSRC=yes.
899      -Z var    Unset ("zap") the environment variable var.  This is propagated
900                to the nbmake wrapper.
902    The "nbmake-MACHINE" wrapper script
903      If using the build.sh script to build NetBSD, a nbmake-MACHINE script
904      will be created in TOOLDIR/bin upon the first build to assist in building
905      subtrees on a cross-compile host.
907      nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
908      the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with sev-
909      eral key variables pre-set, including MACHINE, MACHINE_ARCH, and TOOLDIR.
910      nbmake-MACHINE will also set variables specified with -V, and unset vari-
911      ables specified with -Z.
913      This script can be symlinked into a directory listed in PATH, or called
914      with an absolute path.
916 EXAMPLES
917      1.   % ./build.sh [options] tools kernel=GENERIC
919           Build a new toolchain, and use the new toolchain to configure and
920           build a new GENERIC kernel.
922      2.   % ./build.sh [options] -U distribution
924           Using unprivileged mode, build a complete distribution to a DESTDIR
925           directory that build.sh selects (and will display).
927      3.   # ./build.sh [options] -U install=/
929           As root, install to / the distribution that was built by example 2.
930           Even though this is run as root, -U is required so that the permis-
931           sions stored in DESTDIR/METALOG are correctly applied to the files
932           as they're copied to /.
934      4.   % ./build.sh [options] -U -u release
936           Using unprivileged mode, build a complete release to DESTDIR and
937           RELEASEDIR directories that build.sh selects (and will display).
938           MKUPDATE=yes (-u) is set to prevent the ``make cleandir'', so that
939           if this is run after example 2, it doesn't need to redo that portion
940           of the release build.
942 OBSOLETE VARIABLES
943      NBUILDJOBS  Use the make(1) option -j instead.
945      USE_NEW_TOOLCHAIN
946                  The new toolchain is now the default.  To disable, use
947                  TOOLCHAIN_MISSING=yes.
949 SEE ALSO
950      make(1), hier(7), release(7), etcupdate(8), postinstall(8), sysinst(8),
951      pkgsrc/sysutils/cdrtools
953 HISTORY
954      The build.sh based build scheme was introduced for NetBSD 1.6 as
955      USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.
957 NetBSD                            May 1, 2009                           NetBSD