make: Reading Makefiles

1 
1 3.7 How 'make' Reads a Makefile
1 ===============================
1 
1 GNU 'make' does its work in two distinct phases.  During the first phase
1 it reads all the makefiles, included makefiles, etc.  and internalizes
1 all the variables and their values, implicit and explicit rules, and
1 constructs a dependency graph of all the targets and their
1 prerequisites.  During the second phase, 'make' uses these internal
1 structures to determine what targets will need to be rebuilt and to
1 invoke the rules necessary to do so.
1 
1    It's important to understand this two-phase approach because it has a
1 direct impact on how variable and function expansion happens; this is
1 often a source of some confusion when writing makefiles.  Here we will
1 present a summary of the phases in which expansion happens for different
1 constructs within the makefile.  We say that expansion is "immediate" if
1 it happens during the first phase: in this case 'make' will expand any
1 variables or functions in that section of a construct as the makefile is
1 parsed.  We say that expansion is "deferred" if expansion is not
1 performed immediately.  Expansion of a deferred construct is not
1 performed until either the construct appears later in an immediate
1 context, or until the second phase.
1 
1    You may not be familiar with some of these constructs yet.  You can
1 reference this section as you become familiar with them, in later
1 chapters.
1 
1 Variable Assignment
1 -------------------
1 
1 Variable definitions are parsed as follows:
1 
1      IMMEDIATE = DEFERRED
1      IMMEDIATE ?= DEFERRED
1      IMMEDIATE := IMMEDIATE
1      IMMEDIATE ::= IMMEDIATE
1      IMMEDIATE += DEFERRED or IMMEDIATE
1      IMMEDIATE != IMMEDIATE
1 
1      define IMMEDIATE
1        DEFERRED
1      endef
1 
1      define IMMEDIATE =
1        DEFERRED
1      endef
1 
1      define IMMEDIATE ?=
1        DEFERRED
1      endef
1 
1      define IMMEDIATE :=
1        IMMEDIATE
1      endef
1 
1      define IMMEDIATE ::=
1        IMMEDIATE
1      endef
1 
1      define IMMEDIATE +=
1        DEFERRED or IMMEDIATE
1      endef
1 
1      define IMMEDIATE !=
1        IMMEDIATE
1      endef
1 
1    For the append operator, '+=', the right-hand side is considered
1 immediate if the variable was previously set as a simple variable (':='
1 or '::='), and deferred otherwise.
1 
1    For the shell assignment operator, '!=', the right-hand side is
1 evaluated immediately and handed to the shell.  The result is stored in
1 the variable named on the left, and that variable becomes a simple
1 variable (and will thus be re-evaluated on each reference).
1 
1 Conditional Directives
1 ----------------------
1 
1 Conditional directives are parsed immediately.  This means, for example,
1 that automatic variables cannot be used in conditional directives, as
1 automatic variables are not set until the recipe for that rule is
1 invoked.  If you need to use automatic variables in a conditional
1 directive you _must_ move the condition into the recipe and use shell
1 conditional syntax instead.
1 
1 Rule Definition
1 ---------------
1 
1 A rule is always expanded the same way, regardless of the form:
1 
1      IMMEDIATE : IMMEDIATE ; DEFERRED
1              DEFERRED
1 
1    That is, the target and prerequisite sections are expanded
1 immediately, and the recipe used to construct the target is always
1 deferred.  This general rule is true for explicit rules, pattern rules,
1 suffix rules, static pattern rules, and simple prerequisite definitions.
1