make: Variables/Recursion

1 
1 5.7.2 Communicating Variables to a Sub-'make'
1 ---------------------------------------------
1 
1 Variable values of the top-level 'make' can be passed to the sub-'make'
1 through the environment by explicit request.  These variables are
1 defined in the sub-'make' as defaults, but they do not override
1 variables defined in the makefile used by the sub-'make' unless you use
1 the '-e' switch (⇒Summary of Options Options Summary.).
1 
1    To pass down, or "export", a variable, 'make' adds the variable and
1 its value to the environment for running each line of the recipe.  The
1 sub-'make', in turn, uses the environment to initialize its table of
1 variable values.  ⇒Variables from the Environment Environment.
1 
1    Except by explicit request, 'make' exports a variable only if it is
1 either defined in the environment initially or set on the command line,
1 and if its name consists only of letters, numbers, and underscores.
1 Some shells cannot cope with environment variable names consisting of
1 characters other than letters, numbers, and underscores.
1 
1    The value of the 'make' variable 'SHELL' is not exported.  Instead,
1 the value of the 'SHELL' variable from the invoking environment is
1 passed to the sub-'make'.  You can force 'make' to export its value for
11 'SHELL' by using the 'export' directive, described below.  ⇒
 Choosing the Shell.
1 
1    The special variable 'MAKEFLAGS' is always exported (unless you
1 unexport it).  'MAKEFILES' is exported if you set it to anything.
1 
1    'make' automatically passes down variable values that were defined on
11 the command line, by putting them in the 'MAKEFLAGS' variable.  ⇒
 Options/Recursion.
1 
1    Variables are _not_ normally passed down if they were created by
11 default by 'make' (⇒Variables Used by Implicit Rules Implicit
 Variables.).  The sub-'make' will define these for itself.
1 
1    If you want to export specific variables to a sub-'make', use the
1 'export' directive, like this:
1 
1      export VARIABLE ...
1 
1 If you want to _prevent_ a variable from being exported, use the
1 'unexport' directive, like this:
1 
1      unexport VARIABLE ...
1 
1 In both of these forms, the arguments to 'export' and 'unexport' are
1 expanded, and so could be variables or functions which expand to a (list
1 of) variable names to be (un)exported.
1 
1    As a convenience, you can define a variable and export it at the same
1 time by doing:
1 
1      export VARIABLE = value
1 
1 has the same result as:
1 
1      VARIABLE = value
1      export VARIABLE
1 
1 and
1 
1      export VARIABLE := value
1 
1 has the same result as:
1 
1      VARIABLE := value
1      export VARIABLE
1 
1    Likewise,
1 
1      export VARIABLE += value
1 
1 is just like:
1 
1      VARIABLE += value
1      export VARIABLE
1 
1 ⇒Appending More Text to Variables Appending.
1 
1    You may notice that the 'export' and 'unexport' directives work in
1 'make' in the same way they work in the shell, 'sh'.
1 
1    If you want all variables to be exported by default, you can use
1 'export' by itself:
1 
1      export
1 
1 This tells 'make' that variables which are not explicitly mentioned in
1 an 'export' or 'unexport' directive should be exported.  Any variable
1 given in an 'unexport' directive will still _not_ be exported.  If you
1 use 'export' by itself to export variables by default, variables whose
1 names contain characters other than alphanumerics and underscores will
1 not be exported unless specifically mentioned in an 'export' directive.
1 
1    The behavior elicited by an 'export' directive by itself was the
1 default in older versions of GNU 'make'.  If your makefiles depend on
1 this behavior and you want to be compatible with old versions of 'make',
1 you can write a rule for the special target '.EXPORT_ALL_VARIABLES'
1 instead of using the 'export' directive.  This will be ignored by old
1 'make's, while the 'export' directive will cause a syntax error.
1 
1    Likewise, you can use 'unexport' by itself to tell 'make' _not_ to
1 export variables by default.  Since this is the default behavior, you
1 would only need to do this if 'export' had been used by itself earlier
1 (in an included makefile, perhaps).  You *cannot* use 'export' and
1 'unexport' by themselves to have variables exported for some recipes and
1 not for others.  The last 'export' or 'unexport' directive that appears
1 by itself determines the behavior for the entire run of 'make'.
1 
1    As a special feature, the variable 'MAKELEVEL' is changed when it is
1 passed down from level to level.  This variable's value is a string
1 which is the depth of the level as a decimal number.  The value is '0'
1 for the top-level 'make'; '1' for a sub-'make', '2' for a
1 sub-sub-'make', and so on.  The incrementation happens when 'make' sets
1 up the environment for a recipe.
1 
1    The main use of 'MAKELEVEL' is to test it in a conditional directive
1 (⇒Conditional Parts of Makefiles Conditionals.); this way you can
1 write a makefile that behaves one way if run recursively and another way
1 if run directly by you.
1 
1    You can use the variable 'MAKEFILES' to cause all sub-'make' commands
1 to use additional makefiles.  The value of 'MAKEFILES' is a
1 whitespace-separated list of file names.  This variable, if defined in
1 the outer-level makefile, is passed down through the environment; then
1 it serves as a list of extra makefiles for the sub-'make' to read before
11 the usual or specified ones.  ⇒The Variable 'MAKEFILES' MAKEFILES
 Variable.
1