1 files changed, 88 insertions, 0 deletions
diff --git a/devdocs/gnu_make/special-variables.html b/devdocs/gnu_make/special-variables.html
new file mode 100644
index 00000000..11a4dc89
--- /dev/null
+++ b/devdocs/gnu_make/special-variables.html
@@ -0,0 +1,88 @@
+  <h1 class="section">Other Special Variables</h1>   <p>GNU <code>make</code> supports some variables that have special properties. </p> <dl compact>  <dt id="MAKEFILE_LIST"><code>MAKEFILE_LIST</code></dt> <dd>
+<p>Contains the name of each makefile that is parsed by <code>make</code>, in the order in which it was parsed. The name is appended just before <code>make</code> begins to parse the makefile. Thus, if the first thing a makefile does is examine the last word in this variable, it will be the name of the current makefile. Once the current makefile has used <code>include</code>, however, the last word will be the just-included makefile. </p> <p>If a makefile named <code>Makefile</code> has this content: </p> <div class="example"> <pre class="example">name1 := $(lastword $(MAKEFILE_LIST))
+
+include inc.mk
+
+name2 := $(lastword $(MAKEFILE_LIST))
+
+all:
+        @echo name1 = $(name1)
+        @echo name2 = $(name2)
+</pre>
+</div> <p>then you would expect to see this output: </p> <div class="example"> <pre class="example">name1 = Makefile
+name2 = inc.mk
+</pre>
+</div>  </dd> <dt id=".DEFAULT_GOAL"><code>.DEFAULT_GOAL</code></dt> <dd>
+<p>Sets the default goal to be used if no targets were specified on the command line (see <a href="goals">Arguments to Specify the Goals</a>). The <code>.DEFAULT_GOAL</code> variable allows you to discover the current default goal, restart the default goal selection algorithm by clearing its value, or to explicitly set the default goal. The following example illustrates these cases: </p> <div class="example"> <pre class="example"># Query the default goal.
+ifeq ($(.DEFAULT_GOAL),)
+  $(warning no default goal is set)
+endif
+
+.PHONY: foo
+foo: ; @echo $@
+
+$(warning default goal is $(.DEFAULT_GOAL))
+
+# Reset the default goal.
+.DEFAULT_GOAL :=
+
+.PHONY: bar
+bar: ; @echo $@
+
+$(warning default goal is $(.DEFAULT_GOAL))
+
+# Set our own.
+.DEFAULT_GOAL := foo
+</pre>
+</div> <p>This makefile prints: </p> <div class="example"> <pre class="example">no default goal is set
+default goal is foo
+default goal is bar
+foo
+</pre>
+</div> <p>Note that assigning more than one target name to <code>.DEFAULT_GOAL</code> is invalid and will result in an error. </p>  </dd> <dt id="MAKE_RESTARTS"><code>MAKE_RESTARTS</code></dt> <dd>
+<p>This variable is set only if this instance of <code>make</code> has restarted (see <a href="remaking-makefiles">How Makefiles Are Remade</a>): it will contain the number of times this instance has restarted. Note this is not the same as recursion (counted by the <code>MAKELEVEL</code> variable). You should not set, modify, or export this variable. </p>   </dd> <dt id="MAKE_TERMOUT"><code>MAKE_TERMOUT</code></dt> <dt id="MAKE_TERMERR"><code>MAKE_TERMERR</code></dt> <dd>
+<p>When <code>make</code> starts it will check whether stdout and stderr will show their output on a terminal. If so, it will set <code>MAKE_TERMOUT</code> and <code>MAKE_TERMERR</code>, respectively, to the name of the terminal device (or <code>true</code> if this cannot be determined). If set these variables will be marked for export. These variables will not be changed by <code>make</code> and they will not be modified if already set. </p> <p>These values can be used (particularly in combination with output synchronization (see <a href="parallel-output">Output During Parallel Execution</a>) to determine whether <code>make</code> itself is writing to a terminal; they can be tested to decide whether to force recipe commands to generate colorized output for example. </p> <p>If you invoke a sub-<code>make</code> and redirect its stdout or stderr it is your responsibility to reset or unexport these variables as well, if your makefiles rely on them. </p>  </dd> <dt id=".RECIPEPREFIX"><code>.RECIPEPREFIX</code></dt> <dd>
+<p>The first character of the value of this variable is used as the character make assumes is introducing a recipe line. If the variable is empty (as it is by default) that character is the standard tab character. For example, this is a valid makefile: </p> <div class="example"> <pre class="example">.RECIPEPREFIX = &gt;
+all:
+&gt; @echo Hello, world
+</pre>
+</div> <p>The value of <code>.RECIPEPREFIX</code> can be changed multiple times; once set it stays in effect for all rules parsed until it is modified. </p>  </dd> <dt id=".VARIABLES"><code>.VARIABLES</code></dt> <dd>
+<p>Expands to a list of the <em>names</em> of all global variables defined so far. This includes variables which have empty values, as well as built-in variables (see <a href="implicit-variables">Variables Used by Implicit Rules</a>), but does not include any variables which are only defined in a target-specific context. Note that any value you assign to this variable will be ignored; it will always return its special value. </p>  </dd> <dt id=".FEATURES"><code>.FEATURES</code></dt> <dd>
+<p>Expands to a list of special features supported by this version of <code>make</code>. Possible values include, but are not limited to: </p> <dl compact> <dt id="archives">‘<samp>archives</samp>’</dt> <dd>
+<p>Supports <code>ar</code> (archive) files using special file name syntax. See <a href="archives">Using <code>make</code> to Update Archive Files</a>. </p> </dd> <dt id="check-symlink">‘<samp>check-symlink</samp>’</dt> <dd>
+<p>Supports the <code>-L</code> (<code>--check-symlink-times</code>) flag. See <a href="options-summary">Summary of Options</a>. </p> </dd> <dt id="else-if">‘<samp>else-if</samp>’</dt> <dd>
+<p>Supports “else if” non-nested conditionals. See <a href="conditional-syntax">Syntax of Conditionals</a>. </p> </dd> <dt id="extra-prereqs">‘<samp>extra-prereqs</samp>’</dt> <dd>
+<p>Supports the <code>.EXTRA_PREREQS</code> special target. </p> </dd> <dt id="grouped-target">‘<samp>grouped-target</samp>’</dt> <dd>
+<p>Supports grouped target syntax for explicit rules. See <a href="multiple-targets">Multiple Targets in a Rule</a>. </p> </dd> <dt id="guile">‘<samp>guile</samp>’</dt> <dd>
+<p>Has GNU Guile available as an embedded extension language. See <a href="guile-integration">GNU Guile Integration</a>. </p> </dd> <dt id="jobserver">‘<samp>jobserver</samp>’</dt> <dd>
+<p>Supports “job server” enhanced parallel builds. See <a href="parallel">Parallel Execution</a>. </p> </dd> <dt id="jobserver-fifo">‘<samp>jobserver-fifo</samp>’</dt> <dd>
+<p>Supports “job server” enhanced parallel builds using named pipes. See <a href="integrating-make">Integrating GNU <code>make</code></a>. </p> </dd> <dt id="load">‘<samp>load</samp>’</dt> <dd>
+<p>Supports dynamically loadable objects for creating custom extensions. See <a href="loading-objects">Loading Dynamic Objects</a>. </p> </dd> <dt id="notintermediate">‘<samp>notintermediate</samp>’</dt> <dd>
+<p>Supports the <code>.NOTINTERMEDIATE</code> special target. See <a href="integrating-make">Integrating GNU <code>make</code></a>. </p> </dd> <dt id="oneshell">‘<samp>oneshell</samp>’</dt> <dd>
+<p>Supports the <code>.ONESHELL</code> special target. See <a href="one-shell">Using One Shell</a>. </p> </dd> <dt id="order-only">‘<samp>order-only</samp>’</dt> <dd>
+<p>Supports order-only prerequisites. See <a href="prerequisite-types">Types of Prerequisites</a>. </p> </dd> <dt id="output-sync">‘<samp>output-sync</samp>’</dt> <dd>
+<p>Supports the <code>--output-sync</code> command line option. See <a href="options-summary">Summary of Options</a>. </p> </dd> <dt id="second-expansion">‘<samp>second-expansion</samp>’</dt> <dd>
+<p>Supports secondary expansion of prerequisite lists. </p> </dd> <dt id="shell-export">‘<samp>shell-export</samp>’</dt> <dd>
+<p>Supports exporting <code>make</code> variables to <code>shell</code> functions. </p> </dd> <dt id="shortest-stem">‘<samp>shortest-stem</samp>’</dt> <dd>
+<p>Uses the “shortest stem” method of choosing which pattern, of multiple applicable options, will be used. See <a href="pattern-match">How Patterns Match</a>. </p> </dd> <dt id="target-specific">‘<samp>target-specific</samp>’</dt> <dd>
+<p>Supports target-specific and pattern-specific variable assignments. See <a href="target_002dspecific">Target-specific Variable Values</a>. </p> </dd> <dt id="undefine">‘<samp>undefine</samp>’</dt> <dd><p>Supports the <code>undefine</code> directive. See <a href="undefine-directive">Undefine Directive</a>. </p></dd> </dl>  </dd> <dt id=".INCLUDE_DIRS"><code>.INCLUDE_DIRS</code></dt> <dd>
+<p>Expands to a list of directories that <code>make</code> searches for included makefiles (see <a href="include">Including Other Makefiles</a>). Note that modifying this variable’s value does not change the list of directories which are searched. </p>  </dd> <dt id=".EXTRA_PREREQS"><code>.EXTRA_PREREQS</code></dt> <dd>
+<p>Each word in this variable is a new prerequisite which is added to targets for which it is set. These prerequisites differ from normal prerequisites in that they do not appear in any of the automatic variables (see <a href="automatic-variables">Automatic Variables</a>). This allows prerequisites to be defined which do not impact the recipe. </p> <p>Consider a rule to link a program: </p> <div class="example"> <pre class="example">myprog: myprog.o file1.o file2.o
+       $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $^ $(LDLIBS)
+</pre>
+</div> <p>Now suppose you want to enhance this makefile to ensure that updates to the compiler cause the program to be re-linked. You can add the compiler as a prerequisite, but you must ensure that it’s not passed as an argument to link command. You’ll need something like this: </p> <div class="example"> <pre class="example">myprog: myprog.o file1.o file2.o $(CC)
+       $(CC) $(CFLAGS) $(LDFLAGS) -o $@ \
+           $(filter-out $(CC),$^) $(LDLIBS)
+</pre>
+</div> <p>Then consider having multiple extra prerequisites: they would all have to be filtered out. Using <code>.EXTRA_PREREQS</code> and target-specific variables provides a simpler solution: </p> <div class="example"> <pre class="example">myprog: myprog.o file1.o file2.o
+       $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $^ $(LDLIBS)
+myprog: .EXTRA_PREREQS = $(CC)
+</pre>
+</div> <p>This feature can also be useful if you want to add prerequisites to a makefile you cannot easily modify: you can create a new file such as <samp>extra.mk</samp>: </p> <div class="example"> <pre class="example">myprog: .EXTRA_PREREQS = $(CC)
+</pre>
+</div> <p>then invoke <code>make -f extra.mk -f Makefile</code>. </p> <p>Setting <code>.EXTRA_PREREQS</code> globally will cause those prerequisites to be added to all targets (which did not themselves override it with a target-specific value). Note <code>make</code> is smart enough not to add a prerequisite listed in <code>.EXTRA_PREREQS</code> as a prerequisite to itself. </p> </dd> </dl><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright © 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 Free Software Foundation, Inc. <br>Licensed under the GNU Free Documentation License.<br>
+    <a href="https://www.gnu.org/software/make/manual/html_node/Special-Variables.html" class="_attribution-link">https://www.gnu.org/software/make/manual/html_node/Special-Variables.html</a>
+  </p>
+</div>