Module Name: src
Committed By: lukem
Date: Fri Jul 21 22:07:59 UTC 2023
Modified Files:
src: BUILDING
src/doc: BUILDING.mdoc
Log Message:
BUILDING: clarify environ vs mk.conf behaviour
Document that variables set in the environment or the
nbmake-MACHINE wrapper script don't override variable
assignments in mk.conf(5), and that using ?= in mk.conf
allows environment / nbmake-MACHINE variables to override
mk.conf.
Consistently refer to "nbmake-MACHINE wrapper script".
To generate a diff of this commit:
cvs rdiff -u -r1.158 -r1.159 src/BUILDING
cvs rdiff -u -r1.147 -r1.148 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.158 src/BUILDING:1.159
--- src/BUILDING:1.158 Wed Jul 19 15:40:38 2023
+++ src/BUILDING Fri Jul 21 22:07:59 2023
@@ -237,6 +237,15 @@ CONFIGURATION
process environment or the make(1) configuration file mk.conf(5)
specified by MAKECONF.
+ Note: Variables set in the environment, either directly or via build.sh
+ options to set specific values in the nbmake-MACHINE wrapper script do
+ not override variables set in the mk.conf(5) file. To allow variables in
+ mk.conf(5) to be overridden by the environment or build.sh options,
+ define the variables using the "?=" make(1) variable assignment operator.
+ For example,
+
+ MAKEVERBOSE?=1
+
BUILDING
"make" command line options
This is not a summary of all the options available to make(1); only the
@@ -510,8 +519,8 @@ BUILDING
help Show a help message, and exit.
- makewrapper Create the nbmake-MACHINE wrapper. This operation is
- automatically performed for any of the other operations.
+ makewrapper Create the nbmake-MACHINE wrapper script. This operation
+ is automatically performed for any of the other operations.
cleandir Perform "make cleandir".
@@ -601,8 +610,8 @@ BUILDING
-B buildid
Set the value of BUILDID to buildid. This will also append the
- build identifier to the name of the "make" wrapper script so
- that the resulting name is of the form
+ build identifier to the name of the nbmake-MACHINE wrapper
+ script so that the resulting name is of the form
"nbmake-MACHINE-BUILDID".
-C cdextras
@@ -749,12 +758,12 @@ BUILDING
-V var=[value]
Set the environment variable var to an optional value. This is
- propagated to the nbmake wrapper.
+ propagated to the nbmake-MACHINE wrapper script.
-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.
+ Create the nbmake-MACHINE wrapper script (see below) in a
+ custom location, specified by wrapper. This allows, for
+ instance, to place the wrapper script 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
@@ -768,23 +777,25 @@ BUILDING
-x Set MKX11=yes.
-Z var Unset ("zap") the environment variable var. This is propagated
- to the nbmake wrapper.
+ to the nbmake-MACHINE wrapper script.
-? Show a help message, and exit.
The "nbmake-MACHINE" wrapper script
- If using the build.sh script to build NetBSD, a nbmake-MACHINE script
- will be created in TOOLDIR/bin upon the first build to assist in building
- subtrees on a cross-compile host.
-
- nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
- the up-to-date version of "nbmake" installed into TOOLDIR/bin with
- several key variables pre-set, including MACHINE, MACHINE_ARCH, and
- TOOLDIR. nbmake-MACHINE will also set variables specified with -V, and
- unset variables specified with -Z.
+ If using the build.sh script to build NetBSD, a nbmake-MACHINE wrapper
+ script will be created in TOOLDIR/bin upon the first build to assist in
+ building subtrees on a cross-compile host.
+
+ The nbmake-MACHINE wrapper script can be invoked in lieu of make(1), and
+ will instead call the up-to-date version of "nbmake" installed into
+ TOOLDIR/bin with several key variables pre-set, including MACHINE,
+ MACHINE_ARCH, and TOOLDIR. nbmake-MACHINE will also set variables
+ specified with -V, and unset variables specified with -Z. Note that by
+ default these variables will not override mk.conf(5); see "make"
+ variables for more details.
- This script can be symlinked into a directory listed in PATH, or called
- with an absolute path.
+ This wrapper script can be symlinked into a directory listed in PATH, or
+ called with an absolute path.
EXAMPLES
1. % ./build.sh [OPTIONS] tools kernel=GENERIC
@@ -831,4 +842,4 @@ CAVEATS
in object directories. Instead, one may have to manually remove the
files. Consult the UPDATING file for notices concerning this.
-NetBSD July 18, 2023 NetBSD
+NetBSD July 21, 2023 NetBSD
Index: src/doc/BUILDING.mdoc
diff -u src/doc/BUILDING.mdoc:1.147 src/doc/BUILDING.mdoc:1.148
--- src/doc/BUILDING.mdoc:1.147 Wed Jul 19 15:40:38 2023
+++ src/doc/BUILDING.mdoc Fri Jul 21 22:07:59 2023
@@ -1,4 +1,4 @@
-.\" $NetBSD: BUILDING.mdoc,v 1.147 2023/07/19 15:40:38 lukem Exp $
+.\" $NetBSD: BUILDING.mdoc,v 1.148 2023/07/21 22:07:59 lukem Exp $
.\"
.\" Copyright (c) 2001-2023 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -33,7 +33,7 @@
.\" Toolchain prefix for commands
.ds toolprefix nb
.
-.Dd July 18, 2023
+.Dd July 21, 2023
.Dt BUILDING 8
.Os NetBSD
.\" turn off hyphenation
@@ -535,6 +535,27 @@ configuration file
.Xr mk.conf 5
specified by
.Sy MAKECONF .
+.Pp
+.Em Note :
+Variables set in the environment, either directly or via
+.Sy build.sh
+options to set specific values in the
+.Sy \*[toolprefix]make- Ns Sy MACHINE
+wrapper script do not override variables set in the
+.Xr mk.conf 5
+file.
+To allow variables in
+.Xr mk.conf 5
+to be overridden by the environment or
+.Sy build.sh
+options, define the variables using the
+.Dq Li ?=
+.Xr make 1
+variable assignment operator.
+For example,
+.Bd -unfilled -offset indent
+.Li MAKEVERBOSE?=1
+.Ed
.
.Sh BUILDING
.
@@ -1069,7 +1090,7 @@ Show a help message, and exit.
.It Sy makewrapper
Create the
.Sy \*[toolprefix]make- Ns Sy MACHINE
-wrapper.
+wrapper script.
This operation is automatically performed for any of the other
operations.
.
@@ -1272,7 +1293,7 @@ Set the value of
to
.Ar buildid .
This will also append the build identifier to the name of the
-.Dq make
+.Sy \*[toolprefix]make- Ns Sy MACHINE
wrapper script so that the resulting name is of the form
.Dq Sy \*[toolprefix]make- Ns Sy MACHINE Ns Sy -BUILDID .
.
@@ -1594,16 +1615,16 @@ Set the environment variable
to an optional
.Ar value .
This is propagated to the
-.Sy \*[toolprefix]make
-wrapper.
+.Sy \*[toolprefix]make- Ns Sy MACHINE
+wrapper script.
.
.It Fl w Ar wrapper
Create the
-.Sy \*[toolprefix]make
+.Sy \*[toolprefix]make- Ns Sy MACHINE
wrapper script (see below) in a custom location,
specified by
.Ar wrapper .
-This allows, for instance, to place the wrapper in
+This allows, for instance, to place the wrapper script in
.Ev PATH
automatically.
.Pp
@@ -1629,8 +1650,8 @@ Set
Unset ("zap") the environment variable
.Ar var .
This is propagated to the
-.Sy \*[toolprefix]make
-wrapper.
+.Sy \*[toolprefix]make- Ns Sy MACHINE
+wrapper script.
.
.It Fl ?
Show a help message, and exit.
@@ -1645,13 +1666,14 @@ script to build
.Nx ,
a
.Sy \*[toolprefix]make-MACHINE
-script will be created in
+wrapper script will be created in
.Sy TOOLDIR Ns Pa /bin
upon the first build to assist in building subtrees on a cross-compile
host.
.Pp
+The
.Sy \*[toolprefix]make-MACHINE
-can be invoked in lieu of
+wrapper script can be invoked in lieu of
.Xr make 1 ,
and will instead call the up-to-date version of
.Dq \*[toolprefix]make
@@ -1666,8 +1688,13 @@ will also set variables specified with
.Fl V ,
and unset variables specified with
.Fl Z .
+Note that by default these variables will not override
+.Xr mk.conf 5 ;
+see
+.Sx \*qmake\*q variables
+for more details.
.Pp
-This script can be symlinked into a directory listed in
+This wrapper script can be symlinked into a directory listed in
.Ev PATH ,
or called with an absolute path.
.
