Module Name: src
Committed By: lukem
Date: Sun Jun 4 20:08:22 UTC 2023
Modified Files:
src: BUILDING
src/doc: BUILDING.mdoc
Log Message:
BUILDING: update from canonical mk.conf(5)
Incorporate content and styles updates for mk.conf entries
from share/man/man5/mk.conf.5, which is the canonical
reference for mk.conf.
Add: BSDOBJDIR, BSDSRCDIR, EXTERNAL_TOOLCHAIN, MKDEBUGKERNEL,
MKDEBUGTOOLS, MKHTML, MKLINKLIB, MKOBJDIRS, TOOLCHAIN_MISSING,
NETBSDSRCDIR
It's for further study as to whether we just replace the
most of subsection "make" variables with a link to mk.conf(5).
Style:
- Add more .de macros per mk.conf.5.
- Order list items alphabetically. When multiple items are present
in a list item, sort within the item first.
- More cross-references.
To generate a diff of this commit:
cvs rdiff -u -r1.150 -r1.151 src/BUILDING
cvs rdiff -u -r1.139 -r1.140 src/doc/BUILDING.mdoc
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/BUILDING
diff -u src/BUILDING:1.150 src/BUILDING:1.151
--- src/BUILDING:1.150 Fri Jun 2 20:48:41 2023
+++ src/BUILDING Sun Jun 4 20:08:21 2023
@@ -18,14 +18,8 @@ REQUIREMENTS
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.
+ BUILDING This document (in plaintext). Generated from
+ doc/BUILDING.mdoc.
Makefile The main Makefile for NetBSD; should only be run for
native builds with an appropriately up-to-date version of
@@ -51,18 +45,26 @@ FILES
Makefile semantics when building these programs for a
native host.
+ 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.
+
+ doc/BUILDING.mdoc
+ This document, in -mdoc troff format; the original copy.
+ Used to generate BUILDING.
+
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.
+ external/mit/xorg/
+ "Reachover" build structure for modular Xorg; the source
+ is in X11SRCDIR.
- tests/, regress/
+ regress/, tests/
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
@@ -74,15 +76,15 @@ FILES
This has a special method of determining out-of-date
status.
- bin/ ... usr.sbin/
+ tools/compat/README
+ Special notes for cross-hosting a NetBSD build on non-
+ NetBSD platforms.
+
+ Other directories including 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.
-
Build tree layout
The NetBSD build tree is described in hier(7), and the release layout is
described in release(7).
@@ -91,393 +93,555 @@ 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_CC Path name to C compiler used to create the toolchain.
+ HOST_CFLAGS Flags passed to the host C compiler.
- HOST_CFLAGS Flags passed to the host C compiler.
+ HOST_CXX Path name to C++ compiler used to create the toolchain.
- HOST_CXX Path name to C++ compiler used to create the toolchain.
+ HOST_CXXFLAGS Flags passed to the host C++ compiler.
- HOST_CXXFLAGS Flags passed to the host C++ compiler.
+ 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.
INSTALLBOOT_UBOOT_PATHS
- A colon-separated list of search paths used by
- installboot(8) to find U-Boot packages.
+ A colon-separated list of search paths used by
+ installboot(8) to find U-Boot packages.
- MACHINE Machine type, e.g., "macppc".
+ MACHINE Machine type, e.g., "macppc".
- MACHINE_ARCH Machine architecture, e.g., "powerpc".
+ MACHINE_ARCH Machine architecture, e.g., "powerpc".
- MAKE Path name to invoke make(1) as.
+ MAKE Path name to invoke make(1) as.
- MAKECONF The name of the make(1) configuration file. See "make"
- variables and mk.conf(5).
-
- Note: Only settable in the process environment.
-
- Default: "/etc/mk.conf"
-
- 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.
-
- Note: 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 in
- mk.conf(5) 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.
-
- Note: 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 in
- mk.conf(5) or MAKECONF.
-
- TMPDIR Top-level directory to store temporary directories used
- by build.sh before paths to other directories such as
- .OBJDIR can be determined.
+ MAKECONF The name of the make(1) configuration file. See "make"
+ variables and mk.conf(5).
+
+ Note: Only settable in the process environment.
+
+ Default: "/etc/mk.conf"
+
+ MAKEFLAGS Flags to invoke make(1) with.
+
+ Note: 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.
+
+ Note: 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 in mk.conf(5) 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.
+
+ Note: 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 in
+ mk.conf(5) or MAKECONF.
+
+ TMPDIR Top-level directory to store temporary directories used
+ by build.sh before paths to other directories such as
+ .OBJDIR can be determined.
- Note: Must support execution of binaries. I.e.,
- without mount(8)'s -o noexec option.
+ Note: Must support execution of binaries. I.e., without
+ mount(8)'s -o noexec option.
- Default: "/tmp".
+ Default: "/tmp".
"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 mk.conf(5) specified by
- MAKECONF. This list is not comprehensive; all supported variables and
- their defaults are documented in mk.conf(5).
+ MAKECONF.
+
+ This list is not comprehensive; all supported variables and their
+ defaults are documented in mk.conf(5).
+
+ BSDOBJDIR The real path to the object directory tree for the
+ NetBSD source tree.
+
+ Default: "/usr/obj"
+
+ BSDSRCDIR The real path to the NetBSD source tree, if NETBSDSRCDIR
+ isn't defined.
+
+ Default: "/usr/src"
+
+ 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 shown by "uname -v".
+
+ Default: Unset.
+
+ BUILDINFO Optional 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 g++(1) uses random numbers when compiling C++ code.
+ This variable seeds the g++(1) random number generator
+ using -frandom-seed 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
+ g++(1) documentation of -frandom-seed.
+
+ Default: Unset.
+
+ CPUFLAGS Additional flags to the compiler/assembler to select CPU
+ instruction set options, CPU tuning options, etc.
+
+ Default: Unset.
+
+ 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.
+
+ Note: build.sh will provide a default of destdir.MACHINE
+ (in the top-level .OBJDIR) unless run in `expert' mode.
+
+ Default: Empty string if USETOOLS is "yes"; unset
+ otherwise.
+
+ EXTERNAL_TOOLCHAIN
+ If defined, this variable indicates the root directory
+ of an external toolchain which will be used to build the
+ tree. For example, if a platform is a TOOLCHAIN_MISSING
+ platform, EXTERNAL_TOOLCHAIN can be used to re-enable
+ the cross-compile framework.
+
+ If EXTERNAL_TOOLCHAIN is defined, act as MKGCC=no, since
+ the external version of the compiler may not be able to
+ build the library components of the in-tree compiler.
+
+ This variable should be used in conjunction with an
+ appropriate HAVE_GCC or HAVE_LLVM setting to control the
+ compiler flags.
+
+ Note: This variable is not yet used in as many places as
+ it should be. Expect the exact semantics of this
+ variable to change in the short term as parts of the
+ cross-compile framework continue to be cleaned up.
+
+ Default: Unset.
+
+ 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 shown.
+
+ 2 Descriptive messages are shown as above (prefixed
+ with a `#'), and ordinary commands performed by
+ make(1) are shown.
+
+ 3 In addition to the above, all commands performed by
+ make(1) are shown, 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 and
+ installed.
+
+ Forced to "no" if MKMAN=no or MKSHARE=no.
+
+ Default: "no"
+
+ MKCROSSGDB Can be set to "yes" or "no". Create a cross-gdb as a
+ host tool.
- 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 shown by
- "uname -v".
+ Default: "no"
+
+ MKDEBUG Can be set to "yes" or "no". Indicates whether debug
+ information should be generated for all userland
+ binaries. The result is collected as an additional
+ debug.tgz and xdebug.tgz set and installed in
+ DESTDIR/usr/libdata/debug.
+
+ Forced to "no" if NODEBUG is defined, usually in the
+ Makefile before any make(1) .include directives.
+
+ Default: "no"
+
+ MKDEBUGKERNEL Can be set to "yes" or "no". Indicates whether
+ debugging symbols will be built for kernels by default;
+ pretend as if makeoptions DEBUG="-g" is specified in
+ kernel configuration files. This will also put the
+ debug kernel netbsd.gdb in the kernel sets. See
+ options(4) for details. This is useful if a cross-gdb
+ is built as well (see MKCROSSGDB).
+
+ Default: "no"
+
+ MKDEBUGLIB Can be set to "yes" or "no". Indicates whether debug
+ libraries (lib*_g.a) will be built and installed. Debug
+ libraries are compiled with "-g -DDEBUG".
+
+ Forced to "no" if NODEBUGLIB is defined, usually in the
+ Makefile before any make(1) .include directives.
+
+ Default: "no"
+
+ MKDEBUGTOOLS Can be set to "yes" or "no". Indicates whether debug
+ information (lib*_g.a) will be included in the build
+ toolchain.
+
+ Default: "no"
- Default: Unset.
+ MKDOC Can be set to "yes" or "no". Indicates whether system
+ documentation destined for DESTDIR/usr/share/doc will be
+ installed.
+
+ Forced to "no" if NODOC is defined, usually in the
+ Makefile before any make(1) .include directives.
+
+ Forced to "no" if MKSHARE=no.
+
+ 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.
- 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: "no"
- Default: Unset.
+ MKHTML Can be set to "yes" or "no". Indicates whether the HTML
+ manual pages are created and installed. and installed
- 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.
+ Forced to "no" if NOHTML is defined, usually in the
+ Makefile before any make(1) .include directives.
- CPUFLAGS Additional flags to the compiler/assembler to select CPU
- instruction set options, CPU tuning options, etc.
+ Forced to "no" if MKMAN=no or MKSHARE=no.
- Default: Unset.
+ Default: "yes"
- 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.
+ 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 built and installed.
- Default: Empty string if USETOOLS is "yes"; unset otherwise.
+ Forced to "no" if NOINFO is defined, usually in the
+ Makefile before any make(1) .include directives.
- Note: build.sh will provide a default of destdir.MACHINE (in
- the top-level .OBJDIR) unless run in `expert' mode.
+ Forced to "no" if MKSHARE=no.
- MAKEVERBOSE
- Level of verbosity of status messages. Supported values:
+ Default: "yes"
- 0 No descriptive messages or commands executed by make(1)
- are shown.
+ MKKDEBUG Deprecated, use MKDEBUGKERNEL.
- 1 Brief messages are shown describing what is being done,
- but the actual commands executed by make(1) are not
- shown.
+ MKKMOD Can be set to "yes" or "no". Indicates whether kernel
+ modules are built and installed.
- 2 Descriptive messages are shown as above (prefixed with a
- `#'), and ordinary commands performed by make(1) are
- shown.
+ Default: "no" on or1k; "yes" on other platforms.
- 3 In addition to the above, all commands performed by
- make(1) are shown, even if they would ordinarily have
- been hidden through use of the "@" prefix in the
- relevant makefile.
+ MKLINKLIB Can be set to "yes" or "no". Indicates whether all of
+ the shared library infrastructure will be built and
+ installed. If "no", prevents: installation of the *.a
+ libraries, installation of the *_pic.a libraries on PIC
+ systems, building of *.a libraries on PIC systems, or
+ installation of .so symlinks on ELF systems.
- 4 In addition to the above, commands executed by make(1)
- are traced through use of the sh(1) "-x" flag.
+ Forced to "no" if NOLINKLIB is defined, usually in the
+ Makefile before any make(1) .include directives.
- Default: 2
+ If "no", acts as MKLINT=no MKPICINSTALL=no MKPROFILE=no.
- MKCATPAGES Can be set to "yes" or "no". Indicates whether preformatted
- plaintext manual pages will be created during a build.
+ Default: "yes"
- Default: "no"
+ 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.
- MKCROSSGDB Can be set to "yes" or "no". Create a cross-gdb as a host
- tool.
+ Forced to "no" if NOLINT is defined, usually in the
+ Makefile before any make(1) .include directives.
- Default: "no"
+ Forced to "no" if MKLINKLIB=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"
- Default: "no"
+ MKMAN Can be set to "yes" or "no". Indicates whether manual
+ pages will be installed.
- MKDEBUGLIB Can be set to "yes" or "no". Indicates whether debug
- information (see MKDEBUG) should also be generated for all
- libraries built.
+ Forced to "no" if NOMAN is defined, usually in the
+ Makefile before any make(1) .include directives.
- Default: "no"
+ Forced to "no" if MKSHARE=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.
+ If "no", acts as MKCATPAGES=no MKHTML=no.
- Default: "yes"
+ Default: "yes"
- MKHTML Can be set to "yes" or "no". Indicates whether preformatted
- HTML manual pages will be built and installed
+ MKNLS Can be set to "yes" or "no". Indicates whether Native
+ Language System (NLS) locale zone files will be built
+ and installed.
- Default: "yes"
+ Forced to "no" if NONLS is defined, usually in the
+ Makefile before any make(1) .include directives.
- 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.
+ Forced to "no" if MKSHARE=no.
- Default: "no"
+ Default: "yes"
- MKINFO Can be set to "yes" or "no". Indicates whether GNU Info
- files will be created and installed during a build. GNU Info
- files are used for providing documentation by most of the
- compilation tools.
+ 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"
+ Forced to "no" if NOOBJ is defined, usually in the
+ Makefile before any make(1) .include directives.
- 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).
+ If "no", acts as MKOBJDIRS=no.
- Default: "no"
+ Note: Setting MKOBJ to "no" is not recommended and may
+ cause problems when updating the tree with cvs(1).
- MKKMOD Can be set to "yes" or "no". Indicates whether kernel
- modules are built and installed.
+ Default: "yes"
- Default: "yes"
+ 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.
- 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.
+ Forced to "no" if MKOBJ=no.
- Default: "no"
+ Default: "no"
- MKMAN Can be set to "yes" or "no". Indicates whether manual pages
- will be installed during a build.
+ MKPIC Can be set to "yes" or "no". Indicates whether shared
+ objects and libraries will be created and installed. If
+ "no", the entire built system will be statically linked.
- Default: "yes"
+ Forced to "no" if NOPIC is defined, usually in the
+ Makefile before any make(1) .include directives.
- MKNLS Can be set to "yes" or "no". Indicates whether Native
- Language System locale zone files will be compiled and
- installed during a build.
+ If "no", acts as MKPICLIB=no.
- Default: "yes"
+ Default: "no" on m68000; "yes" on other platforms.
- 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.
+ 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.
- Default: "yes"
+ Forced to "no" if NOPICINSTALL is defined, usually in
+ the Makefile before any make(1) .include directives.
- Note that setting MKOBJ to "no" is not recommended and may
- cause problems when updating the tree with cvs(1).
+ Forced to "no" if MKLINKLIB=no.
- 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: "no"
- Default: Platform dependent. As of this writing, all
- platforms except m68000 default to "yes".
+ MKPROFILE Can be set to "yes" or "no". Indicates whether profiled
+ libraries (lib*_p.a) will be built and installed.
- 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.
+ Forced to "no" if NOPROFILE is defined, usually in the
+ Makefile before any make(1) .include directives.
- Default: "yes"
+ Forced to "no" if MKLINKLIB=no.
- MKPROFILE Can be set to "yes" or "no". Indicates whether profiled
- libraries (lib*_p.a) will be built and installed during a
- build.
+ Default: "no" on or1k, riscv32, and riscv64 (due to
+ toolchain problems with profiled code); "yes" on other
+ platforms.
- 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". Indicates whether builds
+ are to be reproducible. If "yes", two builds from the
+ same source tree will produce the same build results.
- 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.
+ Used as the default for MKARZERO.
- Default: "no" This may be set to "yes" by giving build.sh the
- -P option.
+ This may be set to "yes" by giving build.sh the -P
+ option.
+
+ Default: "no" Can be set to "yes" or "no".
MKREPRO_TIMESTAMP
- Unix timestamp. When MKREPRO is set, the timestamp of all
- files in the sets will be set to this value.
+ Unix timestamp. When MKREPRO is set, the timestamp of
+ all files in the sets will be set to this value.
+
+ This may be set automatically to the latest source tree
+ timestamp using cvslatest(1) by giving build.sh the -P
+ option.
+
+ Default: Unset.
+
+ MKSHARE Can be set to "yes" or "no". Indicates whether files
+ destined to reside in DESTDIR/usr/share will be built
+ and installed.
+
+ Forced to "no" if NOSHARE is defined, usually in the
+ Makefile before any make(1) .include directives.
- 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.
+ If "no", acts as MKCATPAGES=no MKDOC=no MKINFO=no
+ MKHTML=no MKMAN=no MKNLS=no.
- Default: NETBSDSRCDIR/../xsrc, if that exists; otherwise
- /usr/xsrc.
+ 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.
+
+ Note: 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 and installed from X11SRCDIR.
+
+ Default: "no"
+
+ NETBSDSRCDIR The path to the top level of the NetBSD sources.
+
+ Default: Top level of the NetBSD source tree (as
+ determined by the presence of build.sh and tools/) if
+ make(1) is run from within that tree; otherwise
+ BSDSRCDIR will be used.
+
+ TOOLCHAIN_MISSING
+ Can be set to "yes" or "no". If not "no", this
+ indicates that the platform "MACHINE_ARCH" being built
+ does not have a working in-tree toolchain.
+
+ If not "no", acts as MKBINUTILS=no MKGCC=no MKGDB=no.
+
+ 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 Can be set to "yes" or "no". 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: "no" when using <bsd.*.mk> outside the NetBSD
+ source tree (detected automatically) or if
+ TOOLCHAIN_MISSING=yes; "yes" otherwise.
+
+ 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: NETBSDSRCDIR/../xsrc, if that exists; otherwise
+ /usr/xsrc.
"make" variables for full builds
These variables only affect the top level "Makefile" and do not affect
@@ -549,11 +713,11 @@ CONFIGURATION
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.
+ Default: Unset.
+
BUILDING
"make" command line options
This is not a summary of all the options available to make(1); only the
@@ -690,14 +854,14 @@ BUILDING
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: 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
+ Note: 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.
@@ -719,14 +883,14 @@ BUILDING
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: 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
+ Note: 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.
@@ -769,9 +933,11 @@ BUILDING
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.
+ on the local host.
+
+ Note: 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
@@ -838,9 +1004,11 @@ BUILDING
(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.
+ installworld".
+
+ Note: 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
@@ -1023,15 +1191,15 @@ BUILDING
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).
+ Note: 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: The 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
@@ -1067,10 +1235,11 @@ BUILDING
-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.
+ place the wrapper in PATH automatically.
+
+ Note: 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
@@ -1099,24 +1268,24 @@ BUILDING
with an absolute path.
EXAMPLES
- 1. % ./build.sh [options] tools kernel=GENERIC
+ 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
+ 2. % ./build.sh [OPTIONS] -U distribution
Using unprivileged mode, build a complete distribution to a DESTDIR
directory that build.sh selects (and will show).
- 3. # ./build.sh [options] -U install=/
+ 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
+ 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 show).
@@ -1132,8 +1301,11 @@ OBSOLETE VARIABLES
TOOLCHAIN_MISSING=yes.
SEE ALSO
- make(1), mk.conf(5), hier(7), release(7), etcupdate(8), installboot(8),
- mount(8), postinstall(8), sysinst(8), pkgsrc/sysutils/cdrtools
+ ar(1), config(1), ctags(1), cvs(1), cvslatest(1), ex(1), g++(1), gzip(1),
+ ident(1), ld(1), lint(1), make(1), mkisofs(1), sh(1), uname(1), vi(1),
+ options(4), mk.conf(5), atf(7), hier(7), release(7), sysctl(7),
+ etcupdate(8), installboot(8), mount(8), mtree(8), postinstall(8),
+ sysinst(8), pkgsrc/sysutils/cdrtools
HISTORY
The build.sh based build scheme was introduced for NetBSD 1.6 as
@@ -1145,4 +1317,4 @@ CAVEATS
in object directories. Instead, one may have to manually remove the
files. Consult the UPDATING file for notices concerning this.
-NetBSD May 18, 2023 NetBSD
+NetBSD June 4, 2023 NetBSD
Index: src/doc/BUILDING.mdoc
diff -u src/doc/BUILDING.mdoc:1.139 src/doc/BUILDING.mdoc:1.140
--- src/doc/BUILDING.mdoc:1.139 Fri Jun 2 20:48:41 2023
+++ src/doc/BUILDING.mdoc Sun Jun 4 20:08:21 2023
@@ -1,4 +1,4 @@
-.\" $NetBSD: BUILDING.mdoc,v 1.139 2023/06/02 20:48:41 lukem Exp $
+.\" $NetBSD: BUILDING.mdoc,v 1.140 2023/06/04 20:08:21 lukem Exp $
.\"
.\" Copyright (c) 2001-2023 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -33,9 +33,11 @@
.\" Toolchain prefix for commands
.ds toolprefix nb
.
-.Dd May 18, 2023
+.Dd June 4, 2023
.Dt BUILDING 8
.Os NetBSD
+.\" turn off hyphenation
+.hym 999
.
.\" if this file is processed with real roff (doc.tmac)
.\" now that the tmac files have been lazily read,
@@ -86,12 +88,12 @@ to override or manually select your comp
.Ss Source tree layout
.
.Bl -tag -width "BUILDING.mdoc"
-.It Pa doc/BUILDING.mdoc
-This document (in -mdoc troff format; the original copy).
+.
.It Pa BUILDING
This document (in plaintext).
-.It Pa tools/compat/README
-Special notes for cross-hosting a NetBSD build on non-NetBSD platforms.
+Generated from
+.Pa doc/BUILDING.mdoc .
+.
.It Pa Makefile
The main Makefile for
.Nx ;
@@ -104,11 +106,13 @@ it has been superseded by the
.Nm build.sh
shell script as the recommended means for building
.Nx .
+.
.It Pa UPDATING
Special notes for updating from an earlier revision of
.Nx .
It is important to read this file before every build of an updated
source tree.
+.
.It Pa build.sh
Bourne-compatible shell script used for building the host build tools
and the
@@ -119,6 +123,7 @@ Can be used for both native and cross bu
as it performs additional checks to prevent common issues going undetected, such
as building with an outdated version of
.Xr make 1 .
+.
.It Pa crypto/dist/ , dist/ , gnu/dist/
Sources imported verbatim from third parties, without mangling the
existing build structure.
@@ -131,6 +136,18 @@ use the
.Xr make 1
.Dq reachover
Makefile semantics when building these programs for a native host.
+.
+.It Pa distrib/ , etc/
+Sources for items used when making a full release snapshot, such as
+files installed in
+.Sy DESTDIR Ns Pa /etc
+on the destination system, boot media, and release notes.
+.
+.It Pa doc/BUILDING.mdoc
+This document, in -mdoc troff format; the original copy.
+Used to generate
+.Pa BUILDING .
+.
.It Pa external , sys/external
Sources and build infrastructure for components imported (mostly) unchanged
from upstream maintainers, sorted by applicable license.
@@ -140,12 +157,13 @@ This is (slowly) replacing the
and
.Pa gnu/dist
directories.
-.It Pa distrib/ , etc/
-Sources for items used when making a full release snapshot, such as
-files installed in
-.Sy DESTDIR Ns Pa /etc
-on the destination system, boot media, and release notes.
-.It Pa tests/ , regress/
+.
+.It Pa external/mit/xorg/
+.Dq Reachover
+build structure for modular Xorg; the source is in
+.Sy X11SRCDIR .
+.
+.It Pa regress/ , tests/
Regression test harness.
Can be cross-compiled, but only run natively.
.Pa tests/
@@ -155,22 +173,25 @@ test framework;
.Pa regress/
contains older tests that have not yet been migrated to
.Xr atf 7 .
+.
.It Pa sys/
.Nx
kernel sources.
+.
.It Pa tools/
.Dq Reachover
build structure for the host build tools.
This has a special method of determining out-of-date status.
-.It Pa bin/ ... usr.sbin/
+.
+.It Pa tools/compat/README
+Special notes for cross-hosting a NetBSD build on non-NetBSD platforms.
+.
+.It Other directories including Pa bin/ ... usr.sbin/
Sources to the
.Nx
userland (non-kernel) programs.
If any of these directories are missing, they will be skipped during the build.
-.It Pa external/mit/xorg/
-.Dq Reachover
-build structure for modular Xorg; the source is in
-.Sy X11SRCDIR .
+.
.El
.
.Ss Build tree layout
@@ -186,16 +207,14 @@ and the release layout is described in
.
.Ss Environment variables
.
-.de YorN
-Can be set to
-.Dq yes
-or
-.Dq no .
-..
.de DFLT
.Pp
.Em Default :
..
+.de DFLTn
+.DFLT
+.Dq no
+..
.de DFLTu
.DFLT
Unset.
@@ -204,16 +223,49 @@ Unset.
.DFLT
.Dq yes
..
-.de DFLTn
-.DFLT
+.de NODEF
+.Pp
+Forced to
.Dq no
+if
+.Sy \\$*
+is defined,
+usually in the Makefile before any
+.Xr make 1
+.Cm \&.include
+directives.
+..
+.de NOVAR
+.Pp
+Forced to
+.Dq no
+if
+.Sy \\$* .
+..
+.de YorN
+Can be set to
+.Dq yes
+or
+.Dq no .
..
+.
Several environment variables control the behaviour of
.Nx
builds.
.
-.Bl -tag -width "MAKEOBJDIRPREFIX"
+.Bl -tag -width 15n
+.
+.It Sy HOST_CC
+Path name to C compiler used to create the toolchain.
+.
+.It Sy HOST_CFLAGS
+Flags passed to the host C compiler.
+.
+.It Sy HOST_CXX
+Path name to C++ compiler used to create the toolchain.
.
+.It Sy HOST_CXXFLAGS
+Flags passed to the host C++ compiler.
.
.It Sy HOST_SH
Path name to a shell available on the host system
@@ -246,18 +298,6 @@ allows it to be a simple command name, w
to an absolute path by searching the
.Sy PATH .
.
-.It Sy HOST_CC
-Path name to C compiler used to create the toolchain.
-.
-.It Sy HOST_CFLAGS
-Flags passed to the host C compiler.
-.
-.It Sy HOST_CXX
-Path name to C++ compiler used to create the toolchain.
-.
-.It Sy HOST_CXXFLAGS
-Flags passed to the host C++ compiler.
-.
.It Sy INSTALLBOOT_UBOOT_PATHS
A colon-separated list of search paths used by
.Xr installboot 8
@@ -294,7 +334,8 @@ Only settable in the process environment
Flags to invoke
.Xr make 1
with.
-Note that
+.Pp
+.Em Note :
.Sy build.sh
ignores the value of
.Sy MAKEFLAGS
@@ -398,11 +439,31 @@ configuration file
.Xr mk.conf 5
specified by
.Sy MAKECONF .
+.Pp
This list is not comprehensive;
all supported variables and their defaults are documented in
.Xr mk.conf 5 .
.
-.Bl -tag -width "MKCATPAGES"
+.Bl -tag -width 15n
+.
+.\" These entries are sorted alphabetically.
+.\" Keep in sync with canonical reference share/man/man5/mk.conf.5.
+.
+.It Sy BSDOBJDIR
+The real path to the object directory tree for the
+.Nx
+source tree.
+.DFLT
+.Dq Pa /usr/obj
+.
+.It Sy BSDSRCDIR
+The real path to the
+.Nx
+source tree, if
+.Sy NETBSDSRCDIR
+isn't defined.
+.DFLT
+.Dq Pa /usr/src
.
.It Sy BUILDID
Identifier for the build.
@@ -419,7 +480,7 @@ which can be shown by
.DFLTu
.
.It Sy BUILDINFO
-This may be a multi-line string containing information about the build.
+Optional multi-line string containing information about the build.
This will appear in
.Sy DESTDIR Ns Pa /etc/release ,
and it will be stored in the
@@ -438,14 +499,22 @@ and
.DFLTu
.
.It Sy 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).
+.Xr g++ 1
+uses random numbers when compiling C++ code.
+This variable seeds the
+.Xr g++ 1
+random number generator using
+.Fl frandom-seed
+with this value.
+By default, it is set to
+.Do NetBSD-( Ns Em majorversion ) Dc .
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.
+Additional information is available in the
+.Xr g++ 1
+documentation of
+.Fl frandom-seed .
+.DFLTu
.
.It Sy CPUFLAGS
Additional flags to the compiler/assembler to select
@@ -471,12 +540,6 @@ to an empty string, not to
.Dq / ) .
The directory must reside on a file system which supports long file
names and hard links.
-.DFLT
-Empty string if
-.Sy USETOOLS
-is
-.Dq yes ;
-unset otherwise.
.Pp
.Em Note :
.Sy build.sh
@@ -487,11 +550,45 @@ will provide a default of
unless run in
.Sq expert
mode.
+.DFLT
+Empty string if
+.Sy USETOOLS
+is
+.Dq yes ;
+unset otherwise.
+.
+.It Sy EXTERNAL_TOOLCHAIN
+If defined, this variable indicates the root directory of
+an external toolchain which will be used to build the tree.
+For example, if a platform is a
+.Sy TOOLCHAIN_MISSING
+platform,
+.Sy EXTERNAL_TOOLCHAIN
+can be used to re-enable the cross-compile framework.
+.Pp
+If
+.Sy EXTERNAL_TOOLCHAIN
+is defined, act as
+.Sy MKGCC=no ,
+since the external version of the compiler may not be
+able to build the library components of the in-tree compiler.
+.Pp
+This variable should be used in conjunction with an appropriate
+.Sy HAVE_GCC
+or
+.Sy HAVE_LLVM
+setting to control the compiler flags.
+.Pp
+.Em Note :
+This variable is not yet used in as many places as it should be.
+Expect the exact semantics of this variable to change in the short
+term as parts of the cross-compile framework continue to be cleaned up.
+.DFLTu
.
.It Sy MAKEVERBOSE
Level of verbosity of status messages.
Supported values:
-.Bl -tag -width xxx
+.Bl -tag -width 2n
.It 0
No descriptive messages or commands executed by
.Xr make 1
@@ -528,7 +625,8 @@ flag.
.It Sy MKCATPAGES
.YorN
Indicates whether preformatted plaintext manual pages will be created
-during a build.
+and installed.
+.NOVAR MKMAN=no No or Sy MKSHARE=no
.DFLTn
.
.It Sy MKCROSSGDB
@@ -538,34 +636,57 @@ Create a cross-gdb as a host tool.
.
.It Sy MKDEBUG
.YorN
-Indicates whether debug information should be generated for all userland
-binaries compiled.
+Indicates whether debug information should be generated for
+all userland binaries.
The result is collected as an additional
.Sy debug.tgz
and
.Sy xdebug.tgz
set and installed in
-.Pa /usr/libdata/debug .
+.Sy DESTDIR Ns Pa /usr/libdata/debug .
+.NODEF NODEBUG
+.DFLTn
+.
+.It Sy MKDEBUGKERNEL
+.YorN
+Indicates whether debugging symbols will be built for kernels
+by default; pretend as if
+.Em makeoptions DEBUG="-g"
+is specified in kernel configuration files.
+This will also put the debug kernel
+.Pa netbsd.gdb
+in the kernel sets.
+See
+.Xr options 4
+for details.
+This is useful if a cross-gdb is built as well (see
+.Sy MKCROSSGDB ) .
.DFLTn
.
.It Sy MKDEBUGLIB
.YorN
-Indicates whether debug information (see
-.Sy MKDEBUG )
-should also be generated for all libraries built.
+Indicates whether debug libraries
+.Sy ( lib*_g.a )
+will be built and installed.
+Debug libraries are compiled with
+.Dq Li -g -DDEBUG .
+.NODEF NODEBUGLIB
+.DFLTn
+.
+.It Sy MKDEBUGTOOLS
+.YorN
+Indicates whether debug information
+.Sy ( lib*_g.a )
+will be included in the build toolchain.
.DFLTn
.
.It Sy MKDOC
.YorN
Indicates whether system documentation destined for
.Sy DESTDIR Ns Pa /usr/share/doc
-will be installed during a build.
-.DFLTy
-.
-.It Sy MKHTML
-.YorN
-Indicates whether preformatted HTML manual pages will be built
-and installed
+will be installed.
+.NODEF NODOC
+.NOVAR MKSHARE=no
.DFLTy
.
.It Sy MKHOSTOBJ
@@ -583,28 +704,61 @@ then programs built to be run on the com
object directory names as programs built to be run on the target.
.DFLTn
.
+.It Sy MKHTML
+.YorN
+Indicates whether the HTML manual pages are created and installed.
+and installed
+.NODEF NOHTML
+.NOVAR MKMAN=no No or Sy MKSHARE=no
+.DFLTy
+.
.It Sy MKINFO
.YorN
-Indicates whether GNU Info files will be created and installed during a build.
-GNU Info files are used for providing documentation by most of the compilation
-tools.
+Indicates whether GNU Info files, used for the documentation for
+most of the compilation tools, will be built and installed.
+.NODEF NOINFO
+.NOVAR MKSHARE=no
.DFLTy
.
.It Sy MKKDEBUG
-.YorN
-Force generation of full-debug symbol versions of all kernels compiled.
-Alongside of the
-.Pa netbsd
-kernel file, an unstripped version
-.Pa netbsd.gdb
-is created.
-This is useful if a cross-gdb is built as well (see
-.Sy MKCROSSGDB ) .
-.DFLTn
+Deprecated, use
+.Sy MKDEBUGKERNEL .
.
.It Sy MKKMOD
.YorN
Indicates whether kernel modules are built and installed.
+.DFLTn
+on
+.Sy or1k ;
+.Dq yes
+on other platforms.
+.
+.It Sy MKLINKLIB
+.YorN
+Indicates whether all of the shared library infrastructure
+will be built and installed.
+If
+.Dq no ,
+prevents:
+installation of the
+.Sy *.a
+libraries,
+installation of the
+.Sy *_pic.a
+libraries on PIC systems,
+building of
+.Sy *.a
+libraries on PIC systems,
+or
+installation of
+.Sy .so
+symlinks on ELF systems.
+.NODEF NOLINKLIB
+.Pp
+If
+.Dq no ,
+acts as
+.Sy MKLINT=no MKPICINSTALL=no MKPROFILE=no .
.DFLTy
.
.It Sy MKLINT
@@ -616,17 +770,28 @@ will be run against portions of the
source code during the build, and whether lint libraries will be
installed into
.Sy DESTDIR Ns Pa /usr/libdata/lint .
+.NODEF NOLINT
+.NOVAR MKLINKLIB=no
.DFLTn
.
.It Sy MKMAN
.YorN
-Indicates whether manual pages will be installed during a build.
+Indicates whether manual pages will be installed.
+.NODEF NOMAN
+.NOVAR MKSHARE=no
+.Pp
+If
+.Dq no ,
+acts as
+.Sy MKCATPAGES=no MKHTML=no .
.DFLTy
.
.It Sy MKNLS
.YorN
-Indicates whether Native Language System locale zone files will be
-compiled and installed during a build.
+Indicates whether Native Language System (NLS) locale zone files will be
+built and installed.
+.NODEF NONLS
+.NOVAR MKSHARE=no
.DFLTy
.
.It Sy MKOBJ
@@ -636,28 +801,49 @@ Indicates whether object directories wil
If set to
.Dq no ,
then all built files will be located inside the regular source tree.
-.DFLTy
+.NODEF NOOBJ
+.Pp
+If
+.Dq no ,
+acts as
+.Sy MKOBJDIRS=no .
.Pp
-Note that setting
+.Em Note :
+Setting
.Sy MKOBJ
to
.Dq no
is not recommended and may cause problems when updating the tree with
.Xr cvs 1 .
+.DFLTy
+.
+.It Sy MKOBJDIRS
+.YorN
+Indicates whether object directories will be created automatically
+(via a
+.Dq make obj
+pass) at the start of a build.
+.NOVAR MKOBJ=no
+.DFLTn
.
.It Sy MKPIC
.YorN
Indicates whether shared objects and libraries will be created and
-installed during a build.
-If set to
+installed.
+If
.Dq no ,
the entire built system will be statically linked.
-.DFLT
-Platform dependent.
-As of this writing, all platforms except
-.Sy m68000
-default to
-.Dq yes .
+.NODEF NOPIC
+.Pp
+If
+.Dq no ,
+acts as
+.Sy MKPICLIB=no .
+.DFLTn
+on
+.Sy m68000 ;
+.Dq yes
+on other platforms.
.
.It Sy MKPICINSTALL
.YorN
@@ -665,26 +851,40 @@ Indicates whether the
.Xr ar 1
format libraries
.Sy ( lib*_pic.a ) ,
-used to generate shared libraries, are installed during a build.
-.DFLTy
+used to generate shared libraries, are installed.
+.NODEF NOPICINSTALL
+.NOVAR MKLINKLIB=no
+.DFLTn
.
.It Sy MKPROFILE
.YorN
Indicates whether profiled libraries
.Sy ( lib*_p.a )
-will be built and installed during a build.
-.DFLT
-.Dq yes ;
-however, some platforms turn off
-.Sy MKPROFILE
-by default at times due to toolchain problems with profiled code.
+will be built and installed.
+.NODEF NOPROFILE
+.NOVAR MKLINKLIB=no
+.DFLTn
+on
+.Sy or1k ,
+.Sy riscv32 ,
+and
+.Sy riscv64
+(due to toolchain problems with profiled code);
+.Dq yes
+on other platforms.
.
.It Sy MKREPRO
.YorN
-Create reproducible builds.
-This enables different switches to make two builds from the same
-source tree result in the same build results.
-.DFLTn
+Indicates whether builds are to be reproducible.
+If
+.Dq yes ,
+two builds from the same source tree will produce the same build
+results.
+.Pp
+Used as the default for
+.Sy MKARZERO .
+.Pp
+.\" Note: This paragraph is not in share/man/man5/mk.conf.5.
This may be set to
.Dq yes
by giving
@@ -692,6 +892,8 @@ by giving
the
.Fl P
option.
+.DFLTn
+.YorN
.
.It Sy MKREPRO_TIMESTAMP
Unix timestamp.
@@ -699,7 +901,8 @@ When
.Sy MKREPRO
is set, the timestamp of all files in the sets will be set
to this value.
-.DFLTu
+.Pp
+.\" Note: This paragraph is not in share/man/man5/mk.conf.5.
This may be set automatically to the latest source tree timestamp
using
.Xr cvslatest 1
@@ -708,21 +911,19 @@ by giving
the
.Fl P
option.
+.DFLTu
.
.It Sy MKSHARE
.YorN
Indicates whether files destined to reside in
.Sy DESTDIR Ns Pa /usr/share
-will be built and installed during a build.
-If set to
+will be built and installed.
+.NODEF NOSHARE
+.Pp
+If
.Dq no ,
-then all of
-.Sy MKCATPAGES , MKDOC , MKINFO , MKMAN ,
-and
-.Sy MKNLS
-will be set to
-.Dq no
-unconditionally.
+acts as
+.Sy MKCATPAGES=no MKDOC=no MKINFO=no MKHTML=no MKMAN=no MKNLS=no .
.DFLTy
.
.It Sy MKSTRIPIDENT
@@ -741,7 +942,7 @@ strip all local symbols from shared libr
the affect is equivalent to the
.Fl x
option of
-.Xr ld 1 .
+.Xr ld 1 .
If
.Dq no ,
strip only temporary local symbols; the affect is equivalent
@@ -776,15 +977,50 @@ Indicates whether all install operations
.Sy DESTDIR
will compare file timestamps before installing, and skip the install
phase if the destination files are up-to-date.
+.Pp
+.\" Note: This paragraph is not in share/man/man5/mk.conf.5.
+.Em Note :
This also has implications on full builds (see next subsection).
.DFLTn
.
.It Sy MKX11
.YorN
-Indicates whether X11 is built from
+Indicates whether X11 is built and installed from
.Sy X11SRCDIR .
.DFLTn
.
+.It Sy NETBSDSRCDIR
+The path to the top level of the
+.Nx
+sources.
+.DFLT
+Top level of the
+.Nx
+source tree (as determined by the presence of
+.Pa build.sh
+and
+.Pa tools/ )
+if
+.Xr make 1
+is run from within that tree;
+otherwise
+.Sy BSDSRCDIR
+will be used.
+.
+.It Sy TOOLCHAIN_MISSING
+.YorN
+If not
+.Dq no ,
+this indicates that the platform
+.Dq Sy MACHINE_ARCH
+being built does not have a working in-tree toolchain.
+.Pp
+If not
+.Dq no ,
+acts as
+.Sy MKBINUTILS=no MKGCC=no MKGDB=no .
+.DFLTn
+.
.It Sy TOOLDIR
Directory to hold the host tools, once built.
If specified, must be an absolute path.
@@ -803,6 +1039,7 @@ of
.DFLTu
.
.It Sy USETOOLS
+.YorN
Indicates whether the tools specified by
.Sy TOOLDIR
should be used as part of a build in progress.
@@ -810,15 +1047,15 @@ Must be set to
.Dq yes
if cross-compiling.
.Bl -tag -width "never"
-.It Sy yes
+.It yes
Use the tools from
.Sy TOOLDIR .
-.It Sy no
+.It no
Do not use the tools from
.Sy TOOLDIR ,
but refuse to build native compilation tool components that are
version-specific for that tool.
-.It Sy never
+.It never
Do not use the tools from
.Sy TOOLDIR ,
even when building native tool components.
@@ -832,21 +1069,15 @@ This may cause build or runtime problems
.Nx
source tree.
.El
-.DFLT
-.Dq yes ,
-unless
-.Sy TOOLCHAIN_MISSING
-is set to
-.Dq yes .
-.Pp
-.Sy USETOOLS
-is also set to
-.Dq no
+.DFLTn
when using
.Aq bsd.*.mk
outside the
.Nx
-source tree.
+source tree (detected automatically) or if
+.Sy TOOLCHAIN_MISSING=yes ;
+.Dq yes
+otherwise.
.
.It Sy X11SRCDIR
Directory containing the modular Xorg source.
@@ -868,7 +1099,7 @@ and do not affect manually building subt
.Nx
source code.
.
-.Bl -tag -width "INSTALLWORLDDIR"
+.Bl -tag -width 15n
.
.It Sy INSTALLBOOT_BOARDS
A list of boards to create bootable images for.
@@ -981,7 +1212,6 @@ If set, specifies the directory to which
layout will be written at the end of a
.Dq make release .
If specified, must be an absolute path.
-.DFLTu
.Pp
.Em Note :
.Sy build.sh
@@ -992,6 +1222,7 @@ will provide a default of
unless run in
.Sq expert
mode.
+.DFLTu
.
.El
.
@@ -1270,7 +1501,8 @@ is attempted, RELEASEDIR must be populat
.Dq make release
or equivalent.
.Pp
-Note that other, smaller, CD-ROM images may be created in the
+.Em Note :
+Other, smaller, CD-ROM images may be created in the
.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom
directory by
.Dq "make release" .
@@ -1278,7 +1510,8 @@ These smaller images usually contain the
.Sy RELEASEDIR Ns Pa /images ,
but do not contain additional content such as the distribution sets.
.Pp
-Note that the mac68k port still uses an older method of creating
+.Em Note :
+The mac68k port still uses an older method of creating
CD-ROM images.
This requires the
.Xr mkisofs 1
@@ -1314,7 +1547,8 @@ is attempted, RELEASEDIR must be populat
.Dq make sourcesets release
or equivalent.
.Pp
-Note that other, smaller, CD-ROM images may be created in the
+.Em Note :
+Other, smaller, CD-ROM images may be created in the
.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom
directory by
.Dq make release .
@@ -1322,7 +1556,8 @@ These smaller images usually contain the
.Sy RELEASEDIR Ns Pa /images ,
but do not contain additional content such as the distribution sets.
.Pp
-Note that the mac68k port still uses an older method of creating
+.Em Note :
+The mac68k port still uses an older method of creating
CD-ROM images.
This requires the
.Xr mkisofs 1
@@ -1406,7 +1641,9 @@ relies on information in
Can only be run after building the regression tests in the directory
.Dq regress .
Runs those compiled regression tests on the local host.
-Note that most tests are now managed instead using
+.Pp
+.Em Note :
+Most tests are now managed instead using
.Xr atf 7 ;
this target should probably run those as well but currently does not.
.
@@ -1556,7 +1793,9 @@ to
.Ar idir ,
using
.Dq make installworld .
-Note that files that are part of the
+.Pp
+.Em Note :
+Files that are part of the
.Dq etc
or
.Dq xetc
@@ -1947,7 +2186,8 @@ it is determined by complex rules that a
by the values of several variables and
by the location of the source directory.
.Pp
-Note that placing the
+.Em Note :
+Placing the
.Ar obj
directory location outside of the default source tree hierarchy makes
it easier to manually clear out old files in the event the
@@ -1957,7 +2197,8 @@ operation is unable to do so.
.Sx CAVEATS
below.)
.Pp
-Note also that use of one of
+.Em Note :
+The use of one of
.Fl M
or
.Fl O
@@ -2055,7 +2296,8 @@ specified by
This allows, for instance, to place the wrapper in
.Sy PATH
automatically.
-Note that
+.Pp
+.Em Note :
.Ar 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
@@ -2124,13 +2366,13 @@ or called with an absolute path.
.Bl -enum
.
.It
-.Li "% ./build.sh [options] tools kernel=GENERIC"
+.Li "% ./build.sh [OPTIONS] tools kernel=GENERIC"
.Pp
Build a new toolchain, and use the new toolchain to
configure and build a new GENERIC kernel.
.
.It
-.Li "% ./build.sh [options] -U distribution"
+.Li "% ./build.sh [OPTIONS] -U distribution"
.Pp
Using unprivileged mode,
build a complete distribution to a
@@ -2140,7 +2382,7 @@ directory that
selects (and will show).
.
.It
-.Li "# ./build.sh [options] -U install=/"
+.Li "# ./build.sh [OPTIONS] -U install=/"
.Pp
As root, install to
.Pa /
@@ -2154,7 +2396,7 @@ are correctly applied to the files as th
.Pa / .
.
.It
-.Li "% ./build.sh [options] -U -u release"
+.Li "% ./build.sh [OPTIONS] -U -u release"
.Pp
Using unprivileged mode,
build a complete release to
@@ -2189,13 +2431,32 @@ To disable, use
.Sy TOOLCHAIN_MISSING=yes .
.El
.Sh SEE ALSO
+.Xr ar 1 ,
+.Xr config 1 ,
+.Xr ctags 1 ,
+.Xr cvs 1 ,
+.Xr cvslatest 1 ,
+.Xr ex 1 ,
+.Xr g++ 1 ,
+.Xr gzip 1 ,
+.Xr ident 1 ,
+.Xr ld 1 ,
+.Xr lint 1 ,
.Xr make 1 ,
+.Xr mkisofs 1 ,
+.Xr sh 1 ,
+.Xr uname 1 ,
+.Xr vi 1 ,
+.Xr options 4 ,
.Xr mk.conf 5 ,
+.Xr atf 7 ,
.Xr hier 7 ,
.Xr release 7 ,
+.Xr sysctl 7 ,
.Xr etcupdate 8 ,
.Xr installboot 8 ,
.Xr mount 8 ,
+.Xr mtree 8 ,
.Xr postinstall 8 ,
.Xr sysinst 8 ,
.Pa pkgsrc/sysutils/cdrtools
