Module Name: src
Committed By: lukem
Date: Sun Jun 11 20:34:14 UTC 2023
Modified Files:
src: BUILDING
src/doc: BUILDING.mdoc
Log Message:
BUILDING: remove duplication from mk.conf(5)
Remove all "make" variables / mk.conf(5) variables already documented
in mk.conf(5). The duplication was a maintenance headache, as I've
experienced over recent weeks getting the build documentation up to
date.
Add notes clarifying that manual page references are to the NetBSD
manual pages, not to the host manual pages, and how to format from
source, or find online at https://man.netbsd.org.
Add explicit links to the mdoc(7) in-tree source for mk.conf(5),
hier(7), and release(7) because those are directly relevant to the host
build information in BUILDING.
Note: We don't normally need these notes for native documentation,
but BUILDING is intended for users on host systems which might not
be NetBSD(-current).
Add missing defaults.
To generate a diff of this commit:
cvs rdiff -u -r1.154 -r1.155 src/BUILDING
cvs rdiff -u -r1.143 -r1.144 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.154 src/BUILDING:1.155
--- src/BUILDING:1.154 Sun Jun 11 10:49:43 2023
+++ src/BUILDING Sun Jun 11 20:34:14 2023
@@ -16,6 +16,13 @@ REQUIREMENTS
the NetBSD build process. (See the Environment variables section below
if you need to override or manually select your compilers.)
+ Note: Within this document, cross-references to manual pages are to the
+ NetBSD manual pages, not the host system manual pages. The mdoc(7)
+ source to the NetBSD manual pages can be found within the source tree,
+ and these and can be formatted with mandoc(1) or nroff(1) if those are
+ available on the host system. The NetBSD manual pages are also available
+ at https://man.netbsd.org
+
FILES
Source tree layout
BUILDING This document (in plaintext). Generated from
@@ -51,8 +58,8 @@ FILES
destination system, boot media, and release notes.
doc/BUILDING.mdoc
- This document, in -mdoc troff format; the original copy.
- Used to generate BUILDING.
+ The source to this document, in mdoc(7) format. Used to
+ generate BUILDING.
external, sys/external
Sources and build infrastructure for components imported
@@ -86,8 +93,9 @@ FILES
during the build.
Build tree layout
- The NetBSD build tree is described in hier(7), and the release layout is
- described in release(7).
+ The NetBSD build tree is described in hier(7) (mdoc(7) source in
+ share/man/man7/hier.7), and the release layout is described in release(7)
+ (mdoc(7) source in share/man/man7/release.7).
CONFIGURATION
Environment variables
@@ -95,12 +103,24 @@ CONFIGURATION
HOST_CC Path name to C compiler used to create the toolchain.
+ Default: "cc".
+
HOST_CFLAGS Flags passed to the host C compiler.
+ Default: "-O".
+
+ HOST_CPPFLAGS Flags passed to the host C/C++ pre-processor.
+
+ Default: Unset.
+
HOST_CXX Path name to C++ compiler used to create the toolchain.
+ Default: Unset, but defaults to "c++" where required.
+
HOST_CXXFLAGS Flags passed to the host C++ compiler.
+ Default: Unset.
+
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-
@@ -119,22 +139,32 @@ CONFIGURATION
name, which will be converted to an absolute path by
searching the PATH.
+ Default: "sh".
+
INSTALLBOOT_UBOOT_PATHS
A colon-separated list of search paths used by
installboot(8) to find U-Boot packages.
+ Default: Unset.
+
MACHINE Machine type, e.g., "macppc".
+ Default: Unset.
+
MACHINE_ARCH Machine architecture, e.g., "powerpc".
+ Default: Unset.
+
MAKE Path name to invoke make(1) as.
+ Default: "make".
+
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"
+ Default: "/etc/mk.conf".
MAKEFLAGS Flags to invoke make(1) with.
@@ -142,6 +172,9 @@ CONFIGURATION
the environment, but allows MAKEFLAGS to be set via the
-V option.
+ Default: "-X" on systems with a small ARG_MAX (Cygwin,
+ Darwin, FreeBSD); otherwise unset.
+
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
@@ -154,6 +187,8 @@ CONFIGURATION
or via the -O flag of build.sh; it cannot usefully be set
inside a Makefile, including in mk.conf(5) or MAKECONF.
+ Default: Unset.
+
MAKEOBJDIRPREFIX
Top level directory of the object directory tree. The
value is subjected to variable expansion by make(1).
@@ -171,6 +206,8 @@ CONFIGURATION
usefully be set inside a Makefile, including in
mk.conf(5) or MAKECONF.
+ Default: Unset.
+
TMPDIR Top-level directory to store temporary directories used
by build.sh before paths to other directories such as
.OBJDIR can be determined.
@@ -181,539 +218,12 @@ CONFIGURATION
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).
-
- 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.
-
- COPTS Extra options for the C compiler. Should be appended to
- (e.g., COPTS+=-g), rather than explicitly set.
-
- Note: CPUFLAGS, not COPTS, should be used for compiler
- flags that select CPU-related options.
-
- Note: CFLAGS should never be set in mk.conf(5).
-
- CPUFLAGS Additional options passed to the compiler/assembler to
- select CPU instruction set options, CPU tuning options,
- etc.
-
- Note: Such options should not be specified in COPTS,
- because some parts of the build process need to override
- CPU-related compiler options.
-
- 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=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.
-
- INSTALLBOOT_BOARDS
- A list of evbarm boards to create bootable images for.
- If corresponding U-Boot packages are installed, bootable
- images are created as part of a release. See the
- -o board=name option of installboot(8).
-
- INSTALLWORLDDIR
- Location for the top-level "make installworld" target to
- install to. If specified, must be an absolute path.
-
- Default: "/"
-
- 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.
-
- 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"
-
- 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 "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
- architecture.) If "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 architecture.
-
- Default: "no"
-
- MKHTML Can be set to "yes" or "no". Indicates whether the HTML
- manual pages are created and installed.
-
- Forced to "no" if NOHTML is defined, usually in the
- Makefile before any make(1) .include directives.
-
- Forced to "no" if MKMAN=no or MKSHARE=no.
-
- Default: "yes"
-
- 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.
-
- Forced to "no" if NOINFO is defined, usually in the
- Makefile before any make(1) .include directives.
-
- Forced to "no" if MKSHARE=no.
-
- Default: "yes"
-
- MKKMOD Can be set to "yes" or "no". Indicates whether kernel
- modules will be built and installed.
-
- Default: "no" on or1k; "yes" on other platforms.
-
- 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
- - installation of .so symlinks on ELF systems
-
- I.e, only install the shared library (and the .so.major
- symlink on ELF).
-
- Forced to "no" if NOLINKLIB is defined, usually in the
- Makefile before any make(1) .include directives.
+ Variables control the behavior of NetBSD builds are documented in
+ mk.conf(5) (mdoc(7) source in share/man/man5/mk.conf.5).
- If "no", acts as MKLINT=no MKPICINSTALL=no MKPROFILE=no.
-
- 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.
-
- Forced to "no" if NOLINT is defined, usually in the
- Makefile before any make(1) .include directives.
-
- Forced to "no" if MKLINKLIB=no.
-
- Default: "no"
-
- MKMAN Can be set to "yes" or "no". Indicates whether manual
- pages will be installed.
-
- Forced to "no" if NOMAN is defined, usually in the
- Makefile before any make(1) .include directives.
-
- Forced to "no" if MKSHARE=no.
-
- If "no", acts as MKCATPAGES=no MKHTML=no.
-
- Default: "yes"
-
- MKNLS Can be set to "yes" or "no". Indicates whether Native
- Language System (NLS) locale zone files will be built and
- installed.
-
- Forced to "no" if NONLS is defined, usually in the
- Makefile before any make(1) .include directives.
-
- Forced to "no" if MKSHARE=no.
-
- Default: "yes"
-
- MKOBJ Can be set to "yes" or "no". Indicates whether object
- directories will be created when running "make obj". If
- "no", then all built files will be located inside the
- regular source tree.
-
- Forced to "no" if NOOBJ is defined, usually in the
- Makefile before any make(1) .include directives.
-
- If "no", acts as MKOBJDIRS=no.
-
- Note: Setting MKOBJ to "no" is not recommended and may
- cause problems when updating the tree with cvs(1).
-
- 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.
-
- Forced to "no" if MKOBJ=no.
-
- Note: If using build.sh, the default is "yes". This may
- be set back to "no" by giving build.sh the -o option.
-
- Default: "no"
-
- 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.
-
- Forced to "no" if NOPIC is defined, usually in the
- Makefile before any make(1) .include directives.
-
- If "no", acts as MKPICLIB=no.
-
- Default: "no" on m68000; "yes" on other platforms.
-
- 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.
-
- Forced to "no" if NOPICINSTALL is defined, usually in the
- Makefile before any make(1) .include directives.
-
- Forced to "no" if MKLINKLIB=no.
-
- Default: "no"
-
- MKPROFILE Can be set to "yes" or "no". Indicates whether profiled
- libraries (lib*_p.a) will be built and installed.
-
- Forced to "no" if NOPROFILE is defined, usually in the
- Makefile before any make(1) .include directives.
-
- Forced to "no" if MKLINKLIB=no.
-
- Default: "no" on or1k, riscv32, and riscv64 (due to
- toolchain problems with profiled code); "yes" on other
- platforms.
-
- 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.
-
- Used as the default for MKARZERO.
-
- Note: This may be set to "yes" by giving build.sh the -P
- option.
-
- Default: "no"
-
- MKREPRO_TIMESTAMP
- Unix timestamp. When MKREPRO is set, the timestamp of
- all files in the sets will be set to this value.
-
- Note: 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.
-
- If "no", acts as MKCATPAGES=no MKDOC=no MKINFO=no
- MKHTML=no MKMAN=no MKNLS=no.
-
- 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
- effect is equivalent to the -x option of ld(1). If "no",
- strip only temporary local symbols; the effect 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 METALOG
- contents are used during the generation of the
- distribution tar files to ensure that the appropriate
- file ownership is stored. This allows a non-root `make
- install'.
-
- 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.
-
- For top-level builds this this implies the effects of
- NOCLEANDIR (i.e., "make cleandir" is avoided).
-
- Note: If using build.sh, this may be set by giving the -u
- option.
-
- Default: "no"
-
- MKX11 Can be set to "yes" or "no". Indicates whether X11 will
- be built and installed from X11SRCDIR, and whether the X
- sets will be created.
-
- Note: If "yes", requires MKINET6=yes.
-
- 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.
-
- 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.
-
- See also MKUPDATE.
-
- Default: Unset.
-
- 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(8) 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.
-
- Note: build.sh will provide a default of "releasedir" (in
- the top-level .OBJDIR) unless run in `expert' mode.
-
- Default: Unset.
-
- 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 target architectures may share
- the same TOOLDIR; the target-architecture-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.
- Supported values:
-
- 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.
+ 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.
BUILDING
"make" command line options
@@ -1290,22 +800,15 @@ EXAMPLES
this is run after example 2, it doesn't need to redo that portion of
the release build.
-OBSOLETE VARIABLES
- MKKDEBUG Use MKDEBUGKERNEL.
-
- NBUILDJOBS Use the build.sh and make(1) option -j instead.
-
- USE_NEW_TOOLCHAIN
- The new toolchain is now the default. To disable, use
- TOOLCHAIN_MISSING=yes.
-
SEE ALSO
- 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),
+ config(1), ctags(1), ex(1), gzip(1), lint(1), make(1), mandoc(1),
+ mkisofs(1), nroff(1), vi(1), mk.conf(5), atf(7), hier(7), mdoc(7),
+ release(7), etcupdate(8), installboot(8), mount(8), postinstall(8),
sysinst(8), pkgsrc/sysutils/cdrtools
+ Note: The NetBSD manual pages are also available at
+ https://man.netbsd.org
+
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.
Index: src/doc/BUILDING.mdoc
diff -u src/doc/BUILDING.mdoc:1.143 src/doc/BUILDING.mdoc:1.144
--- src/doc/BUILDING.mdoc:1.143 Sun Jun 11 10:49:44 2023
+++ src/doc/BUILDING.mdoc Sun Jun 11 20:34:14 2023
@@ -1,4 +1,4 @@
-.\" $NetBSD: BUILDING.mdoc,v 1.143 2023/06/11 10:49:44 lukem Exp $
+.\" $NetBSD: BUILDING.mdoc,v 1.144 2023/06/11 20:34:14 lukem Exp $
.\"
.\" Copyright (c) 2001-2023 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -82,6 +82,26 @@ build process.
.Sx Environment variables
section below if you need
to override or manually select your compilers.)
+.Pp
+.Em Note :
+Within this document, cross-references to manual pages are to the
+.Nx
+manual pages, not the host system manual pages.
+The
+.Xr mdoc 7
+source
+to the
+.Nx
+manual pages can be found within the source tree,
+and these and can be formatted with
+.Xr mandoc 1
+or
+.Xr nroff 1
+if those are available on the host system.
+The
+.Nx
+manual pages are also available at
+.Lk https://man.netbsd.org
.
.Sh FILES
.
@@ -144,7 +164,9 @@ files installed in
on the destination system, boot media, and release notes.
.
.It Pa doc/BUILDING.mdoc
-This document, in -mdoc troff format; the original copy.
+The source to this document, in
+.Xr mdoc 7
+format.
Used to generate
.Pa BUILDING .
.
@@ -199,9 +221,15 @@ If any of these directories are missing,
The
.Nx
build tree is described in
-.Xr hier 7 ,
+.Xr hier 7
+.Xr ( mdoc 7
+source in
+.Pa share/man/man7/hier.7 ) ,
and the release layout is described in
-.Xr release 7 .
+.Xr release 7
+.Xr ( mdoc 7
+source in
+.Pa share/man/man7/release.7 ) .
.
.Sh CONFIGURATION
.
@@ -213,7 +241,7 @@ and the release layout is described in
..
.de DFLTn
.DFLT
-.Dq no
+.Dq no .
..
.de DFLTu
.DFLT
@@ -221,7 +249,7 @@ Unset.
..
.de DFLTy
.DFLT
-.Dq yes
+.Dq yes .
..
.de NODEF
.Pp
@@ -259,15 +287,28 @@ builds.
.
.It Sy HOST_CC
Path name to C compiler used to create the toolchain.
+.DFLT
+.Dq cc .
.
.It Sy HOST_CFLAGS
Flags passed to the host C compiler.
+.DFLT
+.Dq \&-O .
+.
+.It Sy HOST_CPPFLAGS
+Flags passed to the host C/C++ pre-processor.
+.DFLTu
.
.It Sy HOST_CXX
Path name to C++ compiler used to create the toolchain.
+.DFLT
+Unset, but defaults to
+.Dq c++
+where required.
.
.It Sy HOST_CXXFLAGS
Flags passed to the host C++ compiler.
+.DFLTu
.
.It Sy HOST_SH
Path name to a shell available on the host system
@@ -298,25 +339,32 @@ to be an absolute path; however,
.Nm build.sh
allows it to be a simple command name, which will be converted
to an absolute path by searching the
-.Sy PATH .
+.Ev PATH .
+.DFLT
+.Dq sh .
.
.It Sy INSTALLBOOT_UBOOT_PATHS
A colon-separated list of search paths used by
.Xr installboot 8
to find U-Boot packages.
+.DFLTu
.
.It Sy MACHINE
Machine type, e.g.,
.Dq macppc .
+.DFLTu
.
.It Sy MACHINE_ARCH
Machine architecture, e.g.,
.Dq powerpc .
+.DFLTu
.
.It Sy MAKE
Path name to invoke
.Xr make 1
as.
+.DFLT
+.Dq make .
.
.It Sy MAKECONF
The name of the
@@ -330,7 +378,7 @@ and
.Em Note :
Only settable in the process environment.
.DFLT
-.Dq /etc/mk.conf
+.Dq Pa /etc/mk.conf .
.
.It Sy MAKEFLAGS
Flags to invoke
@@ -346,6 +394,12 @@ passed in the environment, but allows
to be set via the
.Fl V
option.
+.DFLT
+.Dq \&-X
+on systems with a small
+.Dv ARG_MAX
+(Cygwin, Darwin, FreeBSD);
+otherwise unset.
.
.It Sy MAKEOBJDIR
Directory to use as the
@@ -375,6 +429,7 @@ it cannot usefully be set inside a Makef
.Xr mk.conf 5
or
.Sy MAKECONF .
+.DFLTu
.
.It Sy MAKEOBJDIRPREFIX
Top level directory of the object directory tree.
@@ -409,8 +464,9 @@ it cannot usefully be set inside a Makef
.Xr mk.conf 5
or
.Sy MAKECONF .
+.DFLTu
.
-.It Sy TMPDIR
+.It Ev TMPDIR
Top-level directory to store temporary directories used by
.Sy build.sh
before paths to other directories such as
@@ -425,15 +481,20 @@ I.e., without
.Sy noexec
option.
.DFLT
-.Dq /tmp .
+.Dq Pa /tmp .
.
.El
.
.Ss \*qmake\*q variables
.
-Several variables control the behavior of
+Variables control the behavior of
.Nx
-builds.
+builds are documented in
+.Xr mk.conf 5
+.Xr ( mdoc 7
+source in
+.Pa share/man/man5/mk.conf.5 ) .
+.Pp
Unless otherwise specified, these variables may be set in
either the process environment or the
.Xr make 1
@@ -441,800 +502,6 @@ 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 14n
-.
-.\" These entries are sorted alphabetically.
-.\" Keep in sync with canonical reference share/man/man5/mk.conf.5
-.\" and with share/mk/bsd.README.
-.
-.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.
-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
-.Xr 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
-.Dq Li uname \-v .
-.DFLTu
-.
-.It Sy BUILDINFO
-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
-.Va buildinfo
-variable in any kernels that are built.
-When such kernels are booted, the
-.Xr sysctl 7
-.Va kern.buildinfo
-variable will report this value.
-The string may contain backslash escape sequences, such as
-.Dq "\e\e"
-(representing a backslash character)
-and
-.Dq "\en"
-(representing a newline).
-.DFLTu
-.
-.It Sy BUILDSEED
-.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
-.Xr g++ 1
-documentation of
-.Fl frandom-seed .
-.DFLTu
-.
-.It Sy COPTS
-Extra options for the C compiler.
-Should be appended to (e.g.,
-.Sy COPTS+=-g ) ,
-rather than explicitly set.
-.Pp
-.Em Note :
-.Sy CPUFLAGS ,
-not
-.Sy COPTS ,
-should be used for
-compiler flags that select CPU-related options.
-.Pp
-.Em Note :
-.Sy CFLAGS
-should never be set in
-.Xr mk.conf 5 .
-.
-.It Sy CPUFLAGS
-Additional options passed to the compiler/assembler to select
-CPU instruction set options, CPU tuning options, etc.
-.Pp
-.Em Note :
-Such options should not be specified in
-.Sy COPTS ,
-because some parts of the build process need to override
-CPU-related compiler options.
-.DFLTu
-.
-.It Sy DESTDIR
-Directory to contain the built
-.Nx
-system.
-If set, special options are passed to the compilation tools to
-prevent their default use of the host system's
-.Pa /usr/include , /usr/lib ,
-and so forth.
-This pathname must be an absolute path, and should
-.Em not
-end with a slash
-.Pq /
-character.
-(For installation into the system's root directory, set
-.Sy DESTDIR
-to an empty string, not to
-.Dq / ) .
-The directory must reside on a file system which supports long file
-names and hard links.
-.Pp
-.Em Note :
-.Sy build.sh
-will provide a default of
-.Dq Pa destdir . Ns Sy MACHINE
-(in the top-level
-.Sy .OBJDIR )
-unless run in
-.Sq expert
-mode.
-.DFLT
-Empty string if
-.Sy USETOOLS=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 INSTALLBOOT_BOARDS
-A list of
-.Sy evbarm
-boards to create bootable images for.
-If corresponding U-Boot packages are installed,
-bootable images are created as part of a release.
-See the
-.Bk -words
-.Fl o Sy board= Ns Ar name
-.Ek
-option of
-.Xr installboot 8 .
-.
-.It Sy INSTALLWORLDDIR
-Location for the top-level
-.Dq make installworld
-target to install to.
-If specified, must be an absolute path.
-.DFLT
-.Dq /
-.
-.It Sy MAKEVERBOSE
-Level of verbosity of status messages.
-Supported values:
-.Bl -tag -width 2n
-.It 0
-No descriptive messages or commands executed by
-.Xr make 1
-are shown.
-.It 1
-Brief messages are shown describing what is being done,
-but the actual commands executed by
-.Xr make 1
-are not shown.
-.It 2
-Descriptive messages are shown as above (prefixed with a
-.Sq # ) ,
-and ordinary commands performed by
-.Xr make 1
-are shown.
-.It 3
-In addition to the above, all commands performed by
-.Xr make 1
-are shown, even if they would ordinarily have been hidden
-through use of the
-.Dq \&@
-prefix in the relevant makefile.
-.It 4
-In addition to the above, commands executed by
-.Xr make 1
-are traced through use of the
-.Xr sh 1
-.Dq Fl x
-flag.
-.El
-.DFLT
-2
-.
-.It Sy MKCATPAGES
-.YorN
-Indicates whether preformatted plaintext manual pages will be created
-and installed.
-.NOVAR MKMAN=no No or Sy MKSHARE=no
-.DFLTn
-.
-.It Sy MKCROSSGDB
-.YorN
-Create a cross-gdb as a host tool.
-.DFLTn
-.
-.It Sy MKDEBUG
-.YorN
-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
-.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 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.
-.NODEF NODOC
-.NOVAR MKSHARE=no
-.DFLTy
-.
-.It Sy MKHOSTOBJ
-.YorN
-If
-.Dq 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
-.Dq make obj .
-(This allows multiple host systems to compile
-.Nx
-for a single target architecture.)
-If
-.Dq 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
-architecture.
-.DFLTn
-.
-.It Sy MKHTML
-.YorN
-Indicates whether the HTML manual pages are created and installed.
-.NODEF NOHTML
-.NOVAR MKMAN=no No or Sy MKSHARE=no
-.DFLTy
-.
-.It Sy MKINFO
-.YorN
-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 MKKMOD
-.YorN
-Indicates whether kernel modules will be 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.
-.Pp
-If
-.Dq no ,
-prevents:
-.Bl -dash -compact
-.It
-installation of the
-.Sy *.a
-libraries
-.It
-installation of the
-.Sy *_pic.a
-libraries on PIC systems
-.It
-building of
-.Sy *.a
-libraries on PIC systems
-.It
-installation of
-.Sy .so
-symlinks on ELF systems
-.El
-.Pp
-I.e, only install the shared library (and the
-.Pa .so.major
-symlink on ELF).
-.NODEF NOLINKLIB
-.Pp
-If
-.Dq no ,
-acts as
-.Sy MKLINT=no MKPICINSTALL=no MKPROFILE=no .
-.DFLTy
-.
-.It Sy MKLINT
-.YorN
-Indicates whether
-.Xr lint 1
-will be run against portions of the
-.Nx
-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.
-.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 (NLS) locale zone files will be
-built and installed.
-.NODEF NONLS
-.NOVAR MKSHARE=no
-.DFLTy
-.
-.It Sy MKOBJ
-.YorN
-Indicates whether object directories will be created when running
-.Dq make obj .
-If
-.Dq no ,
-then all built files will be located inside the regular source tree.
-.NODEF NOOBJ
-.Pp
-If
-.Dq no ,
-acts as
-.Sy MKOBJDIRS=no .
-.Pp
-.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
-.Pp
-.Em Note :
-If using
-.Sy build.sh ,
-the default is
-.Dq yes .
-This may be set back to
-.Dq no
-by giving
-.Sy build.sh
-the
-.Fl o
-option.
-.DFLTn
-.
-.It Sy MKPIC
-.YorN
-Indicates whether shared objects and libraries will be created and
-installed.
-If
-.Dq no ,
-the entire built system will be statically linked.
-.NODEF NOPIC
-.Pp
-If
-.Dq no ,
-acts as
-.Sy MKPICLIB=no .
-.DFLTn
-on
-.Sy m68000 ;
-.Dq yes
-on other platforms.
-.
-.It Sy MKPICINSTALL
-.YorN
-Indicates whether the
-.Xr ar 1
-format libraries
-.Sy ( lib*_pic.a ) ,
-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.
-.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
-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
-.Em Note :
-This may be set to
-.Dq yes
-by giving
-.Sy build.sh
-the
-.Fl P
-option.
-.DFLTn
-.
-.It Sy MKREPRO_TIMESTAMP
-Unix timestamp.
-When
-.Sy MKREPRO
-is set, the timestamp of all files in the sets will be set
-to this value.
-.Pp
-.Em Note :
-This may be set automatically to the latest source tree timestamp
-using
-.Xr cvslatest 1
-by giving
-.Sy build.sh
-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.
-.NODEF NOSHARE
-.Pp
-If
-.Dq no ,
-acts as
-.Sy MKCATPAGES=no MKDOC=no MKINFO=no MKHTML=no MKMAN=no MKNLS=no .
-.DFLTy
-.
-.It Sy MKSTRIPIDENT
-.YorN
-Indicates whether RCS IDs, for use with
-.Xr ident 1 ,
-should be stripped from program binaries and shared libraries.
-.DFLTn
-.
-.It Sy MKSTRIPSYM
-.YorN
-Indicates whether all local symbols should be stripped from shared libraries.
-If
-.Dq yes ,
-strip all local symbols from shared libraries;
-the effect is equivalent to the
-.Fl x
-option of
-.Xr ld 1 .
-If
-.Dq no ,
-strip only temporary local symbols; the effect is equivalent
-to the
-.Fl X
-option of
-.Xr 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.
-.DFLTy
-.
-.It Sy MKUNPRIVED
-.YorN
-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
-.Pa METALOG
-in
-.Sy DESTDIR .
-The
-.Pa METALOG
-contents are used during the generation of the distribution
-tar files to ensure that the appropriate file ownership is stored.
-This allows a non-root
-.Sq "make install" .
-.DFLTn
-.
-.It Sy MKUPDATE
-.YorN
-Indicates whether all install operations intended to write to
-.Sy DESTDIR
-will compare file timestamps before installing, and skip the install
-phase if the destination files are up-to-date.
-.Pp
-For top-level builds this this implies the effects of
-.Sy NOCLEANDIR
-(i.e.,
-.Dq make cleandir
-is avoided).
-.Pp
-.Em Note :
-If using
-.Sy build.sh ,
-this may be set by giving the
-.Fl u
-option.
-.DFLTn
-.
-.It Sy MKX11
-.YorN
-Indicates whether X11 will be built and installed from
-.Sy X11SRCDIR ,
-and whether the X sets will be created.
-.Pp
-.Em Note :
-If
-.Dq yes ,
-requires
-.Sy MKINET6=yes .
-.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 NOCLEANDIR
-If set, avoids the
-.Dq 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.
-.Pp
-See also
-.Sy MKUPDATE .
-.DFLTu
-.
-.It Sy NODISTRIBDIRS
-If set, avoids the
-.Dq make distrib-dirs
-phase of a full build.
-This skips running
-.Xr mtree 8
-on
-.Sy DESTDIR ,
-useful on systems where building as an unprivileged user, or where it is
-known that the system-wide
-.Xr mtree 8
-files have not changed.
-.DFLTu
-.
-.It Sy NOINCLUDES
-If set, avoids the
-.Dq make includes
-phase of a full build.
-This has the effect of preventing
-.Xr 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
-.Nx
-source tree arbitrarily; it is suggested to use
-.Sy MKUPDATE=yes
-instead in that case.
-.DFLTu
-.
-.It Sy RELEASEDIR
-If set, specifies the directory to which a
-.Xr release 7
-layout will be written at the end of a
-.Dq make release .
-If specified, must be an absolute path.
-.Pp
-.Em Note :
-.Sy build.sh
-will provide a default of
-.Dq Pa releasedir
-(in the top-level
-.Sy .OBJDIR )
-unless run in
-.Sq expert
-mode.
-.DFLTu
-.
-.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.
-This directory should be unique to a given host system and
-.Nx
-source tree.
-(However, multiple target architectures may share the same
-.Sy TOOLDIR ;
-the target-architecture-dependent files have unique names.)
-If unset, a default based
-on the
-.Xr uname 1
-information of the host platform will be created in the
-.Sy .OBJDIR
-of
-.Pa src .
-.DFLTu
-.
-.It Sy USETOOLS
-.YorN
-Indicates whether the tools specified by
-.Sy TOOLDIR
-should be used as part of a build in progress.
-Must be set to
-.Dq yes
-if cross-compiling.
-Supported values:
-.Bl -tag -width "never"
-.It yes
-Use the tools from
-.Sy TOOLDIR .
-.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 never
-Do not use the tools from
-.Sy TOOLDIR ,
-even when building native tool components.
-This is similar to the traditional
-.Nx
-build method, but does
-.Em 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
-.Nx
-source tree.
-.El
-.DFLTn
-when using
-.Aq bsd.*.mk
-outside the
-.Nx
-source tree (detected automatically) or if
-.Sy TOOLCHAIN_MISSING=yes ;
-.Dq yes
-otherwise.
-.
-.It Sy X11SRCDIR
-Directory containing the modular Xorg source.
-If specified, must be an absolute path.
-The main modular Xorg source is found in
-.Sy X11SRCDIR Ns Pa /external/mit .
-.DFLT
-.Sy NETBSDSRCDIR Ns Pa /../xsrc ,
-if that exists; otherwise
-.Pa /usr/xsrc .
-.
-.El
.
.Sh BUILDING
.
@@ -1703,7 +970,7 @@ is executed (if that can be determined),
or using the first copy of
.Pa sh
found in
-.Sy PATH .
+.Ev PATH .
.Pp
All cross-compile builds, and most native builds, of the entire system
should make use of
@@ -1768,7 +1035,7 @@ Show a help message, and exit.
.
.It Sy makewrapper
Create the
-.Sy \*[toolprefix]make-MACHINE
+.Sy \*[toolprefix]make- Ns Sy MACHINE
wrapper.
This operation is automatically performed for any of the other
operations.
@@ -1830,7 +1097,7 @@ directory, which is typically
The new kernel will be built in a subdirectory of
.Sy KERNOBJDIR ,
which is typically
-.Pa sys/arch/MACHINE/compile
+.Pa sys/arch/ Ns Sy MACHINE Ns Pa /compile
or an associated object directory.
.Pp
This command does
@@ -1877,7 +1144,7 @@ Install a
copy of the kernel previously built by
.Sy kernel Ns = Ns Ar kconf
into
-.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/kernel ,
+.Sy RELEASEDIR Ns Pa / Ns Sy RELEASEMACHINEDIR Ns Pa /binary/kernel ,
usually as
.Pa netbsd- Ns Ar kconf Ns Pa .gz ,
although the
@@ -1974,7 +1241,7 @@ to
This will also append the build identifier to the name of the
.Dq make
wrapper script so that the resulting name is of the form
-.Dq Sy \*[toolprefix]make-MACHINE-BUILDID .
+.Dq Sy \*[toolprefix]make- Ns Sy MACHINE Ns Sy -BUILDID .
.
.It Fl C Ar cdextras
Append
@@ -2304,7 +1571,7 @@ wrapper script (see below) in a custom l
specified by
.Ar wrapper .
This allows, for instance, to place the wrapper in
-.Sy PATH
+.Ev PATH
automatically.
.Pp
.Em Note :
@@ -2368,7 +1635,7 @@ and unset variables specified with
.Fl Z .
.Pp
This script can be symlinked into a directory listed in
-.Sy PATH ,
+.Ev PATH ,
or called with an absolute path.
.
.Sh EXAMPLES
@@ -2424,58 +1691,34 @@ so that if this is run after example 2,
portion of the release build.
.El
.
-.Sh OBSOLETE VARIABLES
-.
-.Bl -tag -width "NBUILDJOBS"
-.
-.It Sy MKKDEBUG
-Use
-.Sy MKDEBUGKERNEL .
-.
-.It Sy NBUILDJOBS
-Use the
-.Nm build.sh
-and
-.Xr make 1
-option
-.Fl j
-instead.
-.
-.It Sy USE_NEW_TOOLCHAIN
-The new toolchain is now the default.
-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 mandoc 1 ,
.Xr mkisofs 1 ,
-.Xr sh 1 ,
-.Xr uname 1 ,
+.Xr nroff 1 ,
.Xr vi 1 ,
-.Xr options 4 ,
.Xr mk.conf 5 ,
.Xr atf 7 ,
.Xr hier 7 ,
+.Xr mdoc 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
+.Pp
+.Em Note :
+The
+.Nx
+manual pages are also available at
+.Lk https://man.netbsd.org
.
.Sh HISTORY
.
