 @@ -1,14 +1,14 @@
-.\"	$NetBSD: make.1,v 1.338 2022/09/09 05:27:32 rillig Exp $
+.\"	$NetBSD: make.1,v 1.339 2022/09/09 06:23:36 rillig Exp $
 .\"
 .\" Copyright (c) 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
 .\" 1. Redistributions of source code must retain the above copyright
 .\"    notice, this list of conditions and the following disclaimer.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
 .\" 3. Neither the name of the University nor the names of its contributors
 @@ -846,35 +846,34 @@ A path to the directory where
 was executed.
 Refer to the description of
 .Sq Va PWD
 for more details.
 .It Va .INCLUDEDFROMDIR
 The directory of the file this Makefile was included from.
 .It Va .INCLUDEDFROMFILE
 The filename of the file this Makefile was included from.
 .It Va MAKE
 The name that
 .Nm
 was executed with
 .Pq Va argv[0] .
-For compatibility
+For compatibility,
 .Nm
 also sets
 .Va .MAKE
 with the same value.
 The preferred variable to use is the environment variable
 .Ev MAKE
-because it is more compatible with other versions of
+because it is more compatible with other make variants
 .Nm
 and cannot be confused with the special target with the same name.
 .It Va .MAKE.DEPENDFILE
 Names the makefile (default
 .Sq Pa .depend )
 from which generated dependencies are read.
 .It Va .MAKE.EXPAND_VARIABLES
 A boolean that controls the default behavior of the
 .Fl V
 option.
 If true, variable values printed with
 .Fl V
 are fully expanded; if false, the raw variable contents (which may
 include additional unexpanded variable references) are shown.
 @@ -910,82 +909,80 @@ If set to
 apparent variable assignments in dependency lines are
 treated as normal sources.
 .It Va MAKEFLAGS
 The environment variable
 .Sq Ev MAKEFLAGS
 may contain anything that
 may be specified on
 .Nm Ns 's
 command line.
 Anything specified on
 .Nm Ns 's
 command line is appended to the
 .Va MAKEFLAGS
-variable which is then
+variable, which is then added to the environment for all programs that
 entered into the environment for all programs which
 .Nm
 executes.
 .It Va .MAKE.LEVEL
 The recursion depth of
 .Nm .
-The initial instance of
+The top-level instance of
 .Nm
-is 0, and an incremented value is put into the environment
+has level 0, and each child make has its parent level plus 1.
 to be seen by the next generation.
 This allows tests like:
 .Li .if ${.MAKE.LEVEL} == 0
-to protect things which should only be evaluated in the initial instance of
+to protect things which should only be evaluated in the top-level instance of
 .Nm .
 .It Va .MAKE.MAKEFILE_PREFERENCE
 The ordered list of makefile names
 (default
 .Sq Pa makefile ,
 .Sq Pa Makefile )
 that
 .Nm
 looks for.
 .It Va .MAKE.MAKEFILES
 The list of makefiles read by
 .Nm ,
 which is useful for tracking dependencies.
 Each makefile is recorded only once, regardless of the number of times read.
 .It Va .MAKE.MODE
 Processed after reading all makefiles.
-Can affect the mode that
+Affects the mode that
 .Nm
 runs in.
 It can contain a number of keywords:
 .Bl -hang -width missing-filemon=bf.
 .It Cm compat
 Like
 .Fl B ,
 puts
 .Nm
 into
 .Dq compat
 mode.
 .It Cm meta
 Puts
 .Nm
 into
 .Dq meta
 mode, where meta files are created for each target
-to capture the command run, the output generated and if
+to capture the command run, the output generated, and if
 .Xr filemon 4
 is available, the system calls which are of interest to
 .Nm .
-The captured output can be very useful when diagnosing errors.
+The captured output can be useful when diagnosing errors.
 .It Cm curdirOk= Ns Ar bf
