make: File Name Functions

1 
1 8.3 Functions for File Names
1 ============================
1 
1 Several of the built-in expansion functions relate specifically to
1 taking apart file names or lists of file names.
1 
1    Each of the following functions performs a specific transformation on
1 a file name.  The argument of the function is regarded as a series of
1 file names, separated by whitespace.  (Leading and trailing whitespace
1 is ignored.)  Each file name in the series is transformed in the same
1 way and the results are concatenated with single spaces between them.
1 
1 '$(dir NAMES...)'
1      Extracts the directory-part of each file name in NAMES.  The
1      directory-part of the file name is everything up through (and
1      including) the last slash in it.  If the file name contains no
1      slash, the directory part is the string './'.  For example,
1 
1           $(dir src/foo.c hacks)
1 
1      produces the result 'src/ ./'.
1 
1 '$(notdir NAMES...)'
1      Extracts all but the directory-part of each file name in NAMES.  If
1      the file name contains no slash, it is left unchanged.  Otherwise,
1      everything through the last slash is removed from it.
1 
1      A file name that ends with a slash becomes an empty string.  This
1      is unfortunate, because it means that the result does not always
1      have the same number of whitespace-separated file names as the
1      argument had; but we do not see any other valid alternative.
1 
1      For example,
1 
1           $(notdir src/foo.c hacks)
1 
1      produces the result 'foo.c hacks'.
1 
1 '$(suffix NAMES...)'
1      Extracts the suffix of each file name in NAMES.  If the file name
1      contains a period, the suffix is everything starting with the last
1      period.  Otherwise, the suffix is the empty string.  This
1      frequently means that the result will be empty when NAMES is not,
1      and if NAMES contains multiple file names, the result may contain
1      fewer file names.
1 
1      For example,
1 
1           $(suffix src/foo.c src-1.0/bar.c hacks)
1 
1      produces the result '.c .c'.
1 
1 '$(basename NAMES...)'
1      Extracts all but the suffix of each file name in NAMES.  If the
1      file name contains a period, the basename is everything starting up
1      to (and not including) the last period.  Periods in the directory
1      part are ignored.  If there is no period, the basename is the
1      entire file name.  For example,
1 
1           $(basename src/foo.c src-1.0/bar hacks)
1 
1      produces the result 'src/foo src-1.0/bar hacks'.
1 
1 '$(addsuffix SUFFIX,NAMES...)'
1      The argument NAMES is regarded as a series of names, separated by
1      whitespace; SUFFIX is used as a unit.  The value of SUFFIX is
1      appended to the end of each individual name and the resulting
1      larger names are concatenated with single spaces between them.  For
1      example,
1 
1           $(addsuffix .c,foo bar)
1 
1      produces the result 'foo.c bar.c'.
1 
1 '$(addprefix PREFIX,NAMES...)'
1      The argument NAMES is regarded as a series of names, separated by
1      whitespace; PREFIX is used as a unit.  The value of PREFIX is
1      prepended to the front of each individual name and the resulting
1      larger names are concatenated with single spaces between them.  For
1      example,
1 
1           $(addprefix src/,foo bar)
1 
1      produces the result 'src/foo src/bar'.
1 
1 '$(join LIST1,LIST2)'
1      Concatenates the two arguments word by word: the two first words
1      (one from each argument) concatenated form the first word of the
1      result, the two second words form the second word of the result,
1      and so on.  So the Nth word of the result comes from the Nth word
1      of each argument.  If one argument has more words that the other,
1      the extra words are copied unchanged into the result.
1 
1      For example, '$(join a b,.c .o)' produces 'a.c b.o'.
1 
1      Whitespace between the words in the lists is not preserved; it is
1      replaced with a single space.
1 
1      This function can merge the results of the 'dir' and 'notdir'
1      functions, to produce the original list of files which was given to
1      those two functions.
1 
1 '$(wildcard PATTERN)'
1      The argument PATTERN is a file name pattern, typically containing
1      wildcard characters (as in shell file name patterns).  The result
1      of 'wildcard' is a space-separated list of the names of existing
11      files that match the pattern.  ⇒Using Wildcard Characters in
      File Names Wildcards.
1 
1 '$(realpath NAMES...)'
1      For each file name in NAMES return the canonical absolute name.  A
1      canonical name does not contain any '.' or '..' components, nor any
1      repeated path separators ('/') or symlinks.  In case of a failure
1      the empty string is returned.  Consult the 'realpath(3)'
1      documentation for a list of possible failure causes.
1 
1 '$(abspath NAMES...)'
1      For each file name in NAMES return an absolute name that does not
1      contain any '.' or '..' components, nor any repeated path
1      separators ('/').  Note that, in contrast to 'realpath' function,
1      'abspath' does not resolve symlinks and does not require the file
1      names to refer to an existing file or directory.  Use the
1      'wildcard' function to test for existence.
1