summaryrefslogtreecommitdiff
path: root/BUILDING
diff options
context:
space:
mode:
authorpgoyette <pgoyette@NetBSD.org>2018-05-02 07:34:44 +0000
committerpgoyette <pgoyette@NetBSD.org>2018-05-02 07:34:44 +0000
commita0bff5b88204c269f89ce197de367aa382b50ca0 (patch)
treea43f712407686e1884bbbd1e8e29b202bee93f21 /BUILDING
parentd7d6f2875b9ec17c72d1b8147bc8c0e24fe995a3 (diff)
Re-add files that were accidentally deleted in my previous commit.
Diffstat (limited to 'BUILDING')
-rw-r--r--BUILDING1115
1 files changed, 1115 insertions, 0 deletions
diff --git a/BUILDING b/BUILDING
new file mode 100644
index 00000000000..f46c41f8eb7
--- /dev/null
+++ b/BUILDING
@@ -0,0 +1,1115 @@
+BUILDING(8) System Manager's Manual BUILDING(8)
+
+NAME
+ BUILDING - Procedure for building NetBSD from source code.
+
+REQUIREMENTS
+ NetBSD is designed to be buildable on most POSIX-compliant host systems.
+ The basic build procedure is the same whether compiling natively (on the
+ same NetBSD architecture) or cross compiling (on another architecture or
+ OS).
+
+ This source tree contains a special subtree, "tools", which uses the host
+ system to create a build toolchain for the target architecture. The host
+ system must have at least C and C++ compilers in order to create the
+ toolchain (make is not required); all other tools are created as part of
+ the NetBSD build process. (See the environment variables section below
+ if you need to override or manually select your compilers.)
+
+FILES
+ Source tree layout
+ doc/BUILDING.mdoc
+ This document (in -mdoc troff format; the original copy).
+
+ BUILDING This document (in plaintext).
+
+ tools/compat/README
+ Special notes for cross-hosting a NetBSD build on non-
+ NetBSD platforms.
+
+ Makefile The main Makefile for NetBSD; should only be run for
+ native builds with an appropriately up-to-date version of
+ NetBSD make(1). Intended for expert use with knowlege of
+ its shortcomings, it has been superseded by the build.sh
+ shell script as the recommended means for building NetBSD.
+
+ UPDATING Special notes for updating from an earlier revision of
+ NetBSD. It is important to read this file before every
+ build of an updated source tree.
+
+ build.sh Bourne-compatible shell script used for building the host
+ build tools and the NetBSD system from scratch. Can be
+ used for both native and cross builds, and should be used
+ instead of make(1) as it performs additional checks to
+ prevent common issues going undetected, such as building
+ with an outdated version of make(1).
+
+ crypto/dist/, dist/, gnu/dist/
+ Sources imported verbatim from third parties, without
+ mangling the existing build structure. Other source trees
+ in bin through usr.sbin use the NetBSD make(1) "reachover"
+ Makefile semantics when building these programs for a
+ native host.
+
+ external, sys/external
+ Sources and build infrastructure for components imported
+ (mostly) unchanged from upstream maintainers, sorted by
+ applicable license. This is (slowly) replacing the
+ crypto/dist, dist, and gnu/dist directories.
+
+ distrib/, etc/
+ Sources for items used when making a full release
+ snapshot, such as files installed in DESTDIR/etc on the
+ destination system, boot media, and release notes.
+
+ tests/, regress/
+ Regression test harness. Can be cross-compiled, but only
+ run natively. tests/ uses the atf(7) test framework;
+ regress/ contains older tests that have not yet been
+ migrated to atf(7).
+
+ sys/ NetBSD kernel sources.
+
+ tools/ "Reachover" build structure for the host build tools.
+ This has a special method of determining out-of-date
+ status.
+
+ bin/ ... usr.sbin/
+ Sources to the NetBSD userland (non-kernel) programs. If
+ any of these directories are missing, they will be skipped
+ during the build.
+
+ external/mit/xorg/
+ "Reachover" build structure for modular Xorg; the source
+ is in X11SRCDIR.
+
+ extsrc/ "Reachover" build structure for externally added programs
+ and libraries; the source is in EXTSRCSRCDIR.
+
+ Build tree layout
+ The NetBSD build tree is described in hier(7), and the release layout is
+ described in release(7).
+
+CONFIGURATION
+ Environment variables
+ Several environment variables control the behaviour of NetBSD builds.
+
+ HOST_SH Path name to a shell available on the host system and
+ suitable for use during the build. The NetBSD build
+ system requires a modern Bourne-like shell with POSIX-
+ compliant features, and also requires support for the
+ "local" keyword to declare local variables in shell
+ functions (which is a widely-implemented but non-
+ standardised feature).
+
+ Depending on the host system, a suitable shell may be
+ /bin/sh, /usr/xpg4/bin/sh, /bin/ksh (provided it is a
+ variant of ksh that supports the "local" keyword, such
+ as ksh88, but not ksh93), or /usr/local/bin/bash.
+
+ Most parts of the build require HOST_SH to be an
+ absolute path; however, build.sh allows it to be a
+ simple command name, which will be converted to an
+ absolute path by searching the PATH.
+
+ HOST_CC Path name to C compiler used to create the toolchain.
+
+ HOST_CXX Path name to C++ compiler used to create the toolchain.
+
+ MACHINE Machine type, e.g., "macppc".
+
+ MACHINE_ARCH Machine architecture, e.g., "powerpc".
+
+ MAKE Path name to invoke make(1) as.
+
+ MAKEFLAGS Flags to invoke make(1) with. Note that build.sh
+ ignores the value of MAKEFLAGS passed in the
+ environment, but allows MAKEFLAGS to be set via the -V
+ option.
+
+ MAKEOBJDIR Directory to use as the .OBJDIR for the current
+ directory. The value is subjected to variable
+ expansion by make(1). Typical usage is to set this
+ variable to a value involving the use of
+ `${.CURDIR:S...}' or `${.CURDIR:C...}', to derive the
+ value of .OBJDIR from the value of .CURDIR. Used only
+ if MAKEOBJDIRPREFIX is not defined. MAKEOBJDIR can be
+ provided only in the environment or via the -O flag of
+ build.sh; it cannot usefully be set inside a Makefile,
+ including mk.conf or ${MAKECONF}.
+
+ MAKEOBJDIRPREFIX Top level directory of the object directory tree. The
+ value is subjected to variable expansion by make(1).
+ build.sh will create the ${MAKEOBJDIRPREFIX} directory
+ if necessary, but if make(1) is used without build.sh,
+ then rules in <bsd.obj.mk> will abort the build if the
+ ${MAKEOBJDIRPREFIX} directory does not exist. If the
+ value is defined and valid, then
+ ${MAKEOBJDIRPREFIX}/${.CURDIR} is used as the .OBJDIR
+ for the current directory. The current directory may
+ be read only. MAKEOBJDIRPREFIX can be provided only in
+ the environment or via the -M flag of build.sh; it
+ cannot usefully be set inside a Makefile, including
+ mk.conf or ${MAKECONF}.
+
+ "make" variables
+ Several variables control the behavior of NetBSD builds. Unless
+ otherwise specified, these variables may be set in either the process
+ environment or the make(1) configuration file specified by MAKECONF.
+
+ BUILDID Identifier for the build. If set, this should be a short
+ string that is suitable for use as part of a file or
+ directory name. The identifier will be appended to object
+ directory names, and can be consulted in the make(1)
+ configuration file in order to set additional build
+ parameters, such as compiler flags. It will also be used as
+ part of the kernel version string, which can be printed by
+ "uname -v".
+
+ Default: Unset.
+
+ BUILDINFO This may be a multi-line string containing information about
+ the build. This will appear in DESTDIR/etc/release, and it
+ will be stored in the buildinfo variable in any kernels that
+ are built. When such kernels are booted, the sysctl(7)
+ kern.buildinfo variable will report this value. The string
+ may contain backslash escape sequences, such as "\\"
+ (representing a backslash character) and "\n" (representing a
+ newline).
+
+ Default: Unset.
+
+ BUILDSEED GCC uses random numbers when compiling C++ code. This
+ variable seeds the gcc random number generator using the
+ -frandom-seed flag with this value. By default, it is set to
+ NetBSD-(majorversion). Using a fixed value causes C++
+ binaries to be the same when built from the same sources,
+ resulting in identical (reproducible) builds. Additional
+ information is available in the GCC documentation of
+ -frandom-seed.
+
+ DESTDIR Directory to contain the built NetBSD system. If set,
+ special options are passed to the compilation tools to
+ prevent their default use of the host system's /usr/include,
+ /usr/lib, and so forth. This pathname must be an absolute
+ path, and should not end with a slash (/) character. (For
+ installation into the system's root directory, set DESTDIR to
+ an empty string, not to "/"). The directory must reside on a
+ file system which supports long file names and hard links.
+
+ Default: Empty string if USETOOLS is "yes"; unset otherwise.
+
+ Note: build.sh will provide a default of destdir.MACHINE (in
+ the top-level .OBJDIR) unless run in `expert' mode.
+
+ EXTSRCSRCDIR
+ Directory containing sources of externally added programs and
+ libraries. If specified, must be an absolute path.
+
+ Default: NETBSDRCDIR/../extsrc, if that exists; otherwise
+ /usr/extsrc.
+
+ MAKECONF The name of the make(1) configuration file. Only settable in
+ the process environment.
+
+ Default: "/etc/mk.conf"
+
+ MAKEVERBOSE
+ Level of verbosity of status messages. Supported values:
+
+ 0 No descriptive messages or commands executed by make(1)
+ are shown.
+
+ 1 Brief messages are shown describing what is being done,
+ but the actual commands executed by make(1) are not
+ displayed.
+
+ 2 Descriptive messages are shown as above (prefixed with a
+ `#'), and ordinary commands performed by make(1) are
+ displayed.
+
+ 3 In addition to the above, all commands performed by
+ make(1) are displayed, even if they would ordinarily
+ have been hidden through use of the "@" prefix in the
+ relevant makefile.
+
+ 4 In addition to the above, commands executed by make(1)
+ are traced through use of the sh(1) "-x" flag.
+
+ Default: 2
+
+ MKCATPAGES Can be set to "yes" or "no". Indicates whether preformatted
+ plaintext manual pages will be created during a build.
+
+ Default: "no"
+
+ MKCROSSGDB Can be set to "yes" or "no". Create a cross-gdb as a host
+ tool.
+
+ Default: "no"
+
+ MKDEBUG Can be set to "yes" or "no". Indicates whether debug
+ information should be generated for all userland binaries
+ compiled. The result is collected as an additional debug.tgz
+ and xdebug.tgz set and installed in /usr/libdata/debug.
+
+ Default: "no"
+
+ MKDEBUGLIB Can be set to "yes" or "no". Indicates whether debug
+ information (see MKDEBUG) should also be generated for all
+ libraries build.
+
+ Default: "no"
+
+ MKDOC Can be set to "yes" or "no". Indicates whether system
+ documentation destined for DESTDIR/usr/share/doc will be
+ installed during a build.
+
+ Default: "yes"
+
+ MKEXTSRC Can be set to "yes" or "no". Indicates whether extsrc is
+ built from EXTSRCSRCDIR.
+
+ Default: "no"
+
+ MKHTML Can be set to "yes" or "no". Indicates whether preformatted
+ HTML manual pages will be built and installed
+
+ Default: "yes"
+
+ MKHOSTOBJ Can be set to "yes" or "no". If set to "yes", then for
+ programs intended to be run on the compile host, the name,
+ release, and architecture of the host operating system will
+ be suffixed to the name of the object directory created by
+ "make obj". (This allows multiple host systems to compile
+ NetBSD for a single target.) If set to "no", then programs
+ built to be run on the compile host will use the same object
+ directory names as programs built to be run on the target.
+
+ Default: "no"
+
+ MKINFO Can be set to "yes" or "no". Indicates whether GNU Info
+ files, used for the documentation for most of the compilation
+ tools, will be created and installed during a build.
+
+ Default: "yes"
+
+ MKKDEBUG Can be set to "yes" or "no". Force generation of full-debug
+ symbol versions of all kernels compiled. Alongside of the
+ netbsd kernel file, an unstripped version netbsd.gdb is
+ created. This is useful if a cross-gdb is built as well (see
+ MKCROSSGDB).
+
+ Default: "no"
+
+ MKKMOD Can be set to "yes" or "no". Indicates whether kernel
+ modules are built and installed.
+
+ Default: "yes"
+
+ MKLINT Can be set to "yes" or "no". Indicates whether lint(1) will
+ be run against portions of the NetBSD source code during the
+ build, and whether lint libraries will be installed into
+ DESTDIR/usr/libdata/lint.
+
+ Default: "yes"
+
+ MKMAN Can be set to "yes" or "no". Indicates whether manual pages
+ will be installed during a build.
+
+ Default: "yes"
+
+ MKNLS Can be set to "yes" or "no". Indicates whether Native
+ Language System locale zone files will be compiled and
+ installed during a build.
+
+ Default: "yes"
+
+ MKOBJ Can be set to "yes" or "no". Indicates whether object
+ directories will be created when running "make obj". If set
+ to "no", then all built files will be located inside the
+ regular source tree.
+
+ Default: "yes"
+
+ Note that setting MKOBJ to "no" is not recommended and may
+ cause problems when updating the tree with cvs(1).
+
+ MKPIC Can be set to "yes" or "no". Indicates whether shared
+ objects and libraries will be created and installed during a
+ build. If set to "no", the entire built system will be
+ statically linked.
+
+ Default: Platform dependent. As of this writing, all
+ platforms except m68000 default to "yes".
+
+ MKPICINSTALL
+ Can be set to "yes" or "no". Indicates whether the ar(1)
+ format libraries (lib*_pic.a), used to generate shared
+ libraries, are installed during a build.
+
+ Default: "yes"
+
+ MKPROFILE Can be set to "yes" or "no". Indicates whether profiled
+ libraries (lib*_p.a) will be built and installed during a
+ build.
+
+ Default: "yes"; however, some platforms turn off MKPROFILE by
+ default at times due to toolchain problems with profiled
+ code.
+
+ MKREPRO Can be set to "yes" or "no". Create reproducible builds.
+ This enables different switches to make two builds from the
+ same source tree result in the same build results.
+
+ Default: "no" This may be set to "yes" by giving build.sh the
+ -P option.
+
+ MKREPRO_TIMESTAMP
+ Unix timestamp. When MKREPRO is set, the timestamp of all
+ files in the sets will be set to this value.
+
+ Default: Unset. This may be set automatically to the latest
+ source tree timestamp using cvslatest(1) by giving build.sh
+ the -P option.
+
+ MKSHARE Can be set to "yes" or "no". Indicates whether files
+ destined to reside in DESTDIR/usr/share will be built and
+ installed during a build. If set to "no", then all of
+ MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to
+ "no" unconditionally.
+
+ Default: "yes"
+
+ MKSTRIPIDENT
+ Can be set to "yes" or "no". Indicates whether RCS IDs, for
+ use with ident(1), should be stripped from program binaries
+ and shared libraries.
+
+ Default: "no"
+
+ MKSTRIPSYM Can be set to "yes" or "no". Indicates whether all local
+ symbols should be stripped from shared libraries. If "yes",
+ strip all local symbols from shared libraries; the affect is
+ equivalent to the -x option of ld(1). If "no", strip only
+ temporary local symbols; the affect is equivalent to the -X
+ option of ld(1). Keeping non-temporary local symbols such as
+ static function names is useful on using DTrace for userland
+ libraries and getting a backtrace from a rump kernel loading
+ shared libraries.
+
+ Default: "yes"
+
+ MKUNPRIVED Can be set to "yes" or "no". Indicates whether an
+ unprivileged install will occur. The user, group,
+ permissions, and file flags, will not be set on the installed
+ items; instead the information will be appended to a file
+ called METALOG in DESTDIR. The contents of METALOG are used
+ during the generation of the distribution tar files to ensure
+ that the appropriate file ownership is stored.
+
+ Default: "no"
+
+ MKUPDATE Can be set to "yes" or "no". Indicates whether all install
+ operations intended to write to DESTDIR will compare file
+ timestamps before installing, and skip the install phase if
+ the destination files are up-to-date. This also has
+ implications on full builds (see next subsection).
+
+ Default: "no"
+
+ MKX11 Can be set to "yes" or "no". Indicates whether X11 is built
+ from X11SRCDIR.
+
+ Default: "no"
+
+ TOOLDIR Directory to hold the host tools, once built. If specified,
+ must be an absolute path. This directory should be unique to
+ a given host system and NetBSD source tree. (However,
+ multiple targets may share the same TOOLDIR; the target-
+ dependent files have unique names.) If unset, a default
+ based on the uname(1) information of the host platform will
+ be created in the .OBJDIR of src.
+
+ Default: Unset.
+
+ USETOOLS Indicates whether the tools specified by TOOLDIR should be
+ used as part of a build in progress. Must be set to "yes" if
+ cross-compiling.
+
+ yes Use the tools from TOOLDIR.
+
+ no Do not use the tools from TOOLDIR, but refuse to build
+ native compilation tool components that are version-
+ specific for that tool.
+
+ never Do not use the tools from TOOLDIR, even when building
+ native tool components. This is similar to the
+ traditional NetBSD build method, but does not verify
+ that the compilation tools in use are up-to-date
+ enough in order to build the tree successfully. This
+ may cause build or runtime problems when building the
+ whole NetBSD source tree.
+
+ Default: "yes", unless TOOLCHAIN_MISSING is set to "yes".
+
+ USETOOLS is also set to "no" when using <bsd.*.mk> outside
+ the NetBSD source tree.
+
+ X11SRCDIR Directory containing the modular Xorg source. If specified,
+ must be an absolute path. The main modular Xorg source is
+ found in X11SRCDIR/external/mit.
+
+ Default: NETBSDRCDIR/../xsrc, if that exists; otherwise
+ /usr/xsrc.
+
+ "make" variables for full builds
+ These variables only affect the top level "Makefile" and do not affect
+ manually building subtrees of the NetBSD source code.
+
+ INSTALLWORLDDIR Location for the "make installworld" target to install
+ to. If specified, must be an absolute path.
+
+ Default: "/"
+
+ MKOBJDIRS Can be set to "yes" or "no". Indicates whether object
+ directories will be created automatically (via a "make
+ obj" pass) at the start of a build.
+
+ Default: "no"
+
+ If using build.sh, the default is "yes". This may be
+ set back to "no" by giving build.sh the -o option.
+
+ MKUPDATE Can be set to "yes" or "no". If set, then in addition
+ to the effects described for MKUPDATE=yes above, this
+ implies the effects of NOCLEANDIR (i.e., "make cleandir"
+ is avoided).
+
+ Default: "no"
+
+ If using build.sh, this may be set by giving the -u
+ option.
+
+ NBUILDJOBS Now obsolete. Use the make(1) option -j, instead. See
+ below.
+
+ Default: Unset.
+
+ NOCLEANDIR If set, avoids the "make cleandir" phase of a full
+ build. This has the effect of allowing only changed
+ files in a source tree to be recompiled. This can speed
+ up builds when updating only a few files in the tree.
+
+ Default: Unset.
+
+ See also MKUPDATE.
+
+ NODISTRIBDIRS If set, avoids the "make distrib-dirs" phase of a full
+ build. This skips running mtree(8) on DESTDIR, useful
+ on systems where building as an unprivileged user, or
+ where it is known that the system-wide mtree files have
+ not changed.
+
+ Default: Unset.
+
+ NOINCLUDES If set, avoids the "make includes" phase of a full
+ build. This has the effect of preventing make(1) from
+ thinking that some programs are out-of-date simply
+ because the system include files have changed. However,
+ this option should not be used when updating the entire
+ NetBSD source tree arbitrarily; it is suggested to use
+ MKUPDATE=yes instead in that case.
+
+ Default: Unset.
+
+ RELEASEDIR If set, specifies the directory to which a release(7)
+ layout will be written at the end of a "make release".
+ If specified, must be an absolute path.
+
+ Default: Unset.
+
+ Note: build.sh will provide a default of releasedir (in
+ the top-level .OBJDIR) unless run in `expert' mode.
+
+BUILDING
+ "make" command line options
+ This is not a summary of all the options available to make(1); only the
+ options used most frequently with NetBSD builds are listed here.
+
+ -j njob Run up to njob make(1) subjobs in parallel. Makefiles should
+ use .WAIT or have explicit dependencies as necessary to
+ enforce build ordering.
+
+ -m dir Specify the default directory for searching for system
+ Makefile segments, mainly the <bsd.*.mk> files. When building
+ any full NetBSD source tree, this should be set to the
+ "share/mk" directory in the source tree. This is set
+ automatically when building from the top level, or when using
+ build.sh.
+
+ -n Display the commands that would have been executed, but do not
+ actually execute them. This will still cause recursion to
+ take place.
+
+ -V var Print make(1)'s idea of the value of var. Does not build any
+ targets.
+
+ var=value Set the variable var to value, overriding any setting
+ specified by the process environment, the MAKECONF
+ configuration file, or the system Makefile segments.
+
+ "make" targets
+ These default targets may be built by running make(1) in any subtree of
+ the NetBSD source code. It is recommended that none of these be used
+ from the top level Makefile; as a specific exception, "make obj" and
+ "make cleandir" are useful in that context.
+
+ all Build programs, libraries, and preformatted documentation.
+
+ clean Remove program and library object code files.
+
+ cleandir Same as clean, but also remove preformatted documentation,
+ dependency files generated by "make depend", and any other
+ files known to be created at build time.
+
+ depend Create dependency files (.depend) containing more detailed
+ information about the dependencies of source code on header
+ files. Allows programs to be recompiled automatically when a
+ dependency changes.
+
+ dependall Does a "make depend" immediately followed by a "make all".
+ This improves cache locality of the build since both passes
+ read the source files in their entirety.
+
+ distclean Synonym for cleandir.
+
+ includes Build and install system header files. Typically needed
+ before any system libraries or programs can be built.
+
+ install Install programs, libraries, and documentation into DESTDIR.
+ Few files will be installed to DESTDIR/dev, DESTDIR/etc,
+ DESTDIR/root or DESTDIR/var in order to prevent user supplied
+ configuration data from being overwritten.
+
+ lint Run lint(1) against the C source code, where appropriate, and
+ generate system-installed lint libraries.
+
+ obj Create object directories to be used for built files, instead
+ of building directly in the source tree.
+
+ tags Create ctags(1) searchable function lists usable by the ex(1)
+ and vi(1) text editors.
+
+ "make" targets for the top level
+ Additional make(1) targets are usable specifically from the top source
+ level to facilitate building the entire NetBSD source tree.
+
+ build Build the entire NetBSD system (except the kernel). This
+ orders portions of the source tree such that prerequisites
+ will be built in the proper order.
+
+ distribution Do a "make build", and then install a full distribution
+ (which does not include a kernel) into DESTDIR, including
+ files in DESTDIR/dev, DESTDIR/etc, DESTDIR/root and
+ DESTDIR/var.
+
+ buildworld As per "make distribution", except that it ensures that
+ DESTDIR is not the root directory.
+
+ installworld Install the distribution from DESTDIR to INSTALLWORLDDIR,
+ which defaults to the root directory. Ensures that
+ INSTALLWORLDDIR is not the root directory if cross
+ compiling.
+
+ The INSTALLSETS environment variable may be set to a space-
+ separated list of distribution sets to be installed. By
+ default, all sets except "etc" and "xetc" are installed, so
+ most files in INSTALLWORLDDIR/etc will not be installed or
+ modified.
+
+ Note: Before performing this operation with
+ INSTALLWORLDDIR=/, it is highly recommended that you
+ upgrade your kernel and reboot. After performing this
+ operation, it is recommended that you use etcupdate(8) to
+ update files in INSTALLWORLDDIR/etc, and postinstall(8) to
+ check for or fix inconsistencies.
+
+ sets Create distribution sets from DESTDIR into
+ RELEASEDIR/RELEASEMACHINEDIR/binary/sets. Should be run
+ after "make distribution", as "make build" alone does not
+ install all of the required files.
+
+ sourcesets Create source sets of the source tree into
+ RELEASEDIR/source/sets.
+
+ syspkgs Create syspkgs from DESTDIR into
+ RELEASEDIR/RELEASEMACHINEDIR/binary/syspkgs. Should be run
+ after "make distribution", as "make build" alone does not
+ install all of the required files.
+
+ release Do a "make distribution", build kernels, distribution
+ media, and install sets (this as per "make sets"), and then
+ package the system into a standard release layout as
+ described by release(7). This requires that RELEASEDIR be
+ set (see above).
+
+ iso-image Create a NetBSD installation CD-ROM image in the
+ RELEASEDIR/images directory. The CD-ROM file system will
+ have a layout as described in release(7).
+
+ For most machine types, the CD-ROM will be bootable, and
+ will automatically run the sysinst(8) menu-based
+ installation program, which can be used to install or
+ upgrade a NetBSD system. Bootable CD-ROMs also contain
+ tools that may be useful in repairing a damaged NetBSD
+ installation.
+
+ Before "make iso-image" is attempted, RELEASEDIR must be
+ populated by "make release" or equivalent.
+
+ Note that other, smaller, CD-ROM images may be created in
+ the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom
+ directory by "make release". These smaller images usually
+ contain the same tools as the larger images in
+ RELEASEDIR/images, but do not contain additional content
+ such as the distribution sets.
+
+ Note that the mac68k port still uses an older method of
+ creating CD-ROM images. This requires the mkisofs(1)
+ utility, which is not part of NetBSD, but which can be
+ installed from pkgsrc/sysutils/cdrtools.
+
+ iso-image-source
+ Create a NetBSD installation CD-ROM image in the
+ RELEASEDIR/images directory. The CD-ROM file system will
+ have a layout as described in release(7). It will have top
+ level directories for the machine type and source.
+
+ For most machine types, the CD-ROM will be bootable, and
+ will automatically run the sysinst(8) menu-based
+ installation program, which can be used to install or
+ upgrade a NetBSD system. Bootable CD-ROMs also contain
+ tools that may be useful in repairing a damaged NetBSD
+ installation.
+
+ Before "make iso-image-source" is attempted, RELEASEDIR
+ must be populated by "make sourcesets release" or
+ equivalent.
+
+ Note that other, smaller, CD-ROM images may be created in
+ the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom
+ directory by "make release". These smaller images usually
+ contain the same tools as the larger images in
+ RELEASEDIR/images, but do not contain additional content
+ such as the distribution sets.
+
+ Note that the mac68k port still uses an older method of
+ creating CD-ROM images. This requires the mkisofs(1)
+ utility, which is not part of NetBSD, but which can be
+ installed from pkgsrc/sysutils/cdrtools.
+
+ install-image
+ Create a bootable NetBSD installation disk image in the
+ RELEASEDIR/images directory. The installation disk image
+ is suitable for copying to bootable USB flash memory
+ sticks, etc., for machines which are able to boot from such
+ devices. The file system in the bootable disk image will
+ have a layout as described in release(7).
+
+ The installation image is bootable, and will automatically
+ run the sysinst(8) menu-based installation program, which
+ can be used to install or upgrade a NetBSD system. The
+ image also contains tools that may be useful in repairing a
+ damaged NetBSD installation.
+
+ Before "make install-image" is attempted, RELEASEDIR must
+ be populated by "make release" or equivalent. The build
+ must have been performed with MKUNPRIVED=yes because "make
+ install-image" relies on information in DESTDIR/METALOG.
+
+ live-image Create NetBSD live images in the RELEASEDIR/images
+ directory. The live image contains all necessary files to
+ boot NetBSD up to multi-user mode, including all files
+ which should be extracted during installation, NetBSD
+ disklabel, bootloaders, etc.
+
+ The live image is suitable for use as a disk image in
+ virtual machine environments such as QEMU, and also useful
+ to boot NetBSD from a USB flash memory stick on a real
+ machine, without the need for installation.
+
+ Before "make live-image" is attempted, RELEASEDIR must be
+ populated by "make release" or equivalent. The build must
+ have been performed with MKUNPRIVED=yes because "make
+ install-image" relies on information in DESTDIR/METALOG.
+
+ regression-tests
+ Can only be run after building the regression tests in the
+ directory "regress". Runs those compiled regression tests
+ on the local host. Note that most tests are now managed
+ instead using atf(7); this target should probably run those
+ as well but currently does not.
+
+ The "build.sh" script
+ This script file is a shell script designed to build the entire NetBSD
+ system on any host with a suitable modern shell and some common
+ utilities. The required shell features are described under the HOST_SH
+ variable.
+
+ If a host system's default shell does support the required features, then
+ we suggest that you explicitly specify a suitable shell using a command
+ like
+
+ /path/to/suitable/shell build.sh [options]
+
+ The above command will usually enable build.sh to automatically set
+ HOST_SH=/path/to/suitable/shell, but if that fails, then the following
+ set of commands may be used instead:
+
+ HOST_SH=/path/to/suitable/shell
+ export HOST_SH
+ ${HOST_SH} build.sh [options]
+
+ If build.sh detects that it is being executed under an unsuitable shell,
+ it attempts to exec a suitable shell instead, or prints an error message.
+ If HOST_SH is not set explicitly, then build.sh sets a default using
+ heuristics dependent on the host platform, or from the shell under which
+ build.sh is executed (if that can be determined), or using the first copy
+ of sh found in PATH.
+
+ All cross-compile builds, and most native builds, of the entire system
+ should make use of build.sh rather than just running "make". This way,
+ the make(1) program will be bootstrapped properly, in case the host
+ system has an older or incompatible "make" program.
+
+ When compiling the entire system via build.sh, many make(1) variables are
+ set for you in order to help encapsulate the build process. In the list
+ of options below, variables that are automatically set by build.sh are
+ noted where applicable.
+
+ The following operations are supported by build.sh:
+
+ build Build the system as per "make build". Before the main part
+ of the build commences, this command runs the obj operation
+ (unless the -o option is given), "make cleandir" (unless
+ the -u option is given), and the tools operation.
+
+ distribution Build a full distribution as per "make distribution". This
+ command first runs the build operation.
+
+ release Build a full release as per "make release". This command
+ first runs the distribution operation.
+
+ makewrapper Create the nbmake-MACHINE wrapper. This operation is
+ automatically performed for any of the other operations.
+
+ cleandir Perform "make cleandir".
+
+ obj Perform "make obj".
+
+ tools Build and install the host tools from src/tools. This
+ command will first run "make obj" and "make cleandir" in
+ the tools subdirectory unless the -o or -u options
+ (respectively) are given.
+
+ install=idir Install the contents of DESTDIR to idir, using "make
+ installworld". Note that files that are part of the "etc"
+ or "xetc" sets will not be installed, unless overridden by
+ the INSTALLSETS environment variable.
+
+ kernel=kconf Build a new kernel. The kconf argument is the name of a
+ configuration file suitable for use by config(1). If kconf
+ does not contain any `/' characters, the configuration file
+ is expected to be found in the KERNCONFDIR directory, which
+ is typically sys/arch/MACHINE/conf. The new kernel will be
+ built in a subdirectory of KERNOBJDIR, which is typically
+ sys/arch/MACHINE/compile or an associated object directory.
+
+ This command does not imply the tools command; run the
+ tools command first unless it is certain that the tools
+ already exist and are up to date.
+
+ This command will run "make cleandir" on the kernel in
+ question first unless the -u option is given.
+
+ kernel.gdb=kconf
+ Build a new kernel with debug information. Similar to the
+ above kernel=kconf operation, but creates a netbsd.gdb file
+ alongside of the kernel netbsd, which contains a full
+ symbol table and can be used for debugging (for example
+ with a cross-gdb built by MKCROSSGDB).
+
+ kernels This command will build all kernels defined in port
+ specific release build procedure.
+
+ This command internally calls the kernel=kconf operation
+ for each found kernel configuration file.
+
+ modules This command will build kernel modules and install them
+ into DESTDIR.
+
+ releasekernel=kconf
+ Install a gzip(1)ed copy of the kernel previously built by
+ kernel=kconf into
+ RELEASEDIR/RELEASEMACHINEDIR/binary/kernel, usually as
+ netbsd-kconf.gz, although the "netbsd" prefix is determined
+ from the "config" directives in kconf.
+
+ sets Perform "make sets".
+
+ sourcesets Perform "make sourcesets".
+
+ syspkgs Perform "make syspkgs".
+
+ iso-image Perform "make iso-image".
+
+ iso-image-source
+ Perform "make iso-image-source".
+
+ install-image
+ Perform "make install-image".
+
+ live-image Perform "make live-image".
+
+ list-arch Prints a list of valid MACHINE and MACHINE_ARCH settings,
+ the default MACHINE_ARCH for each MACHINE, and aliases for
+ MACHINE/MACHINE_ARCH pairs, and then exits. The -m or -a
+ options (or both) may be used to specify glob patterns that
+ will be used to narrow the list of results; for example,
+ "build.sh -m 'evb*' -a '*arm*' list-arch" will list all
+ known MACHINE/MACHINE_ARCH values in which either MACHINE
+ or ALIAS matches the pattern `evb*', and MACHINE_ARCH
+ matches the pattern `*arm*'.
+
+ The following command line options alter the behaviour of the build.sh
+ operations described above:
+
+ -a arch Set the value of MACHINE_ARCH to arch. See the -m option for
+ more information.
+
+ -B buildid
+ Set the value of BUILDID to buildid. This will also append the
+ build identifier to the name of the "make" wrapper script so
+ that the resulting name is of the form
+ "nbmake-MACHINE-BUILDID".
+
+ -C cdextras
+ Append cdextras to the CDEXTRA variable, which is a space-
+ separated list of files or directories that will be added to
+ the CD-ROM image that may be create by the "iso-image" or
+ "iso-image-source" operations. Files will be added to the root
+ of the CD-ROM image, whereas directories will be copied
+ recursively. If relative paths are specified, they will be
+ converted to absolute paths before being used. Multiple paths
+ may be specified via multiple -C options, or via a single
+ option whose argument contains multiple space-separated paths.
+
+ -D dest Set the value of DESTDIR to dest. If a relative path is
+ specified, it will be converted to an absolute path before
+ being used.
+
+ -E Set `expert' mode. This overrides various sanity checks, and
+ allows: DESTDIR does not have to be set to a non-root path for
+ builds, and MKUNPRIVED=yes does not have to be set when
+ building as a non-root user.
+
+ Note: It is highly recommended that you know what you are doing
+ when you use this option.
+
+ -h Print a help message.
+
+ -j njob Run up to njob make(1) subjobs in parallel; passed through to
+ make(1). If you see failures for reasons other than running
+ out of memory while using build.sh with -j, please save
+ complete build logs so the failures can be analyzed.
+
+ To achieve the fastest builds, -j values between (1 + the
+ number of CPUs) and (2 * the number of CPUs) are recommended.
+ Use lower values on machines with limited memory or I/O
+ bandwidth.
+
+ -M obj Set MAKEOBJDIRPREFIX to obj. Unsets MAKEOBJDIR. See "-O obj"
+ for more information.
+
+ For instance, if the source directory is /usr/src, a setting of
+ "-M /usr/obj" will place build-time files under
+ /usr/obj/usr/src/bin, /usr/obj/usr/src/lib,
+ /usr/obj/usr/src/usr.bin, and so forth.
+
+ If a relative path is specified, it will be converted to an
+ absolute path before being used. build.sh imposes the
+ restriction that the argument to the -M option must not begin
+ with a "$" (dollar sign) character; otherwise it would be too
+ difficult to determine whether the value is an absolute or a
+ relative path. If the directory does not already exist,
+ build.sh will create it.
+
+ -m mach Set the value of MACHINE to mach, unless the mach argument is
+ an alias that refers to a MACHINE/MACHINE_ARCH pair, in which
+ case both MACHINE and MACHINE_ARCH are set from the alias.
+ Such aliases are interpreted entirely by build.sh; they are not
+ used by any other part of the build system. The MACHINE_ARCH
+ setting implied by mach will override any value of MACHINE_ARCH
+ in the process environment, but will not override a value set
+ by the -a option. All cross builds require -m, but if unset on
+ a NetBSD host, the host's value of MACHINE will be detected and
+ used automatically.
+
+ See the list-arch operation for a way to get a list of valid
+ MACHINE and MACHINE_ARCH settings.
+
+ -N noiselevel
+ Set the "noisyness" level of the build, by setting MAKEVERBOSE
+ to noiselevel.
+
+ -n Show the commands that would be executed by build.sh, but do
+ not make any changes. This is similar in concept to "make -n".
+
+ -O obj Create an appropriate transform macro for MAKEOBJDIR that will
+ place the built object files under obj. Unsets
+ MAKEOBJDIRPREFIX.
+
+ For instance, a setting of "-O /usr/obj" will place build-time
+ files under /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, and
+ so forth.
+
+ If a relative path is specified, it will be converted to an
+ absolute path before being used. build.sh imposes the
+ restriction that the argument to the -O option must not contain
+ a "$" (dollar sign) character. If the directory does not
+ already exist, build.sh will create it.
+
+ In normal use, exactly one of the -M or -O options should be
+ specified. If neither -M nor -O is specified, then a default
+ object directory will be chosen according to rules in
+ <bsd.obj.mk>. Relying on this default is not recommended
+ because it is determined by complex rules that are influenced
+ by the values of several variables and by the location of the
+ source directory.
+
+ Note that placing the obj directory location outside of the
+ default source tree hierarchy makes it easier to manually clear
+ out old files in the event the "make cleandir" operation is
+ unable to do so. (See CAVEATS below.)
+
+ Note also that use of one of -M or -O is the only means of
+ building multiple machine architecture userlands from the same
+ source tree without cleaning between builds (in which case, one
+ would specify distinct obj locations for each).
+
+ -o Set the value of MKOBJDIRS to "no". Otherwise, it will be
+ automatically set to "yes". This default is opposite to the
+ behaviour when not using build.sh.
+
+ -R rel Set the value of RELEASEDIR to rel. If a relative path is
+ specified, it will be converted to an absolute path before
+ being used.
+
+ -r Remove the contents of DESTDIR and TOOLDIR before building
+ (provides a clean starting point). This will skip deleting
+ DESTDIR if building on a native system to the root directory.
+
+ -S seed Change the value of BUILDSEED to seed. This should rarely be
+ necessary.
+
+ -T tools Set the value of TOOLDIR to tools. If a relative path is
+ specified, it will be converted to an absolute path before
+ being used. If set, the bootstrap "make" will only be rebuilt
+ if the source files for make(1) have changed.
+
+ -U Set MKUNPRIVED=yes.
+
+ -u Set MKUPDATE=yes.
+
+ -V var=[value]
+ Set the environment variable var to an optional value. This is
+ propagated to the nbmake wrapper.
+
+ -w wrapper
+ Create the nbmake wrapper script (see below) in a custom
+ location, specified by wrapper. This allows, for instance, to
+ place the wrapper in PATH automatically. Note that wrapper is
+ the full name of the file, not just a directory name. If a
+ relative path is specified, it will be converted to an absolute
+ path before being used.
+
+ -X x11src
+ Set the value of X11SRCDIR to x11src. If a relative path is
+ specified, it will be converted to an absolute path before
+ being used.
+
+ -x Set MKX11=yes.
+
+ -Y extsrcdir
+ Set the value of EXTSRCSRCDIR to extsrcdir. If a relative path
+ is specified, it will be converted to an absolute path before
+ being used.
+
+ -y Set MKEXTSRC=yes.
+
+ -Z var Unset ("zap") the environment variable var. This is propagated
+ to the nbmake wrapper.
+
+ The "nbmake-MACHINE" wrapper script
+ If using the build.sh script to build NetBSD, a nbmake-MACHINE script
+ will be created in TOOLDIR/bin upon the first build to assist in building
+ subtrees on a cross-compile host.
+
+ nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
+ the up-to-date version of "nbmake" installed into TOOLDIR/bin with
+ several key variables pre-set, including MACHINE, MACHINE_ARCH, and
+ TOOLDIR. nbmake-MACHINE will also set variables specified with -V, and
+ unset variables specified with -Z.
+
+ This script can be symlinked into a directory listed in PATH, or called
+ with an absolute path.
+
+EXAMPLES
+ 1. % ./build.sh [options] tools kernel=GENERIC
+
+ Build a new toolchain, and use the new toolchain to configure and
+ build a new GENERIC kernel.
+
+ 2. % ./build.sh [options] -U distribution
+
+ Using unprivileged mode, build a complete distribution to a DESTDIR
+ directory that build.sh selects (and will display).
+
+ 3. # ./build.sh [options] -U install=/
+
+ As root, install to / the distribution that was built by example 2.
+ Even though this is run as root, -U is required so that the
+ permissions stored in DESTDIR/METALOG are correctly applied to the
+ files as they're copied to /.
+
+ 4. % ./build.sh [options] -U -u release
+
+ Using unprivileged mode, build a complete release to DESTDIR and
+ RELEASEDIR directories that build.sh selects (and will display).
+ MKUPDATE=yes (-u) is set to prevent the "make cleandir", so that if
+ this is run after example 2, it doesn't need to redo that portion of
+ the release build.
+
+OBSOLETE VARIABLES
+ NBUILDJOBS Use the make(1) option -j instead.
+
+ USE_NEW_TOOLCHAIN
+ The new toolchain is now the default. To disable, use
+ TOOLCHAIN_MISSING=yes.
+
+SEE ALSO
+ make(1), hier(7), release(7), etcupdate(8), postinstall(8), sysinst(8),
+ pkgsrc/sysutils/cdrtools
+
+HISTORY
+ The build.sh based build scheme was introduced for NetBSD 1.6 as
+ USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.
+
+CAVEATS
+ After significant updates to third-party components in the source tree,
+ the "make cleandir" operation may be insufficient to clean out old files
+ in object directories. Instead, one may have to manually remove the
+ files. Consult the UPDATING file for notices concerning this.
+
+NetBSD October 21, 2017 NetBSD