2 files changed, 103 insertions, 23 deletions

diff --git a/usr.bin/make/main.c b/usr.bin/make/main.c
index 18d2372aac3d..521d646d7e02 100644
--- a/usr.bin/make/main.c
+++ b/usr.bin/make/main.c
@@ -1187,9 +1187,11 @@ main(int argc, char **argv)
 
 	ReadMakefile(".depend");
 
-	/* Install all the flags into the MAKE envariable. */
+	/* Install all the flags into the MAKEFLAGS envariable. */
 	if (((p = Var_Value(".MAKEFLAGS", VAR_GLOBAL)) != NULL) && *p)
 		setenv("MAKEFLAGS", p, 1);
+	else
+		setenv("MAKEFLAGS", "", 1);
 
 	/*
 	 * For compatibility, look at the directories in the VPATH variable
diff --git a/usr.bin/make/make.1 b/usr.bin/make/make.1
index 1d84d2ac5e1e..210a42f3cc70 100644
--- a/usr.bin/make/make.1
+++ b/usr.bin/make/make.1
@@ -198,6 +198,13 @@ Multiple
 .Fl f
 options can be supplied,
 and the makefiles will be read in that order.
+Unlike the other command-line options,
+.Fl f
+is neither stored in
+.Va .MAKEFLAGS
+nor pushed down to sub-makes via
+.Ev MAKEFLAGS .
+See below for more details on these variables.
 .It Fl I Ar directory
 Specify a directory in which to search for makefiles and included makefiles.
 Multiple
@@ -466,7 +473,21 @@ environment variable or the
 target.
 .It Local variables
 Variables that are defined specific to a certain target.
-The seven local variables are as follows:
+.El
+.Pp
+If the name of an environment variable appears in a makefile
+on the left-hand side of an assignment,
+a global variable with the same name is created, and the latter
+shadows the former as per their relative precedences.
+The environment is not changed in this case, and the change
+is not exported to programs executed by
+.Nm .
+However, a command-line variable actually replaces
+the environment variable of the same name if the latter exists,
+which is visible to child programs.
+.Pp
+There are seven local variables in
+.Nm :
 .Bl -tag -width ".ARCHIVE"
 .It Va .ALLSRC
 The list of all sources for this target; also known as
@@ -528,7 +549,6 @@ These variables are
 .Va .ARCHIVE ,
 and
 .Va .MEMBER .
-.El
 .Pp
 In addition,
 .Nm
@@ -625,36 +645,51 @@ They are added right before
 .Nm
 begins to parse them, so that the name of the current makefile is the
 last word in this variable.
-.It Va .MAKEFLAGS
+.It Ev MAKEFLAGS
 The environment variable
 .Ev MAKEFLAGS
-may contain anything that
+may initially contain anything that
 may be specified on
 .Nm Ns 's
-command line.
-Its contents are stored in
-.Nm Ns 's
+command line,
+including
+.Fl f
+option(s).
+After processing, its contents are stored in the
 .Va .MAKEFLAGS
-variable.
-All options and variable assignments specified on
+global variable, although any
+.Fl f
+options are omitted.
+Then all options and variable assignments specified on
 .Nm Ns 's
-command line are appended to the
+command line, except for
+.Fl f ,
+are appended to the
 .Va .MAKEFLAGS
-variable which is then
-entered into the environment as
-.Ev MAKEFLAGS
-for all programs which
+variable.
+.Pp
+Whenever
 .Nm
-executes.
-By modifying the contents of the
+executes a program, it sets
+.Ev MAKEFLAGS
+in the program's environment to the current value of the
 .Va .MAKEFLAGS
-variable, makefile can alter the contents of the
-.Va MAKEFLAGS
-environment variable made available for all programs which
+global variable.
+Thus, if
+.Ev MAKEFLAGS
+in
+.Nm Ns 's
+environment contains any
+.Fl f
+options, they will not be pushed down to child programs automatically.
+The
 .Nm
-executes; compare with the
-.Ic .MAKEFLAGS
-special target below.
+utility effectively filters out
+.Fl f
+options from the environment and command line although it
+passes the rest of its options down to sub-makes via
+.Ev MAKEFLAGS
+by default.
 .Pp
 When passing macro definitions and flag arguments in the
 .Ev MAKEFLAGS
@@ -669,6 +704,49 @@ without causing a word break.
 Any other occurrences of a backslash are retained.
 Groups of unquoted space, tab and newline characters cause word
 breaking.
+.It Va .MAKEFLAGS
+Initially, this global variable contains
+.Nm Ns 's
+current run-time options from the environment
+and command line as described above, under
+.Ev MAKEFLAGS .
+By modifying the contents of the
+.Va .MAKEFLAGS
+global variable, the makefile can alter the contents of the
+.Ev MAKEFLAGS
+environment variable made available for all programs which
+.Nm
+executes.
+This includes adding
+.Fl f
+option(s).
+The current value of
+.Va .MAKEFLAGS
+is just copied verbatim to
+.Ev MAKEFLAGS
+in the environment of child programs.
+.Pp
+Note that any options entered to
+.Va .MAKEFLAGS
+neither affect the current instance of
+.Nm
+nor show up in its own copy of
+.Ev MAKEFLAGS
+instantly.
+However, they do show up in the
+.Ev MAKEFLAGS
+environment variable of programs executed by
+.Nm .
+On the other hand, a direct assignment to
+.Ev MAKEFLAGS
+neither affects the current instance of
+.Nm
+nor is passed down to
+.Nm Ns 's
+children.
+Compare with the
+.Ic .MAKEFLAGS
+special target below.
 .It Va MFLAGS
 This variable is provided for backward compatibility and
 contains all the options from the