-Normally
+By default,
 .Nm
 does not create
 .Pa .meta
 files in
 .Sq Va .CURDIR .
 This can be overridden by setting
 .Va bf
 to a value which represents true.
 .It Cm missing-meta= Ns Ar bf
 If
 .Va bf
 is true, a missing
 .Pa .meta
 @@ -1140,27 +1137,27 @@ and
 to the path of the meta file (if any) describing the failed target.
 It then prints its name and the value of
 .Sq Va .CURDIR
 as well as the value of any variables named in
 .Sq Va MAKE_PRINT_VAR_ON_ERROR .
 .It Va .newline
 This variable is simply assigned a newline character as its value.
 This allows expansions using the
 .Cm \&:@
 modifier to put a newline between
 iterations of the loop rather than a space.
 For example, the printing of
 .Sq Va MAKE_PRINT_VAR_ON_ERROR
-could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v:Q}'${.newline}@}.
+could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}.
 .It Va .OBJDIR
 A path to the directory where the targets are built.
 Its value is determined by trying to
 .Xr chdir 2
 to the following directories in order and using the first match:
 .Bl -enum
 .It
 .Ev ${MAKEOBJDIRPREFIX}${.CURDIR}
 .Pp
 (Only if
 .Sq Ev MAKEOBJDIRPREFIX
 is set in the environment or on the command line.)
 .It
 @@ -1196,42 +1193,42 @@ changes to the specified directory if it
 and
 .Sq Va PWD
 to that directory before executing any targets.
 .Pp
 Except in the case of an explicit
 .Sq Ic .OBJDIR
 target,
 .Nm
 checks that the specified directory is writable and ignores it if not.
 This check can be skipped by setting the environment variable
 .Sq Ev MAKE_OBJDIR_CHECK_WRITABLE
 to "no".
 .It Va .PARSEDIR
-A path to the directory of the current makefile being parsed.
+The directory name of the current makefile being parsed.
 .It Va .PARSEFILE
 The basename of the current makefile being parsed.
 This variable and
 .Sq Va .PARSEDIR
 are both set only while the makefiles are being parsed.
-If you want to retain their current values, assign them to a variable
+To retain their current values,
-using assignment with expansion
+assign them to a variable using assignment with expansion
 .Sq Cm \&:= .
 .It Va .PATH
 The space-separated list of directories that
 .Nm
 searches for files.
-The search list should be updated using the target
+To update this search list, use the special target
 .Sq Ic .PATH
-rather than the variable.
+rather than modifying the variable directly.
 .It Va PWD
 Alternate path to the current directory.
 .Nm
 normally sets
 .Sq Va .CURDIR
 to the canonical path given by
 .Xr getcwd 3 .
 However, if the environment variable
 .Sq Ev PWD
 is set and gives a path to the current directory,
 .Nm
 sets
 .Sq Va .CURDIR
 @@ -1248,29 +1245,29 @@ is set to the value of
 .Sq Va .OBJDIR
 for all programs which
 .Nm
 executes.
 .It Va .SHELL
 The pathname of the shell used to run target scripts.
 It is read-only.
 .It Va .SUFFIXES
 The list of known suffixes.
 It is read-only.
 .It Va .TARGETS
 The list of targets explicitly specified on the command line, if any.
 .It Va VPATH
-Colon-separated
+The colon-separated
 .Pq Dq \&:
