make: Origin Function

1 
1 8.10 The 'origin' Function
1 ==========================
1 
1 The 'origin' function is unlike most other functions in that it does not
1 operate on the values of variables; it tells you something _about_ a
1 variable.  Specifically, it tells you where it came from.
1 
1    The syntax of the 'origin' function is:
1 
1      $(origin VARIABLE)
1 
1    Note that VARIABLE is the _name_ of a variable to inquire about, not
1 a _reference_ to that variable.  Therefore you would not normally use a
1 '$' or parentheses when writing it.  (You can, however, use a variable
1 reference in the name if you want the name not to be a constant.)
1 
1    The result of this function is a string telling you how the variable
1 VARIABLE was defined:
1 
1 'undefined'
1 
1      if VARIABLE was never defined.
1 
1 'default'
1 
1      if VARIABLE has a default definition, as is usual with 'CC' and so
1      on.  ⇒Variables Used by Implicit Rules Implicit Variables.
1      Note that if you have redefined a default variable, the 'origin'
1      function will return the origin of the later definition.
1 
1 'environment'
1 
1      if VARIABLE was inherited from the environment provided to 'make'.
1 
1 'environment override'
1 
1      if VARIABLE was inherited from the environment provided to 'make',
1      and is overriding a setting for VARIABLE in the makefile as a
11      result of the '-e' option (⇒Summary of Options Options
      Summary.).
1 
1 'file'
1 
1      if VARIABLE was defined in a makefile.
1 
1 'command line'
1 
1      if VARIABLE was defined on the command line.
1 
1 'override'
1 
1      if VARIABLE was defined with an 'override' directive in a makefile
1      (⇒The 'override' Directive Override Directive.).
1 
1 'automatic'
1 
1      if VARIABLE is an automatic variable defined for the execution of
1      the recipe for each rule (⇒Automatic Variables).
1 
1    This information is primarily useful (other than for your curiosity)
1 to determine if you want to believe the value of a variable.  For
1 example, suppose you have a makefile 'foo' that includes another
1 makefile 'bar'.  You want a variable 'bletch' to be defined in 'bar' if
1 you run the command 'make -f bar', even if the environment contains a
1 definition of 'bletch'.  However, if 'foo' defined 'bletch' before
1 including 'bar', you do not want to override that definition.  This
1 could be done by using an 'override' directive in 'foo', giving that
1 definition precedence over the later definition in 'bar'; unfortunately,
1 the 'override' directive would also override any command line
1 definitions.  So, 'bar' could include:
1 
1      ifdef bletch
1      ifeq "$(origin bletch)" "environment"
1      bletch = barf, gag, etc.
1      endif
1      endif
1 
1 If 'bletch' has been defined from the environment, this will redefine
1 it.
1 
1    If you want to override a previous definition of 'bletch' if it came
1 from the environment, even under '-e', you could instead write:
1 
1      ifneq "$(findstring environment,$(origin bletch))" ""
1      bletch = barf, gag, etc.
1      endif
1 
1    Here the redefinition takes place if '$(origin bletch)' returns
11 either 'environment' or 'environment override'.  ⇒Functions for
 String Substitution and Analysis Text Functions.
1