(make) Text Functions

Info Catalog

(make) Syntax of Functions

(make) Functions

(make) File Name Functions

 
 Functions for String Substitution and Analysis
 ==============================================
 
    Here are some functions that operate on strings:
 
 `$(subst FROM,TO,TEXT)'
      Performs a textual replacement on the text TEXT: each occurrence
      of FROM is replaced by TO.  The result is substituted for the
      function call.  For example,
 
           $(subst ee,EE,feet on the street)
 
      substitutes the string `fEEt on the strEEt'.
 
 `$(patsubst PATTERN,REPLACEMENT,TEXT)'
      Finds whitespace-separated words in TEXT that match PATTERN and
      replaces them with REPLACEMENT.  Here PATTERN may contain a `%'
      which acts as a wildcard, matching any number of any characters
      within a word.  If REPLACEMENT also contains a `%', the `%' is
      replaced by the text that matched the `%' in PATTERN.
 
      `%' characters in `patsubst' function invocations can be quoted
      with preceding backslashes (`\').  Backslashes that would
      otherwise quote `%' characters can be quoted with more backslashes.
      Backslashes that quote `%' characters or other backslashes are
      removed from the pattern before it is compared file names or has a
      stem substituted into it.  Backslashes that are not in danger of
      quoting `%' characters go unmolested.  For example, the pattern
      `the\%weird\\%pattern\\' has `the%weird\' preceding the operative
      `%' character, and `pattern\\' following it.  The final two
      backslashes are left alone because they cannot affect any `%'
      character.
 
      Whitespace between words is folded into single space characters;
      leading and trailing whitespace is discarded.
 
      For example,
 
           $(patsubst %.c,%.o,x.c.c bar.c)
 
      produces the value `x.c.o bar.o'.
 
      Substitution references ( Substitution References
      Substitution Refs.) are a simpler way to get the effect of the
      `patsubst' function:
 
           $(VAR:PATTERN=REPLACEMENT)
 
      is equivalent to
 
           $(patsubst PATTERN,REPLACEMENT,$(VAR))
 
      The second shorthand simplifies one of the most common uses of
      `patsubst': replacing the suffix at the end of file names.
 
           $(VAR:SUFFIX=REPLACEMENT)
 
      is equivalent to
 
           $(patsubst %SUFFIX,%REPLACEMENT,$(VAR))
 
      For example, you might have a list of object files:
 
           objects = foo.o bar.o baz.o
 
      To get the list of corresponding source files, you could simply
      write:
 
           $(objects:.o=.c)
 
      instead of using the general form:
 
           $(patsubst %.o,%.c,$(objects))
 
 `$(strip STRING)'
      Removes leading and trailing whitespace from STRING and replaces
      each internal sequence of one or more whitespace characters with a
      single space.  Thus, `$(strip a b  c )' results in `a b c'.
 
      The function `strip' can be very useful when used in conjunction
      with conditionals.  When comparing something with the empty string
      `' using `ifeq' or `ifneq', you usually want a string of just
      whitespace to match the empty string ( Conditionals).
 
      Thus, the following may fail to have the desired results:
 
           .PHONY: all
           ifneq   "$(needs_made)" ""
           all: $(needs_made)
           else
           all:;@echo 'Nothing to make!'
           endif
 
      Replacing the variable reference `$(needs_made)' with the function
      call `$(strip $(needs_made))' in the `ifneq' directive would make
      it more robust.
 
 `$(findstring FIND,IN)'
      Searches IN for an occurrence of FIND.  If it occurs, the value is
      FIND; otherwise, the value is empty.  You can use this function in
      a conditional to test for the presence of a specific substring in
      a given string.  Thus, the two examples,
 
           $(findstring a,a b c)
           $(findstring a,b c)
 
      produce the values `a' and `' (the empty string), respectively.
       Testing Flags, for a practical application of `findstring'.
 
 `$(filter PATTERN...,TEXT)'
      Returns all whitespace-separated words in TEXT that _do_ match any
      of the PATTERN words, removing any words that _do not_ match.  The
      patterns are written using `%', just like the patterns used in the
      `patsubst' function above.
 
      The `filter' function can be used to separate out different types
      of strings (such as file names) in a variable.  For example:
 
           sources := foo.c bar.c baz.s ugh.h
           foo: $(sources)
                   cc $(filter %.c %.s,$(sources)) -o foo
 
      says that `foo' depends of `foo.c', `bar.c', `baz.s' and `ugh.h'
      but only `foo.c', `bar.c' and `baz.s' should be specified in the
      command to the compiler.
 
 `$(filter-out PATTERN...,TEXT)'
      Returns all whitespace-separated words in TEXT that _do not_ match
      any of the PATTERN words, removing the words that _do_ match one
      or more.  This is the exact opposite of the `filter' function.
 
      Removes all whitespace-separated words in TEXT that _do_ match the
      PATTERN words, returning only the words that _do not_ match.  This
      is the exact opposite of the `filter' function.
 
      For example, given:
 
           objects=main1.o foo.o main2.o bar.o
           mains=main1.o main2.o
 
      the following generates a list which contains all the object files
      not in `mains':
 
           $(filter-out $(mains),$(objects))
 
 `$(sort LIST)'
      Sorts the words of LIST in lexical order, removing duplicate
      words.  The output is a list of words separated by single spaces.
      Thus,
 
           $(sort foo bar lose)
 
      returns the value `bar foo lose'.
 
      Incidentally, since `sort' removes duplicate words, you can use it
      for this purpose even if you don't care about the sort order.
 
    Here is a realistic example of the use of `subst' and `patsubst'.
 Suppose that a makefile uses the `VPATH' variable to specify a list of
 directories that `make' should search for prerequisite files (
 `VPATH' Search Path for All Prerequisites General Search.).  This
 example shows how to tell the C compiler to search for header files in
 the same list of directories.
 
    The value of `VPATH' is a list of directories separated by colons,
 such as `src:../headers'.  First, the `subst' function is used to
 change the colons to spaces:
 
      $(subst :, ,$(VPATH))
 
 This produces `src ../headers'.  Then `patsubst' is used to turn each
 directory name into a `-I' flag.  These can be added to the value of
 the variable `CFLAGS', which is passed automatically to the C compiler,
 like this:
 
      override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))
 
 The effect is to append the text `-Isrc -I../headers' to the previously
 given value of `CFLAGS'.  The `override' directive is used so that the
 new value is assigned even if the previous value of `CFLAGS' was
 specified with a command argument ( The `override' Directive
 Override Directive.).
 

Info Catalog

(make) Syntax of Functions

(make) Functions

(make) File Name Functions