-lists of directories that
+list of directories that
 .Nm
 searches for files.
 The variable is supported for compatibility with old make programs only,
 use
 .Sq Va .PATH
 instead.
 .El
 .Ss Variable modifiers
 The general format of a variable expansion is:
 .Pp
 .Sm off
 .D1 Ic \&${ Ar variable\| Oo Ic \&: Ar modifier\| Oo Ic \&: Ar ... Oc Oc Ic \&}
 .Sm on
 @@ -1287,27 +1284,26 @@ A list of indirect modifiers can be spec
 .Ic \&${ Ar variable Ic \&:${ Ar modifier_variable Ic \&} Oo Ic \&: Ar ... Oc Ic \&}
 .Sm on
 .Ed
 .Pp
 In this case, the first modifier in the
 .Ar modifier_variable
 does not start with a colon,
 since that colon already occurs in the referencing variable.
 If any of the modifiers in the
 .Ar modifier_variable
 contains a dollar sign
 .Pq Ql $ ,
 these must be doubled to avoid early expansion.
 .\" XXX: This is only close to the truth, see the table in varmod.mk.
 .Pp
 Some modifiers interpret the expression value as a single string,
 others treat the expression value as a whitespace-separated list of words.
 When splitting a string into words,
 whitespace can be escaped using double quotes, single quotes and backslashes,
 like in the shell.
 The quotes and backslashes are retained in the words.
 .Pp
 The supported modifiers are:
 .Bl -tag -width EEE
 .It Cm \&:E
 Replaces each word in the variable with its suffix.
 .It Cm \&:H
 @@ -1410,34 +1406,34 @@ value is not provided or is 0, the curre
 .It Cm \&:hash
 Computes a 32-bit hash of the value and encodes it as 8 hex digits.
 .It Cm \&:localtime Ns Oo Cm = Ns Ar timestamp Oc
 The value is interpreted as a format string for
 .Xr strftime 3 ,
 using
 .Xr localtime 3 ,
 producing the formatted timestamp.
 If a
 .Ar timestamp
 value is not provided or is 0, the current time is used.
 .It Cm \&:tA
 Attempts to convert the value to an absolute path using
-.Xr realpath 3 ,
+.Xr realpath 3 .
-if that fails, the value is unchanged.
+If that fails, the value is unchanged.
 .It Cm \&:tl
 Converts the value to lower-case letters.
 .It Cm \&:ts Ns Ar c
 When joining the words after a modifier that treats the value as words,
 the words are normally separated by a space.
-This modifier sets the separator to the character
+This modifier changes the separator to the character
 .Ar c .
 If
 .Ar c
 is omitted, no separator is used.
 The common escapes (including octal numeric codes) work as expected.
 .It Cm \&:tu
 Converts the value to upper-case letters.
 .It Cm \&:tW
 Causes subsequent modifiers to treat the value as a single word
 (possibly containing embedded whitespace).
 See also
 .Sq Cm \&:[*] .
 .It Cm \&:tw
 @@ -1620,28 +1616,28 @@ This is the loop expansion mechanism fro
 Environment (ODE) make.
 Unlike
 .Cm \&.for
 loops, expansion occurs at the time of reference.
 For each word in the value, assign the word to the variable named
 .Ar varname
 and evaluate
 .Ar string .
 The ODE convention is that
 .Ar varname
 should start and end with a period, for example:
 .Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@}
 .Pp
-However, a single-character variable is often more readable:
+However, a single-letter variable is often more readable:
-.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v:Q}'${.newline}@}
+.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
 .It Cm \&:_ Ns Oo Cm = Ns Ar var Oc
 Saves the current variable value in
 .Ql $_
 or the named
 .Ar var
 for later reference.
 Example usage:
 .Bd -literal -offset indent
 M_cmpv.units = 1 1000 1000000
 M_cmpv = S,., ,g:_:range:@i@+ $${_:[-$$i]} \&\\
 \\* $${M_cmpv.units:[$$i]}@:S,^,expr 0 ,1:sh
 .Dv .if ${VERSION:${M_cmpv}} < ${3.1.12:L:${M_cmpv}}
 @@ -1663,48 +1659,43 @@ It is handy for setting per-target CFLAG
 .Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}}
 If a value is only required if the variable is undefined, use:
 .Dl ${VAR:D:Unewval}
 .It Cm \&:D\| Ns Ar newval
 If the variable is defined,
 .Ar newval
 is the value.
 .It Cm \&:L
 The name of the variable is the value.
 .It Cm \&:P
 The path of the node which has the same name as the variable is the value.
 If no such node exists or its path is null, the name of the variable is used.
 In order for this modifier to work, the name (node) must at least have
