BUILDING revision 1.54
11.1StvBUILDING(8)             NetBSD System Manager's Manual             BUILDING(8)
21.1Stv
31.1StvNAME
41.52Sjmc     BUILDING -- Procedure for building NetBSD from source code.
51.1Stv
61.1StvSTATUS
71.1Stv     This document is a work-in-progress.  As such, the information described
81.1Stv     here may not match the reality of the build system as of this writing.
91.1Stv     Once this document is completely in sync with reality, this paragraph
101.1Stv     will be removed.
111.1Stv
121.44Slukem     Discrepancies between this documentation and the current reality of
131.44Slukem     implementation are noted specially, as with the note below:
141.1Stv
151.1Stv     Note: This document applies only to platforms which use the new toolchain
161.15Slukem     as indicated by the default setting of TOOLCHAIN_MISSING in <bsd.own.mk>.
171.5Stv     Platforms which have not yet been switched to the new toolchain should
181.5Stv     continue building traditionally, using the notes specified in the file
191.5Stv     UPDATING.
201.1Stv
211.1StvREQUIREMENTS
221.1Stv     NetBSD is designed to be buildable on most POSIX-compliant host systems.
231.1Stv     The basic build procedure is the same whether compiling natively (on the
241.1Stv     same NetBSD architecture) or cross compiling (on another architecture or
251.1Stv     OS).
261.1Stv
271.1Stv     This source tree contains a special subtree, ``tools'', which uses the
281.1Stv     host system to create a build toolchain for the target architecture.  The
291.1Stv     host system must have at least C and C++ compilers in order to create the
301.1Stv     toolchain (make is not required); all other tools are created as part of
311.53Sreed     the NetBSD build process.  (See the environment variables section below
321.53Sreed     if you need to override or manually select your compilers.)
331.1Stv
341.1StvFILES
351.1Stv   Source tree layout
361.17Swiz     doc/BUILDING.mdoc
371.17Swiz                    This document (in -mdoc troff format; the original copy).
381.1Stv
391.2Swiz     BUILDING       This document (in plaintext).
401.1Stv
411.48Sjmc     tools/compat/README
421.48Sjmc                    Special notes for cross-hosting a NetBSD build on non-
431.48Sjmc                    NetBSD platforms.
441.48Sjmc
451.44Slukem     Makefile       The main Makefile for NetBSD; should only be run for
461.44Slukem                    native builds with an appropriately up-to-date version of
471.1Stv                    NetBSD make(1).  (For building from out-of-date systems or
481.1Stv                    on a non-native host, see the build.sh shell script.)
491.1Stv
501.1Stv     UPDATING       Special notes for updating from an earlier revision of
511.1Stv                    NetBSD.  It is important to read this file before every
521.1Stv                    build of an updated source tree.
531.1Stv
541.1Stv     build.sh       Bourne-compatible shell script used for building the host
551.1Stv                    build tools and the NetBSD system from scratch.  Can be
561.1Stv                    used for both native and cross builds, and should be used
571.1Stv                    instead of make(1) for any source tree that is updated and
581.1Stv                    recompiled regularly.
591.1Stv
601.1Stv     crypto/dist/, dist/, gnu/dist/
611.1Stv                    Sources imported verbatim from third parties, without man-
621.1Stv                    gling the existing build structure.  Other source trees in
631.1Stv                    bin through usr.sbin use the NetBSD make(1) ``reachover''
641.44Slukem                    Makefile semantics when building these programs for a
651.44Slukem                    native host.
661.1Stv
671.1Stv     distrib/, etc/
681.1Stv                    Sources for items used when making a full release snap-
691.27Slukem                    shot, such as files installed in DESTDIR/etc on the desti-
701.27Slukem                    nation system, boot media, and release notes.
711.1Stv
721.1Stv     regress/       Regression test harness.  Can be cross-compiled, but only
731.1Stv                    run natively.
741.1Stv
751.1Stv     sys/           NetBSD kernel sources.
761.1Stv
771.1Stv     tools/         ``Reachover'' build structure for the host build tools.
781.1Stv                    This has a special method of determining out-of-date sta-
791.1Stv                    tus.
801.1Stv
811.1Stv     bin/ ... usr.sbin/
821.1Stv                    Sources to the NetBSD userland (non-kernel) programs.  If
831.1Stv                    any of these directories are missing, they will be skipped
841.1Stv                    during the build.
851.1Stv
861.49Slukem     x11/           ``Reachover'' build structure for X11R6; the source is in
871.49Slukem                    X11SRCDIR.
881.49Slukem
891.1Stv   Build tree layout
901.1Stv     The NetBSD build tree is described in hier(7), and the release layout is
911.1Stv     described in release(7).
921.1Stv
931.1StvCONFIGURATION
941.8Slukem   Environment variables
951.8Slukem     Several environment variables control the behaviour of NetBSD builds.
961.8Slukem
971.53Sreed     HOST_CC           Path name to C compiler used to create the toolchain.
981.53Sreed
991.53Sreed     HOST_CXX          Path name to C++ compiler used to create the toolchain.
1001.53Sreed
1011.8Slukem     MACHINE           Machine type.
1021.8Slukem
1031.8Slukem     MACHINE_ARCH      Machine architecture.
1041.8Slukem
1051.8Slukem     MAKE              Path name to invoke make(1) as.
1061.8Slukem
1071.8Slukem     MAKEFLAGS         Flags to invoke make(1) with.
1081.8Slukem
1091.8Slukem     MAKEOBJDIR        Directory to use as the .OBJDIR for the current direc-
1101.8Slukem                       tory.  Used only if MAKEOBJDIRPREFIX is not defined.
1111.36Slukem                       MAKEOBJDIR can only be provided in the environment or
1121.41Slukem                       via the -O flag of build.sh.
1131.8Slukem
1141.8Slukem     MAKEOBJDIRPREFIX  Top level directory of the object directory tree.  If
1151.8Slukem                       this is defined, ${MAKEOBJDIRPREFIX}/${.CURDIR} is used
1161.8Slukem                       as the .OBJDIR for the current directory.  The current
1171.8Slukem                       directory may be read only.  MAKEOBJDIRPREFIX can only
1181.36Slukem                       be provided in the environment or via the -M flag of
1191.36Slukem                       build.sh.
1201.8Slukem
1211.1Stv   "make" variables
1221.1Stv     Several variables control the behavior of NetBSD builds.  Unless other-
1231.1Stv     wise specified, these variables may be set in either the process environ-
1241.1Stv     ment or the make(1) configuration file specified by MAKECONF.
1251.1Stv
1261.9Sthorpej     BUILDID     Identifier for the build.  The identifier will be appended to
1271.9Sthorpej                 object directory names, and can be consulted in the make(1)
1281.9Sthorpej                 configuration file in order to set additional build parame-
1291.9Sthorpej                 ters, such as compiler flags.
1301.9Sthorpej
1311.1Stv     DESTDIR     Directory to contain the built NetBSD system.  If set, spe-
1321.1Stv                 cial options are passed to the compilation tools to prevent
1331.1Stv                 their default use of the host system's /usr/include,
1341.1Stv                 /usr/lib, and so forth.  This pathname should not end with a
1351.1Stv                 slash (/) character (for installation into the system's root
1361.7Slukem                 directory, set DESTDIR to an empty string).  The directory
1371.7Slukem                 must reside on a file system which supports long file names
1381.7Slukem                 and hard links.
1391.1Stv
1401.1Stv                 Default: Empty string if USETOOLS is ``yes''; unset other-
1411.1Stv                 wise.
1421.1Stv
1431.30Slukem                 Note: build.sh will provide a default of destdir.MACHINE (in
1441.30Slukem                 the top-level .OBJDIR) unless run in `expert' mode
1451.30Slukem
1461.1Stv     MAKECONF    The name of the make(1) configuration file.  Only settable in
1471.1Stv                 the process environment.
1481.1Stv
1491.1Stv                 Default: ``/etc/mk.conf''
1501.1Stv
1511.45Slukem     MAKEVERBOSE
1521.45Slukem                 Level of verbosity of status messages.  Supported values:
1531.45Slukem
1541.45Slukem                 0    No descriptive messages are shown.
1551.45Slukem
1561.45Slukem                 1    Descriptive messages are shown.
1571.45Slukem
1581.45Slukem                 2    Descriptive messages (prefixed with a `#') and command
1591.45Slukem                      output is not suppressed.
1601.45Slukem
1611.45Slukem                 Default: 2
1621.45Slukem
1631.1Stv     MKCATPAGES  Can be set to ``yes'' or ``no''.  Indicates whether prefor-
1641.1Stv                 matted plaintext manual pages will be created during a build.
1651.1Stv
1661.1Stv                 Default: ``yes''
1671.1Stv
1681.1Stv     MKCRYPTO    Can be set to ``yes'' or ``no''.  Indicates whether crypto-
1691.1Stv                 graphic code will be included in a build; provided for the
1701.1Stv                 benefit of countries that do not allow strong cryptography.
1711.44Slukem                 Will not affect use of the standard low-security password
1721.44Slukem                 encryption system, crypt(3).
1731.1Stv
1741.1Stv                 Default: ``yes''
1751.1Stv
1761.1Stv     MKDOC       Can be set to ``yes'' or ``no''.  Indicates whether system
1771.44Slukem                 documentation destined for DESTDIR/usr/share/doc will be
1781.44Slukem                 installed during a build.
1791.1Stv
1801.1Stv                 Default: ``yes''
1811.1Stv
1821.4Stv     MKHOSTOBJ   Can be set to ``yes'' or ``no''.  If set to ``yes'', then for
1831.4Stv                 programs intended to be run on the compile host, the name,
1841.4Stv                 release, and architecture of the host operating system will
1851.4Stv                 be suffixed to the name of the object directory created by
1861.4Stv                 ``make obj''.  (This allows multiple host systems to compile
1871.4Stv                 NetBSD for a single target.)  If set to ``no'', then programs
1881.4Stv                 built to be run on the compile host will use the same object
1891.4Stv                 directory names as programs built to be run on the target.
1901.4Stv
1911.4Stv                 Default: ``no''
1921.4Stv
1931.1Stv     MKINFO      Can be set to ``yes'' or ``no''.  Indicates whether GNU Info
1941.1Stv                 files, used for the documentation for most of the compilation
1951.1Stv                 tools, will be created and installed during a build.
1961.1Stv
1971.1Stv                 Default: ``yes''
1981.1Stv
1991.1Stv     MKLINT      Can be set to ``yes'' or ``no''.  Indicates whether lint(1)
2001.1Stv                 will be run against portions of the NetBSD source code during
2011.1Stv                 the build, and whether lint libraries will be installed into
2021.27Slukem                 DESTDIR/usr/libdata/lint.
2031.1Stv
2041.1Stv                 Default: ``yes''
2051.1Stv
2061.1Stv     MKMAN       Can be set to ``yes'' or ``no''.  Indicates whether manual
2071.1Stv                 pages will be installed during a build.
2081.1Stv
2091.1Stv                 Default: ``yes''
2101.1Stv
2111.1Stv     MKNLS       Can be set to ``yes'' or ``no''.  Indicates whether Native
2121.44Slukem                 Language System locale zone files will be compiled and
2131.44Slukem                 installed during a build.
2141.1Stv
2151.1Stv                 Default: ``yes''
2161.1Stv
2171.1Stv     MKOBJ       Can be set to ``yes'' or ``no''.  Indicates whether object
2181.1Stv                 directories will be created when running ``make obj''.  If
2191.1Stv                 set to ``no'', then all built files will be located inside
2201.1Stv                 the regular source tree.
2211.1Stv
2221.1Stv                 Default: ``yes''
2231.1Stv
2241.1Stv     MKPIC       Can be set to ``yes'' or ``no''.  Indicates whether shared
2251.1Stv                 objects and libraries will be created and installed during a
2261.1Stv                 build.  If set to ``no'', the entire built system will be
2271.1Stv                 statically linked.
2281.1Stv
2291.1Stv                 Default: Platform dependent.  As of this writing, all plat-
2301.1Stv                 forms except sh3 default to ``yes''.
2311.1Stv
2321.1Stv     MKPICINSTALL
2331.1Stv                 Can be set to ``yes'' or ``no''.  Indicates whether the ar(1)
2341.44Slukem                 format libraries (lib*_pic.a), used to generate shared
2351.44Slukem                 libraries, are installed during a build.
2361.1Stv
2371.1Stv                 Default: ``yes''
2381.1Stv
2391.1Stv     MKPROFILE   Can be set to ``yes'' or ``no''.  Indicates whether profiled
2401.1Stv                 libraries (lib*_p.a) will be built and installed during a
2411.1Stv                 build.
2421.1Stv
2431.1Stv                 Default: ``yes''; however, some platforms turn off MKPROFILE
2441.1Stv                 by default at times due to toolchain problems with profiled
2451.1Stv                 code.
2461.1Stv
2471.1Stv     MKSHARE     Can be set to ``yes'' or ``no''.  Indicates whether files
2481.44Slukem                 destined to reside in DESTDIR/usr/share will be built and
2491.44Slukem                 installed during a build.  If set to ``no'', then all of
2501.27Slukem                 MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to
2511.27Slukem                 ``no'' unconditionally.
2521.1Stv
2531.1Stv                 Default: ``yes''
2541.1Stv
2551.50Swiz     MKTTINTERP  Can be set to ``yes'' or ``no''.  For X builds, decides if
2561.50Swiz                 the TrueType bytecode interpreter is turned on.  See
2571.50Swiz                 http://www.freetype.org/patents.html for details.
2581.50Swiz
2591.50Swiz                 Default: ``no''
2601.50Swiz
2611.44Slukem     MKUNPRIVED  Can be set to ``yes'' or ``no''.  Indicates whether an
2621.44Slukem                 unprivileged install will occur.  The user, group, permis-
2631.52Sjmc                 sions, and file flags, will not be set on the installed
2641.52Sjmc                 items; instead the information will be appended to a file
2651.52Sjmc                 called METALOG in DESTDIR.  The contents of METALOG are used
2661.52Sjmc                 during the generation of the distribution tar files to ensure
2671.52Sjmc                 that the appropriate file ownership is stored.
2681.38Slukem
2691.38Slukem                 Default: ``no''
2701.38Slukem
2711.44Slukem     MKUPDATE    Can be set to ``yes'' or ``no''.  Indicates whether all
2721.44Slukem                 install operations intended to write to DESTDIR will compare
2731.38Slukem                 file timestamps before installing, and skip the install phase
2741.44Slukem                 if the destination files are up-to-date.  This also has
2751.44Slukem                 implications on full builds (see next subsection).
2761.38Slukem
2771.38Slukem                 Default: ``no''
2781.38Slukem
2791.49Slukem     MKX11       Can be set to ``yes'' or ``no''.  Indicates whether X11R6 is
2801.49Slukem                 built from X11SRCDIR.
2811.49Slukem
2821.49Slukem                 Default: ``no''
2831.49Slukem
2841.1Stv     TOOLDIR     Directory to hold the host tools, once built.  This directory
2851.1Stv                 should be unique to a given host system and NetBSD source
2861.1Stv                 tree.  (However, multiple targets may share the same TOOLDIR;
2871.1Stv                 the target-dependent files have unique names.)  If unset, a
2881.1Stv                 default based on the uname(1) information of the host plat-
2891.39Slukem                 form will be created in the .OBJDIR of src.
2901.1Stv
2911.1Stv                 Default: Unset.
2921.1Stv
2931.1Stv     USETOOLS    Indicates whether the tools specified by TOOLDIR should be
2941.1Stv                 used as part of a build in progress.  Must be set to ``yes''
2951.1Stv                 if cross-compiling.
2961.1Stv
2971.1Stv                 yes    Use the tools from TOOLDIR.
2981.1Stv
2991.1Stv                 no     Do not use the tools from TOOLDIR, but refuse to build
3001.1Stv                        native compilation tool components that are version-
3011.1Stv                        specific for that tool.
3021.1Stv
3031.1Stv                 never  Do not use the tools from TOOLDIR, even when building
3041.1Stv                        native tool components.  This is similar to the tradi-
3051.1Stv                        tional NetBSD build method, but does not verify that
3061.1Stv                        the compilation tools in use are up-to-date enough in
3071.1Stv                        order to build the tree successfully.  This may cause
3081.1Stv                        build or runtime problems when building the whole
3091.1Stv                        NetBSD source tree.
3101.1Stv
3111.1Stv                 Default: ``yes'' if building all or part of a whole NetBSD
3121.1Stv                 source tree (detected automatically); ``no'' otherwise (to
3131.44Slukem                 preserve traditional semantics of the <bsd.*.mk> make(1)
3141.44Slukem                 include files).
3151.1Stv
3161.49Slukem     X11SRCDIR   Directory containing the X11R6 source.  The main X11R6 source
3171.49Slukem                 is found in X11SRCDIR/xfree/xc.
3181.49Slukem
3191.49Slukem                 Default: ``/usr/xsrc''
3201.49Slukem
3211.1Stv   "make" variables for full builds
3221.7Slukem     These variables only affect the top level ``Makefile'' and do not affect
3231.7Slukem     manually building subtrees of the NetBSD source code.
3241.1Stv
3251.20Slukem     INSTALLWORLDDIR  Location for the ``make installworld'' target to install
3261.20Slukem                      to.
3271.1Stv
3281.20Slukem                      Default: ``/''
3291.1Stv
3301.44Slukem     MKOBJDIRS        Can be set to ``yes'' or ``no''.  Indicates whether
3311.44Slukem                      object directories will be created automatically (via a
3321.20Slukem                      ``make obj'' pass) at the start of a build.
3331.1Stv
3341.34Slukem                      Default: ``no''
3351.1Stv
3361.38Slukem     MKUPDATE         Can be set to ``yes'' or ``no''.  If set, then in addi-
3371.38Slukem                      tion to the effects described for MKUPDATE=yes above,
3381.38Slukem                      this implies the effects of NOCLEANDIR (i.e., ``make
3391.38Slukem                      cleandir'' is avoided).
3401.38Slukem
3411.38Slukem                      Default: ``no''
3421.38Slukem
3431.20Slukem     NBUILDJOBS       Now obsolete.  Use the make(1) option -j, instead (see
3441.20Slukem                      below)
3451.1Stv
3461.20Slukem                      Default: Unset.
3471.1Stv
3481.20Slukem     NOCLEANDIR       If set, avoids the ``make cleandir'' phase of a full
3491.20Slukem                      build.  This has the effect of allowing only changed
3501.20Slukem                      files in a source tree to be recompiled.  This can speed
3511.20Slukem                      up builds when updating only a few files in the tree.
3521.1Stv
3531.20Slukem                      Default: Unset.
3541.1Stv
3551.20Slukem     NODISTRIBDIRS    If set, avoids the ``make distrib-dirs'' phase of a full
3561.20Slukem                      build.  This skips running mtree(8) on DESTDIR, useful
3571.20Slukem                      on systems where building as an unprivileged user, or
3581.20Slukem                      where it is known that the system-wide mtree files have
3591.20Slukem                      not changed.
3601.1Stv
3611.20Slukem                      Default: Unset.
3621.1Stv
3631.20Slukem     NOINCLUDES       If set, avoids the ``make includes'' phase of a full
3641.20Slukem                      build.  This has the effect of preventing make(1) from
3651.44Slukem                      thinking that some programs are out-of-date simply
3661.44Slukem                      because the system include files have changed.  However,
3671.20Slukem                      this option should not be used when updating the entire
3681.20Slukem                      NetBSD source tree arbitrarily; it is suggested to use
3691.38Slukem                      MKUPDATE=yes in that case.
3701.1Stv
3711.20Slukem                      Default: Unset.
3721.1Stv
3731.20Slukem     RELEASEDIR       If set, specifies the directory to which a release(7)
3741.20Slukem                      layout will be written at the end of a ``make release''.
3751.20Slukem
3761.20Slukem                      Default: Unset.
3771.20Slukem
3781.30Slukem                      Note: build.sh will provide a default of releasedir (in
3791.30Slukem                      the top-level .OBJDIR) unless run in `expert' mode
3801.30Slukem
3811.1StvBUILDING
3821.1Stv   "make" command line options
3831.52Sjmc     This is not a summary of all the options available to make(1); only the
3841.52Sjmc     options used most frequently with NetBSD builds are listed here.
3851.1Stv
3861.10Ssommerfe     -j njob    Run up to njob make(1) subjobs in parallel.  Makefiles should
3871.52Sjmc                use .WAIT or have explicit dependencies as necessary to
3881.44Slukem                enforce build ordering.  If you see build failures with -j,
3891.10Ssommerfe                please save complete build logs so the failures can be ana-
3901.10Ssommerfe                lyzed.
3911.10Ssommerfe
3921.1Stv     -m dir     Specify the default directory for searching for system Make-
3931.1Stv                file segments, mainly the <bsd.*.mk> files.  When building any
3941.1Stv                full NetBSD source tree, this should be set to the
3951.1Stv                ``share/mk'' directory in the source tree.  (This is set auto-
3961.1Stv                matically when building from the top level.)
3971.1Stv
3981.1Stv     -n         Display the commands that would have been executed, but do not
3991.1Stv                actually execute them.  This will still cause recursion to
4001.1Stv                take place.
4011.1Stv
4021.47Szuntum     -V var     Print make(1)'s idea of the value of var.  Does not build any
4031.1Stv                targets.
4041.1Stv
4051.1Stv     var=value  Set the variable var to value, overriding any setting speci-
4061.1Stv                fied by the process environment, the MAKECONF configuration
4071.1Stv                file, or the system Makefile segments.
4081.1Stv
4091.1Stv   "make" targets
4101.1Stv     These default targets may be built by running make(1) in any subtree of
4111.1Stv     the NetBSD source code.  It is recommended that none of these be used
4121.1Stv     from the top level Makefile; as a specific exception, ``make obj'' and
4131.1Stv     ``make cleandir'' are useful in that context.
4141.1Stv
4151.1Stv     all        Build programs, libraries, and preformatted documentation.
4161.1Stv
4171.1Stv     clean      Remove program and library object code files.
4181.1Stv
4191.44Slukem     cleandir   Same as clean, but also remove preformatted documentation,
4201.44Slukem                dependency files generated by ``make depend'', and any other
4211.49Slukem                files known to be created at build time.
4221.1Stv
4231.44Slukem     depend     Create dependency files (.depend) containing more detailed
4241.44Slukem                information about the dependencies of source code on header
4251.1Stv                files.  Allows programs to be recompiled automatically when a
4261.1Stv                dependency changes.
4271.1Stv
4281.1Stv     dependall  Does a ``make depend'' immediately followed by a ``make all''.
4291.10Ssommerfe                This improves cache locality of the build since both passes
4301.10Ssommerfe                read the source files in their entirety.
4311.1Stv
4321.49Slukem     distclean  Synonym for cleandir.
4331.49Slukem
4341.44Slukem     includes   Build and install system header files.  Typically needed
4351.44Slukem                before any system libraries or programs can be built.
4361.1Stv
4371.1Stv     install    Install programs, libraries, and documentation into DESTDIR.
4381.27Slukem                Few files will be installed to DESTDIR/dev, DESTDIR/etc,
4391.27Slukem                DESTDIR/root or DESTDIR/var in order to prevent user supplied
4401.27Slukem                configuration data from being overwritten.
4411.1Stv
4421.1Stv     lint       Run lint(1) against the C source code, where appropriate, and
4431.1Stv                generate system-installed lint libraries.
4441.1Stv
4451.1Stv     obj        Create object directories to be used for built files, instead
4461.1Stv                of building directly in the source tree.
4471.1Stv
4481.1Stv     tags       Create ctags(1) searchable function lists usable by the ex(1)
4491.1Stv                and vi(1) text editors.
4501.1Stv
4511.1Stv   "make" targets for the top level
4521.1Stv     Additional make(1) targets are usable specifically from the top source
4531.1Stv     level to facilitate building the entire NetBSD source tree.
4541.1Stv
4551.20Slukem     build         Build the entire NetBSD system.  This orders portions of
4561.20Slukem                   the source tree such that prerequisites will be built in
4571.20Slukem                   the proper order.
4581.20Slukem
4591.20Slukem     distribution  Do a ``make build'', and then install a full distribution
4601.27Slukem                   into DESTDIR, including files in DESTDIR/dev, DESTDIR/etc,
4611.27Slukem                   DESTDIR/root and DESTDIR/var.
4621.20Slukem
4631.20Slukem     buildworld    As per ``make distribution'', except that it ensures that
4641.20Slukem                   DESTDIR is not the root directory.
4651.20Slukem
4661.20Slukem     installworld  Install the distribution from DESTDIR to INSTALLWORLDDIR
4671.20Slukem                   (which defaults to the root directory).  Ensures that
4681.52Sjmc                   INSTALLWORLDDIR is not the root directory if cross compil-
4691.20Slukem                   ing.
4701.20Slukem
4711.20Slukem                   Note: It is highly recommended that you upgrade your kernel
4721.20Slukem                   and reboot before performing this operation.
4731.20Slukem
4741.25Slukem     sets          Create distribution sets from DESTDIR into
4751.25Slukem                   RELEASEDIR/MACHINE/binary/sets.  Should be run after ``make
4761.25Slukem                   distribution'' (as ``make build'' does not install all of
4771.25Slukem                   the required files).
4781.25Slukem
4791.31Slukem     sourcesets    Create source sets of the source tree into
4801.31Slukem                   RELEASEDIR/source/sets.
4811.31Slukem
4821.54Sapb     syspkgs       Create syspkgs from DESTDIR into
4831.54Sapb                   RELEASEDIR/MACHINE/binary/syspkgs.  Should be run after
4841.54Sapb                   ``make distribution'' (as ``make build'' does not install
4851.54Sapb                   all of the required files).
4861.54Sapb
4871.44Slukem     release       Do a ``make distribution'', build kernels, distribution
4881.44Slukem                   media, and install sets (this as per ``make sets''), and
4891.44Slukem                   then package the system into a standard release layout as
4901.44Slukem                   described by release(7).  This requires that RELEASEDIR be
4911.25Slukem                   set (see above).
4921.1Stv
4931.1Stv     regression-tests
4941.20Slukem                   Can only be run after building the regression tests in the
4951.20Slukem                   directory ``regress''.  Runs the compiled regression tests
4961.20Slukem                   on the local host.
4971.1Stv
4981.1Stv   The "build.sh" script
4991.1Stv     This script file is a Bourne shell script designed to build the entire
5001.1Stv     NetBSD system on any host with a Bourne shell in /bin/sh, including many
5011.1Stv     that are not POSIX compliant.  Note that if a host system's /bin/sh is
5021.1Stv     unusually old and broken, the Korn Shell (/bin/ksh), if available, may be
5031.1Stv     a usable alternative.
5041.1Stv
5051.1Stv     All cross-compile builds, and most native builds, of the entire system
5061.1Stv     should make use of build.sh rather than just running ``make''.  This way,
5071.1Stv     the make(1) program will be bootstrapped properly, in case the host sys-
5081.1Stv     tem has an older or incompatible ``make'' program.
5091.1Stv
5101.1Stv     When compiling the entire system via build.sh, many make(1) variables are
5111.1Stv     set for you in order to help encapsulate the build process.  In the list
5121.1Stv     of options below, variables that are automatically set by build.sh are
5131.1Stv     noted where applicable.
5141.1Stv
5151.22Slukem     The following operations are supported by build.sh:
5161.22Slukem
5171.44Slukem     build         Build the system as per ``make build''.  This option
5181.44Slukem                   implies the obj and tools operations.
5191.22Slukem
5201.22Slukem     distribution  Build a full distribution as per ``make distribution''.
5211.22Slukem                   This option implies the build operation.
5221.22Slukem
5231.22Slukem     release       Build a full release as per ``make release''.  This option
5241.22Slukem                   implies the distribution operation.
5251.22Slukem
5261.23Slukem     makewrapper   Create the nbmake-MACHINE wrapper.  This operation is auto-
5271.23Slukem                   matically performed for any of the other operations.
5281.23Slukem
5291.22Slukem     obj           Perform ``make obj''.
5301.22Slukem
5311.22Slukem     tools         Build and install the host tools from src/tools.
5321.22Slukem
5331.35Slukem     install=idir  Install the contents of DESTDIR to idir, using ``make
5341.35Slukem                   installworld''.
5351.35Slukem
5361.22Slukem     kernel=kconf  Build a new kernel.  The kconf argument is the name of a
5371.54Sapb                   configuration file suitable for use by config(1).  If kconf
5381.22Slukem                   does not contain any `/' characters, the configuration file
5391.22Slukem                   is expected to be found in the KERNCONFDIR directory, which
5401.22Slukem                   is typically sys/arch/MACHINE/conf.  The new kernel will be
5411.22Slukem                   built in a subdirectory of KERNOBJDIR, which is typically
5421.22Slukem                   sys/arch/MACHINE/compile or an associated object directory.
5431.22Slukem                   In order to ensure that the kernel is built using up-to-
5441.22Slukem                   date tools, it is strongly recommended that the tools be
5451.22Slukem                   rebuilt (using the tools operation).
5461.22Slukem
5471.35Slukem     releasekernel=kconf
5481.35Slukem                   Install a gzip(1)ed copy of the kernel built by
5491.35Slukem                   kernel=kconf into RELEASEDIR/MACHINE/binary/kernel, usually
5501.44Slukem                   as netbsd-kconf.gz, although the ``netbsd'' prefix is
5511.44Slukem                   determined from the ``config'' directives in kconf.
5521.24Slukem
5531.24Slukem     sets          Perform ``make sets''.
5541.31Slukem
5551.31Slukem     sourcesets    Perform ``make sourcesets''.
5561.22Slukem
5571.54Sapb     syspkgs       Perform ``make syspkgs''.
5581.54Sapb
5591.51Swiz     The following command line options alter the behaviour of the build.sh
5601.51Swiz     operations described above:
5611.1Stv
5621.1Stv     -a arch   Set the value of MACHINE_ARCH to arch.
5631.9Sthorpej
5641.9Sthorpej     -B buildid
5651.9Sthorpej               Set the value of BUILDID to buildid.  This will also append the
5661.9Sthorpej               build idenfitier to the name of the ``make'' wrapper script so
5671.37Slukem               that the resulting name is of the form
5681.37Slukem               ``nbmake-MACHINE-BUILDID''.
5691.1Stv
5701.18Slukem     -D dest   Set the value of DESTDIR to dest.
5711.18Slukem
5721.23Slukem     -E        Set `expert' mode.  This overrides various sanity checks, and
5731.23Slukem               allows: DESTDIR does not have to be set to a non-root path for
5741.38Slukem               builds, and MKUNPRIVED=yes does not have to be set when build-
5751.38Slukem               ing as a non-root user.
5761.23Slukem
5771.23Slukem               Note: It is highly recommended that you know what you are doing
5781.23Slukem               when you use this option.
5791.19Slukem
5801.51Swiz     -h        Print a help message.
5811.51Swiz
5821.10Ssommerfe     -j njob   Passed through to make(1).  Makefiles should use .WAIT or have
5831.10Ssommerfe               explicit dependancies as necessary to enforce build ordering.
5841.10Ssommerfe               If you see build failures with -j, please save complete build
5851.10Ssommerfe               logs so the failures can be analyzed.
5861.1Stv
5871.40Slukem     -M obj    Set MAKEOBJDIRPREFIX to obj.  Unsets MAKEOBJDIR.
5881.18Slukem
5891.1Stv     -m mach   Set the value of MACHINE to mach.  This will also override any
5901.1Stv               value of MACHINE_ARCH in the process environment with a value
5911.33Slukem               deduced from mach, unless -a is specified, or mach is a special
5921.33Slukem               case listed below.  All cross builds require -m, but if unset
5931.33Slukem               on a NetBSD host, the host's value of MACHINE will be detected
5941.33Slukem               and used automatically.
5951.33Slukem
5961.33Slukem               Some machines support multiple values for MACHINE_ARCH.  For a
5971.33Slukem               given value of mach, the following MACHINE and MACHINE_ARCH
5981.33Slukem               values will result:
5991.33Slukem
6001.33Slukem                     mach          MACHINE    MACHINE_ARCH
6011.33Slukem                     evbmips       evbmips    (not set)
6021.33Slukem                     evbmips-eb    evbmips    mipseb
6031.33Slukem                     evbmips-el    evbmips    mipsel
6041.33Slukem                     evbsh3        evbsh3     (not set)
6051.33Slukem                     evbsh3-eb     evbsh3     sh3eb
6061.33Slukem                     evbsh3-el     evbsh3     sh3el
6071.33Slukem                     sbmips        sbmips     (not set)
6081.33Slukem                     sbmips-eb     sbmips     mipseb
6091.33Slukem                     sbmips-el     sbmips     mipsel
6101.1Stv
6111.45Slukem     -N noiselevel
6121.46Slukem               Set the ``noisyness'' level of the build, by setting
6131.46Slukem               MAKEVERBOSE to noiselevel.
6141.45Slukem
6151.1Stv     -n        Show the commands that would be executed by build.sh, but do
6161.1Stv               not make any changes.  This is similar in concept to ``make
6171.1Stv               -n''.
6181.1Stv
6191.18Slukem     -O obj    Create an appropriate transform macro for MAKEOBJDIR that will
6201.18Slukem               place the built object files under obj.  For instance, a set-
6211.18Slukem               ting of /usr/obj will place build-time files under
6221.40Slukem               /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, and so forth.
6231.40Slukem               Unsets MAKEOBJDIRPREFIX.
6241.18Slukem
6251.34Slukem     -o        Set the value of MKOBJDIRS to ``no''.  Otherwise, it will be
6261.34Slukem               automatically set to ``yes'' (which is opposite to the default
6271.34Slukem               behaviour).
6281.1Stv
6291.22Slukem     -R rel    Set the value of RELEASEDIR to rel.
6301.18Slukem
6311.1Stv     -r        Remove the contents of DESTDIR and TOOLDIR before building
6321.1Stv               (provides a clean starting point).  This will skip deleting
6331.1Stv               DESTDIR if building on a native system to the root directory.
6341.1Stv
6351.18Slukem     -T tools  Set the value of TOOLDIR to tools.  If set, the bootstrap
6361.18Slukem               ``make'' will only be rebuilt as needed (when the source files
6371.18Slukem               for make(1) change).
6381.18Slukem
6391.38Slukem     -U        Set MKUNPRIVED=yes.
6401.18Slukem
6411.38Slukem     -u        Set MKUPDATE=yes.
6421.1Stv
6431.21Slukem     -V var=[value]
6441.40Slukem               Set the environment variable var to an optional value.  This is
6451.40Slukem               propagated to the nbmake wrapper.
6461.21Slukem
6471.1Stv     -w wrapper
6481.1Stv               Create the nbmake wrapper script (see below) in a custom loca-
6491.1Stv               tion, specified by wrapper.  This allows, for instance, to
6501.1Stv               place the wrapper in PATH automatically.  Note that wrapper is
6511.1Stv               the full name of the file, not just a directory name.
6521.1Stv
6531.49Slukem     -X x11src
6541.49Slukem               Set the value of X11SRCDIR to x11src.
6551.49Slukem
6561.49Slukem     -x        Set MKX11=yes.
6571.49Slukem
6581.40Slukem     -Z var    Unset ("zap") the environment variable var.  This is propagated
6591.40Slukem               to the nbmake wrapper.
6601.40Slukem
6611.1Stv   The "nbmake-MACHINE" wrapper script
6621.1Stv     If using the build.sh script to build NetBSD, a nbmake-MACHINE script
6631.1Stv     will be created in TOOLDIR/bin upon the first build to assist in building
6641.1Stv     subtrees on a cross-compile host.
6651.1Stv
6661.1Stv     nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
6671.1Stv     the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with sev-
6681.1Stv     eral key variables pre-set, including MACHINE, MACHINE_ARCH, and TOOLDIR.
6691.40Slukem     build.sh will also set variables specified with -V, and unset variables
6701.40Slukem     specified with -Z.
6711.40Slukem
6721.1Stv     This script can be symlinked into a directory listed in PATH, or called
6731.1Stv     with an absolute path.
6741.1Stv
6751.16SlukemEXAMPLES
6761.44Slukem     1.   % ./build.sh tools kernel=GENERIC
6771.28Slukem
6781.28Slukem          Build a new toolchain, and use the new toolchain to configure and
6791.28Slukem          build a new GENERIC kernel.
6801.28Slukem
6811.44Slukem     2.   % ./build.sh -U distribution
6821.28Slukem
6831.30Slukem          Using unprivileged mode, build a complete distribution to a DESTDIR
6841.30Slukem          directory that build.sh selects (and will display).
6851.28Slukem
6861.43Smartti     3.   # ./build.sh -U install=/
6871.28Slukem
6881.29Slukem          As root, install to / the distribution that was built by example 2.
6891.29Slukem          Even though this is run as root, -U is required so that the permis-
6901.30Slukem          sions stored in DESTDIR/METALOG are correctly applied to the files
6911.30Slukem          as they're copied to /.
6921.28Slukem
6931.44Slukem     4.   % ./build.sh -U -u release
6941.28Slukem
6951.30Slukem          Using unprivileged mode, build a complete release to DESTDIR and
6961.30Slukem          RELEASEDIR directories that build.sh selects (and will display).
6971.38Slukem          MKUPDATE=yes (-u) is set to prevent the ``make cleandir'', so that
6981.38Slukem          if this is run after example 2, it doesn't need to redo that portion
6991.38Slukem          of the release build.
7001.16Slukem
7011.10SsommerfeOBSOLETE VARIABLES
7021.15Slukem     NBUILDJOBS  Use the make(1) option -j, instead.
7031.15Slukem
7041.15Slukem     USE_NEW_TOOLCHAIN
7051.15Slukem                 The new toolchain is now the default.  To disable, use
7061.15Slukem                 TOOLCHAIN_MISSING=yes.
7071.10Ssommerfe
7081.1StvSEE ALSO
7091.1Stv     make(1), hier(7), release(7)
7101.1Stv
7111.1StvHISTORY
7121.15Slukem     The build.sh based build scheme was introduced for NetBSD 1.6 as
7131.15Slukem     USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.
7141.1Stv
7151.1StvBUGS
7161.15Slukem     A few platforms are not yet using this build system.
7171.1Stv
7181.49SlukemNetBSD                         February 6, 2003                         NetBSD
719