[src/trunk]: src BUILDING: clarify environ vs mk.conf behaviour

[lukem <lukem%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/d921a02a53aa
branches:  trunk
changeset: 378135:d921a02a53aa
user:      lukem <lukem%NetBSD.org@localhost>
date:      Fri Jul 21 22:07:59 2023 +0000

description:
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".

diffstat:

 BUILDING          |  51 +++++++++++++++++++++++++++++++--------------------
 doc/BUILDING.mdoc |  53 ++++++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 71 insertions(+), 33 deletions(-)

diffs (229 lines):

diff -r 0b76cc6f0765 -r d921a02a53aa BUILDING
--- a/BUILDING  Fri Jul 21 22:05:04 2023 +0000
+++ b/BUILDING  Fri Jul 21 22:07:59 2023 +0000
@@ -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.
+     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.
 
-     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.
+     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
diff -r 0b76cc6f0765 -r d921a02a53aa doc/BUILDING.mdoc
--- a/doc/BUILDING.mdoc Fri Jul 21 22:05:04 2023 +0000
+++ b/doc/BUILDING.mdoc Fri Jul 21 22:07:59 2023 +0000
@@ -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.
 .