Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src BUILDING: remove duplication from mk.conf(5)
details: https://anonhg.NetBSD.org/src/rev/4025e2e8455d
branches: trunk
changeset: 376344:4025e2e8455d
user: lukem <lukem%NetBSD.org@localhost>
date: Sun Jun 11 20:34:14 2023 +0000
description:
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.
diffstat:
BUILDING | 605 +++-------------------------------
doc/BUILDING.mdoc | 935 +++++------------------------------------------------
2 files changed, 143 insertions(+), 1397 deletions(-)
diffs (truncated from 1844 to 300 lines):
diff -r a6daf7af9051 -r 4025e2e8455d BUILDING
--- a/BUILDING Sun Jun 11 20:33:46 2023 +0000
+++ b/BUILDING Sun Jun 11 20:34:14 2023 +0000
@@ -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
Home |
Main Index |
Thread Index |
Old Index