diff options
| author | pgoyette <pgoyette@NetBSD.org> | 2018-05-02 07:34:44 +0000 |
|---|---|---|
| committer | pgoyette <pgoyette@NetBSD.org> | 2018-05-02 07:34:44 +0000 |
| commit | a0bff5b88204c269f89ce197de367aa382b50ca0 (patch) | |
| tree | a43f712407686e1884bbbd1e8e29b202bee93f21 /BUILDING | |
| parent | d7d6f2875b9ec17c72d1b8147bc8c0e24fe995a3 (diff) | |
Re-add files that were accidentally deleted in my previous commit.
Diffstat (limited to 'BUILDING')
| -rw-r--r-- | BUILDING | 1115 |
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 |