-appeared on the rhs of a dependency.
+appeared on the right-hand side of a dependency.
 .Sm off
 .It Cm \&:\&! Ar cmd\| Cm \&!
 .Sm on
 The output of running
 .Ar cmd
 is the value.
 .It Cm \&:sh
-If the variable is non-empty, it is run as a command and the output
+The value is run as a command, and the output becomes the new value.
 becomes the new value.
 .It Cm \&::= Ns Ar str
 The variable is assigned the value
 .Ar str
 after substitution.
 This modifier and its variations are useful in obscure situations
-such as wanting to set a variable when shell commands are being parsed.
+such as wanting to set a variable
-These assignment modifiers always expand to nothing,
+at a point where a target's shell commands are being parsed.
-so if they appear in a rule line by themselves,
+These assignment modifiers always expand to nothing.
 they should be preceded with something,
 to keep
 .Nm
 happy.
 .Pp
 The
 .Sq Cm \&::
 helps avoid false matches with the
 .At V
 style
 .Cm \&:=
 modifier and since substitution always occurs, the
 .Cm \&::=
 form is vaguely appropriate.
 .It Cm \&::?= Ns Ar str
 As for
 .Cm \&::=
 @@ -1948,27 +1939,26 @@ End the body of the conditional.
 .El
 .Pp
 The
 .Ar operator
 may be any one of the following:
 .Bl -tag -width "Cm XX"
 .It Cm \&|\&|
 Logical OR.
 .It Cm \&&&
 Logical AND; of higher precedence than
 .Dq \&|\&| .
 .El
 .Pp
 As in C,
 .Nm
 only evaluates a conditional as far as is necessary to determine its value.
 Parentheses can be used to override the operator precedence.
 The boolean operator
 .Sq Ic \&!
 may be used to logically negate an entire
 conditional.
 It is of higher precedence than
 .Sq Ic \&&& .
 .Pp
 The value of
 .Ar expression
 may be any of the following:
 @@ -2017,51 +2007,51 @@ Numeric comparisons may also use the ope
 .Sq Ic \&< ,
 .Sq Ic \&<= ,
 .Sq Ic \&>
 and
 .Sq Ic \&>= .
 .Pp
 If the comparison has neither a comparison operator nor a right side,
 the expression evaluates to true if it is nonempty
 and its numeric value (if any) is not zero.
 .Pp
 When
 .Nm
 is evaluating one of these conditional expressions, and it encounters
-a (white-space separated) word it doesn't recognize, either the
+a (whitespace separated) word it doesn't recognize, either the
 .Dq make
 or
 .Dq defined
-expression is applied to it, depending on the form of the conditional.
+function is applied to it, depending on the form of the conditional.
 If the form is
 .Sq Ic .ifdef ,
-.Sq Ic .ifndef ,
+.Sq Ic .ifndef
 or
-.Sq Ic .if
+.Sq Ic .if ,
 the
 .Dq defined
-expression is applied.
+function is applied.
 Similarly, if the form is
 .Sq Ic .ifmake
 or
 .Sq Ic .ifnmake ,
 the
 .Dq make
-expression is applied.
+function is applied.
 .Pp
-If the conditional evaluates to true the parsing of the makefile continues
+If the conditional evaluates to true,
-as before.
+parsing of the makefile continues as before.
 If it evaluates to false, the following lines are skipped.
-In both cases this continues until a
+In both cases, this continues until the corresponding
 .Sq Ic .else
 or
 .Sq Ic .endif
 is found.
 .Pp
 For loops are typically used to apply a set of rules to a list of files.
 The syntax of a for loop is:
 .Pp
 .Bl -tag -compact -width Ds
 .It Ic \&.for Ar variable Oo Ar variable ... Oc Ic in Ar expression
 .It Aq make-lines
 .It Ic \&.endfor
 .El