- 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’.
- 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 ‘%’ inpattern. Only the first ‘%’ in the pattern and replacement is treated this way; any subsequent ‘%’ is unchanged.‘%’ characters in
patsubstfunction 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.
$(patsubst %.c,%.o,x.c.c bar.c)produces the value ‘x.c.o bar.o’.Substitution references (see Substitution References) are a simpler way to get the effect of the
$(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.oTo get the list of corresponding source files, you could simply write:
$(objects:.o=.c)instead of using the general form:
- 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
stripcan be very useful when used in conjunction with conditionals. When comparing something with the empty string ‘’ using
ifneq, you usually want a string of just whitespace to match the empty string (see 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!' endifReplacing the variable reference ‘$(needs_made)’ with the function call ‘$(strip $(needs_made))’ in the
ifneqdirective would make it more robust.
- 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. See Testing Flags, for a practical application of
- 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
filterfunction 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 foosays 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.
- 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
filterfunction.For example, given:
objects=main1.o foo.o main2.o bar.o mains=main1.o main2.othe following generates a list which contains all the object files not in ‘mains’:
- 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
sortremoves duplicate words, you can use it for this purpose even if you don't care about the sort order.
- Returns the nth word of text. The legitimate values of n start from 1. If n is bigger than the number of words in text, the value is empty. For example,
$(word 2, foo bar baz)returns ‘bar’.
- Returns the list of words in text starting with word s and ending with word e (inclusive). The legitimate values of s start from 1; e may start from 0. If s is bigger than the number of words in text, the value is empty. If e is bigger than the number of words in text, words up to the end of text are returned. If s is greater than e, nothing is returned. For example,
$(wordlist 2, 3, foo bar baz)returns ‘bar baz’.
- Returns the number of words in text. Thus, the last word of text is
- The argument names is regarded as a series of names, separated by whitespace. The value is the first name in the series. The rest of the names are ignored.For example,
$(firstword foo bar)produces the result ‘foo’. Although
)is the same as
firstwordfunction is retained for its simplicity.
- The argument names is regarded as a series of names, separated by whitespace. The value is the last name in the series.For example,
$(lastword foo bar)produces the result ‘bar’. Although
)is the same as
lastwordfunction was added for its simplicity and better performance.
patsubst. Suppose that a makefile uses the
VPATHvariable to specify a list of directories that
makeshould search for prerequisite files (see
VPATHSearch Path for All Prerequisites). This example shows how to tell the C compiler to search for header files in the same list of directories.
The value of
VPATHis a list of directories separated by colons, such as ‘src:../headers’. First, the
substfunction is used to change the colons to spaces:
$(subst :, ,$(VPATH))
This produces ‘src ../headers’. Then
patsubstis 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
overridedirective is used so that the new value is assigned even if the previous value of
CFLAGSwas specified with a command argument (see The
8.3 Functions for File NamesSeveral of the built-in expansion functions relate specifically to taking apart file names or lists of file names.
Each of the following functions performs a specific transformation on a file name. The argument of the function is regarded as a series of file names, separated by whitespace. (Leading and trailing whitespace is ignored.) Each file name in the series is transformed in the same way and the results are concatenated with single spaces between them.
- Extracts the directory-part of each file name in names. The directory-part of the file name is everything up through (and including) the last slash in it. If the file name contains no slash, the directory part is the string ‘./’. For example,
$(dir src/foo.c hacks)produces the result ‘src/ ./’.
- Extracts all but the directory-part of each file name in names. If the file name contains no slash, it is left unchanged. Otherwise, everything through the last slash is removed from it.A file name that ends with a slash becomes an empty string. This is unfortunate, because it means that the result does not always have the same number of whitespace-separated file names as the argument had; but we do not see any other valid alternative.
$(notdir src/foo.c hacks)produces the result ‘foo.c hacks’.
- Extracts the suffix of each file name in names. If the file name contains a period, the suffix is everything starting with the last period. Otherwise, the suffix is the empty string. This frequently means that the result will be empty when names is not, and if names contains multiple file names, the result may contain fewer file names.For example,
$(suffix src/foo.c src-1.0/bar.c hacks)produces the result ‘.c .c’.
- Extracts all but the suffix of each file name in names. If the file name contains a period, the basename is everything starting up to (and not including) the last period. Periods in the directory part are ignored. If there is no period, the basename is the entire file name. For example,
$(basename src/foo.c src-1.0/bar hacks)produces the result ‘src/foo src-1.0/bar hacks’.
- The argument names is regarded as a series of names, separated by whitespace; suffix is used as a unit. The value of suffix is appended to the end of each individual name and the resulting larger names are concatenated with single spaces between them. For example,
$(addsuffix .c,foo bar)produces the result ‘foo.c bar.c’.
- The argument names is regarded as a series of names, separated by whitespace; prefix is used as a unit. The value of prefix is prepended to the front of each individual name and the resulting larger names are concatenated with single spaces between them. For example,
$(addprefix src/,foo bar)produces the result ‘src/foo src/bar’.
- Concatenates the two arguments word by word: the two first words (one from each argument) concatenated form the first word of the result, the two second words form the second word of the result, and so on. So the nth word of the result comes from the nth word of each argument. If one argument has more words that the other, the extra words are copied unchanged into the result.For example, ‘$(join a b,.c .o)’ produces ‘a.c b.o’.
Whitespace between the words in the lists is not preserved; it is replaced with a single space.
This function can merge the results of the
notdirfunctions, to produce the original list of files which was given to those two functions.
- The argument pattern is a file name pattern, typically containing wildcard characters (as in shell file name patterns). The result of
wildcardis a space-separated list of the names of existing files that match the pattern. See Using Wildcard Characters in File Names.
- For each file name in names return the canonical absolute name. A canonical name does not contain any
..components, nor any repeated path separators (
/) or symlinks. In case of a failure the empty string is returned. Consult the
realpath(3)documentation for a list of possible failure causes.
- For each file name in names return an absolute name that does not contain any
..components, nor any repeated path separators (
/). Note that, in contrast to
abspathdoes not resolve symlinks and does not require the file names to refer to an existing file or directory. Use the
wildcardfunction to test for existence.