make: Selective Search

1 
1 4.5.2 The 'vpath' Directive
1 ---------------------------
1 
1 Similar to the 'VPATH' variable, but more selective, is the 'vpath'
1 directive (note lower case), which allows you to specify a search path
1 for a particular class of file names: those that match a particular
1 pattern.  Thus you can supply certain search directories for one class
1 of file names and other directories (or none) for other file names.
1 
1    There are three forms of the 'vpath' directive:
1 
1 'vpath PATTERN DIRECTORIES'
1      Specify the search path DIRECTORIES for file names that match
1      PATTERN.
1 
1      The search path, DIRECTORIES, is a list of directories to be
1      searched, separated by colons (semi-colons on MS-DOS and
1      MS-Windows) or blanks, just like the search path used in the
1      'VPATH' variable.
1 
1 'vpath PATTERN'
1      Clear out the search path associated with PATTERN.
1 
1 'vpath'
1 
1      Clear all search paths previously specified with 'vpath'
1      directives.
1 
1    A 'vpath' pattern is a string containing a '%' character.  The string
1 must match the file name of a prerequisite that is being searched for,
1 the '%' character matching any sequence of zero or more characters (as
11 in pattern rules; ⇒Defining and Redefining Pattern Rules Pattern
 Rules.).  For example, '%.h' matches files that end in '.h'.  (If there
1 is no '%', the pattern must match the prerequisite exactly, which is not
1 useful very often.)
1 
1    '%' characters in a 'vpath' directive's pattern can be quoted with
1 preceding backslashes ('\').  Backslashes that would otherwise quote '%'
1 characters can be quoted with more backslashes.  Backslashes that quote
1 '%' characters or other backslashes are removed from the pattern before
1 it is compared to file names.  Backslashes that are not in danger of
1 quoting '%' characters go unmolested.
1 
1    When a prerequisite fails to exist in the current directory, if the
1 PATTERN in a 'vpath' directive matches the name of the prerequisite
1 file, then the DIRECTORIES in that directive are searched just like (and
1 before) the directories in the 'VPATH' variable.
1 
1    For example,
1 
1      vpath %.h ../headers
1 
1 tells 'make' to look for any prerequisite whose name ends in '.h' in the
1 directory '../headers' if the file is not found in the current
1 directory.
1 
1    If several 'vpath' patterns match the prerequisite file's name, then
1 'make' processes each matching 'vpath' directive one by one, searching
1 all the directories mentioned in each directive.  'make' handles
1 multiple 'vpath' directives in the order in which they appear in the
1 makefile; multiple directives with the same pattern are independent of
1 each other.
1 
1    Thus,
1 
1      vpath %.c foo
1      vpath %   blish
1      vpath %.c bar
1 
1 will look for a file ending in '.c' in 'foo', then 'blish', then 'bar',
1 while
1 
1      vpath %.c foo:bar
1      vpath %   blish
1 
1 will look for a file ending in '.c' in 'foo', then 'bar', then 'blish'.
1