path: root/devdocs/gnu_make/variables_002frecursion.html

  <h1 class="subsection">Communicating Variables to a Sub-make</h1>        <p>Variable values of the top-level <code>make</code> can be passed to the sub-<code>make</code> through the environment by explicit request. These variables are defined in the sub-<code>make</code> as defaults, but they do not override variables defined in the makefile used by the sub-<code>make</code> unless you use the ‘<samp>-e</samp>’ switch (see <a href="options-summary">Summary of Options</a>). </p> <p>To pass down, or <em>export</em>, a variable, <code>make</code> adds the variable and its value to the environment for running each line of the recipe. The sub-<code>make</code>, in turn, uses the environment to initialize its table of variable values. See <a href="environment">Variables from the Environment</a>. </p> <p>Except by explicit request, <code>make</code> exports a variable only if it is either defined in the environment initially, or if set on the command line and its name consists only of letters, numbers, and underscores. </p>  <p>The value of the <code>make</code> variable <code>SHELL</code> is not exported. Instead, the value of the <code>SHELL</code> variable from the invoking environment is passed to the sub-<code>make</code>. You can force <code>make</code> to export its value for <code>SHELL</code> by using the <code>export</code> directive, described below. See <a href="choosing-the-shell">Choosing the Shell</a>. </p> <p>The special variable <code>MAKEFLAGS</code> is always exported (unless you unexport it). <code>MAKEFILES</code> is exported if you set it to anything. </p> <p><code>make</code> automatically passes down variable values that were defined on the command line, by putting them in the <code>MAKEFLAGS</code> variable. See <a href="options_002frecursion">Options/Recursion</a>. </p> <p>Variables are <em>not</em> normally passed down if they were created by default by <code>make</code> (see <a href="implicit-variables">Variables Used by Implicit Rules</a>). The sub-<code>make</code> will define these for itself. </p>  <p>If you want to export specific variables to a sub-<code>make</code>, use the <code>export</code> directive, like this: </p> <div class="example"> <pre class="example">export <var>variable</var> …
</pre>
</div> <p> If you want to <em>prevent</em> a variable from being exported, use the <code>unexport</code> directive, like this: </p> <div class="example"> <pre class="example">unexport <var>variable</var> …
</pre>
</div> <p>In both of these forms, the arguments to <code>export</code> and <code>unexport</code> are expanded, and so could be variables or functions which expand to a (list of) variable names to be (un)exported. </p> <p>As a convenience, you can define a variable and export it at the same time by doing: </p> <div class="example"> <pre class="example">export <var>variable</var> = value
</pre>
</div> <p>has the same result as: </p> <div class="example"> <pre class="example"><var>variable</var> = value
export <var>variable</var>
</pre>
</div> <p>and </p> <div class="example"> <pre class="example">export <var>variable</var> := value
</pre>
</div> <p>has the same result as: </p> <div class="example"> <pre class="example"><var>variable</var> := value
export <var>variable</var>
</pre>
</div> <p>Likewise, </p> <div class="example"> <pre class="example">export <var>variable</var> += value
</pre>
</div> <p>is just like: </p> <div class="example"> <pre class="example"><var>variable</var> += value
export <var>variable</var>
</pre>
</div> <p>See <a href="appending">Appending More Text to Variables</a>. </p> <p>You may notice that the <code>export</code> and <code>unexport</code> directives work in <code>make</code> in the same way they work in the shell, <code>sh</code>. </p> <p>If you want all variables to be exported by default, you can use <code>export</code> by itself: </p> <div class="example"> <pre class="example">export
</pre>
</div> <p>This tells <code>make</code> that variables which are not explicitly mentioned in an <code>export</code> or <code>unexport</code> directive should be exported. Any variable given in an <code>unexport</code> directive will still <em>not</em> be exported. </p>   <p>The behavior elicited by an <code>export</code> directive by itself was the default in older versions of GNU <code>make</code>. If your makefiles depend on this behavior and you want to be compatible with old versions of <code>make</code>, you can add the special target <code>.EXPORT_ALL_VARIABLES</code> to your makefile instead of using the <code>export</code> directive. This will be ignored by old <code>make</code>s, while the <code>export</code> directive will cause a syntax error. </p> <p>When using <code>export</code> by itself or <code>.EXPORT_ALL_VARIABLES</code> to export variables by default, only variables whose names consist solely of alphanumerics and underscores will be exported. To export other variables you must specifically mention them in an <code>export</code> directive. </p> <p>Adding a variable’s value to the environment requires it to be expanded. If expanding a variable has side-effects (such as the <code>info</code> or <code>eval</code> or similar functions) then these side-effects will be seen every time a command is invoked. You can avoid this by ensuring that such variables have names which are not exportable by default. However, a better solution is to <em>not</em> use this “export by default” facility at all, and instead explicitly <code>export</code> the relevant variables by name. </p> <p>You can use <code>unexport</code> by itself to tell <code>make</code> <em>not</em> to export variables by default. Since this is the default behavior, you would only need to do this if <code>export</code> had been used by itself earlier (in an included makefile, perhaps). You <strong>cannot</strong> use <code>export</code> and <code>unexport</code> by themselves to have variables exported for some recipes and not for others. The last <code>export</code> or <code>unexport</code> directive that appears by itself determines the behavior for the entire run of <code>make</code>. </p>   <p>As a special feature, the variable <code>MAKELEVEL</code> is changed when it is passed down from level to level. This variable’s value is a string which is the depth of the level as a decimal number. The value is ‘<samp>0</samp>’ for the top-level <code>make</code>; ‘<samp>1</samp>’ for a sub-<code>make</code>, ‘<samp>2</samp>’ for a sub-sub-<code>make</code>, and so on. The incrementation happens when <code>make</code> sets up the environment for a recipe. </p> <p>The main use of <code>MAKELEVEL</code> is to test it in a conditional directive (see <a href="conditionals">Conditional Parts of Makefiles</a>); this way you can write a makefile that behaves one way if run recursively and another way if run directly by you. </p>  <p>You can use the variable <code>MAKEFILES</code> to cause all sub-<code>make</code> commands to use additional makefiles. The value of <code>MAKEFILES</code> is a whitespace-separated list of file names. This variable, if defined in the outer-level makefile, is passed down through the environment; then it serves as a list of extra makefiles for the sub-<code>make</code> to read before the usual or specified ones. See <a href="makefiles-variable">The Variable <code>MAKEFILES</code></a>. </p><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/Variables_002fRecursion.html" class="_attribution-link">https://www.gnu.org/software/make/manual/html_node/Variables_002fRecursion.html</a>
  </p>
</div>