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".
This commit is contained in:
lukem
parent
dac4cd245f
commit
cc95aaefd7
51
BUILDING
51
BUILDING
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
.
|
||||
|
|
|
|||
Loading…
Reference in New Issue