make: Automatic Variables

1 
1 10.5.3 Automatic Variables
1 --------------------------
1 
1 Suppose you are writing a pattern rule to compile a '.c' file into a
1 '.o' file: how do you write the 'cc' command so that it operates on the
1 right source file name?  You cannot write the name in the recipe,
1 because the name is different each time the implicit rule is applied.
1 
1    What you do is use a special feature of 'make', the "automatic
1 variables".  These variables have values computed afresh for each rule
1 that is executed, based on the target and prerequisites of the rule.  In
1 this example, you would use '$@' for the object file name and '$<' for
1 the source file name.
1 
1    It's very important that you recognize the limited scope in which
1 automatic variable values are available: they only have values within
1 the recipe.  In particular, you cannot use them anywhere within the
1 target list of a rule; they have no value there and will expand to the
1 empty string.  Also, they cannot be accessed directly within the
1 prerequisite list of a rule.  A common mistake is attempting to use '$@'
1 within the prerequisites list; this will not work.  However, there is a
11 special feature of GNU 'make', secondary expansion (⇒Secondary
 Expansion), which will allow automatic variable values to be used in
1 prerequisite lists.
1 
1    Here is a table of automatic variables:
1 
1 '$@'
1      The file name of the target of the rule.  If the target is an
1      archive member, then '$@' is the name of the archive file.  In a
11      pattern rule that has multiple targets (⇒Introduction to
      Pattern Rules Pattern Intro.), '$@' is the name of whichever
1      target caused the rule's recipe to be run.
1 
1 '$%'
1      The target member name, when the target is an archive member.
1      ⇒Archives.  For example, if the target is 'foo.a(bar.o)'
1      then '$%' is 'bar.o' and '$@' is 'foo.a'.  '$%' is empty when the
1      target is not an archive member.
1 
1 '$<'
1      The name of the first prerequisite.  If the target got its recipe
1      from an implicit rule, this will be the first prerequisite added by
1      the implicit rule (⇒Implicit Rules).
1 
1 '$?'
1      The names of all the prerequisites that are newer than the target,
1      with spaces between them.  For prerequisites which are archive
1      members, only the named member is used (⇒Archives).
1 
1 '$^'
1      The names of all the prerequisites, with spaces between them.  For
1      prerequisites which are archive members, only the named member is
1      used (⇒Archives).  A target has only one prerequisite on
1      each other file it depends on, no matter how many times each file
1      is listed as a prerequisite.  So if you list a prerequisite more
1      than once for a target, the value of '$^' contains just one copy of
1      the name.  This list does *not* contain any of the order-only
1      prerequisites; for those see the '$|' variable, below.
1 
1 '$+'
1      This is like '$^', but prerequisites listed more than once are
1      duplicated in the order they were listed in the makefile.  This is
1      primarily useful for use in linking commands where it is meaningful
1      to repeat library file names in a particular order.
1 
1 '$|'
1      The names of all the order-only prerequisites, with spaces between
1      them.
1 
1 '$*'
11      The stem with which an implicit rule matches (⇒How Patterns
      Match Pattern Match.).  If the target is 'dir/a.foo.b' and the
1      target pattern is 'a.%.b' then the stem is 'dir/foo'.  The stem is
1      useful for constructing names of related files.
1 
1      In a static pattern rule, the stem is part of the file name that
1      matched the '%' in the target pattern.
1 
1      In an explicit rule, there is no stem; so '$*' cannot be determined
1      in that way.  Instead, if the target name ends with a recognized
1      suffix (⇒Old-Fashioned Suffix Rules Suffix Rules.), '$*' is
1      set to the target name minus the suffix.  For example, if the
1      target name is 'foo.c', then '$*' is set to 'foo', since '.c' is a
1      suffix.  GNU 'make' does this bizarre thing only for compatibility
1      with other implementations of 'make'.  You should generally avoid
1      using '$*' except in implicit rules or static pattern rules.
1 
1      If the target name in an explicit rule does not end with a
1      recognized suffix, '$*' is set to the empty string for that rule.
1 
1    '$?' is useful even in explicit rules when you wish to operate on
1 only the prerequisites that have changed.  For example, suppose that an
1 archive named 'lib' is supposed to contain copies of several object
1 files.  This rule copies just the changed object files into the archive:
1 
1      lib: foo.o bar.o lose.o win.o
1              ar r lib $?
1 
1    Of the variables listed above, four have values that are single file
1 names, and three have values that are lists of file names.  These seven
1 have variants that get just the file's directory name or just the file
1 name within the directory.  The variant variables' names are formed by
1 appending 'D' or 'F', respectively.  These variants are semi-obsolete in
1 GNU 'make' since the functions 'dir' and 'notdir' can be used to get a
1 similar effect (⇒Functions for File Names File Name Functions.).
1 Note, however, that the 'D' variants all omit the trailing slash which
1 always appears in the output of the 'dir' function.  Here is a table of
1 the variants:
1 
1 '$(@D)'
1      The directory part of the file name of the target, with the
1      trailing slash removed.  If the value of '$@' is 'dir/foo.o' then
1      '$(@D)' is 'dir'.  This value is '.' if '$@' does not contain a
1      slash.
1 
1 '$(@F)'
1      The file-within-directory part of the file name of the target.  If
1      the value of '$@' is 'dir/foo.o' then '$(@F)' is 'foo.o'.  '$(@F)'
1      is equivalent to '$(notdir $@)'.
1 
1 '$(*D)'
1 '$(*F)'
1      The directory part and the file-within-directory part of the stem;
1      'dir' and 'foo' in this example.
1 
1 '$(%D)'
1 '$(%F)'
1      The directory part and the file-within-directory part of the target
1      archive member name.  This makes sense only for archive member
1      targets of the form 'ARCHIVE(MEMBER)' and is useful only when
11      MEMBER may contain a directory name.  (⇒Archive Members as
      Targets Archive Members.)
1 
1 '$(<D)'
1 '$(<F)'
1      The directory part and the file-within-directory part of the first
1      prerequisite.
1 
1 '$(^D)'
1 '$(^F)'
1      Lists of the directory parts and the file-within-directory parts of
1      all prerequisites.
1 
1 '$(+D)'
1 '$(+F)'
1      Lists of the directory parts and the file-within-directory parts of
1      all prerequisites, including multiple instances of duplicated
1      prerequisites.
1 
1 '$(?D)'
1 '$(?F)'
1      Lists of the directory parts and the file-within-directory parts of
1      all prerequisites that are newer than the target.
1 
1    Note that we use a special stylistic convention when we talk about
1 these automatic variables; we write "the value of '$<'", rather than
1 "the variable '<'" as we would write for ordinary variables such as
1 'objects' and 'CFLAGS'.  We think this convention looks more natural in
1 this special case.  Please do not assume it has a deep significance;
1 '$<' refers to the variable named '<' just as '$(CFLAGS)' refers to the
1 variable named 'CFLAGS'.  You could just as well use '$(<)' in place of
1 '$<'.
1