20.2. Adding a search path to a scanner: FindPathDirs

Many scanners need to search for included files or dependencies using a path variable; this is how $CPPPATH and $LIBPATH work. The path to search is passed to your scanner as the path argument. Path variables may be lists of nodes, semicolon-separated strings, or even contain SCons variables which need to be expanded. Fortunately, SCons provides the FindPathDirs function which itself returns a function to expand a given path (given as a SCons construction variable name) to a list of paths at the time the scanner is called. Deferring evaluation until that point allows, for instance, the path to contain $TARGET references which differ for each file scanned.

Using FindPathDirs is quite easy. Continuing the above example, using KPATH as the construction variable with the search path (analogous to $CPPPATH), we just modify the Scanner constructor call to include a path keyword arg:

        kscan = Scanner(function = kfile_scan,
                        skeys = ['.k'],
                        path=FindPathDirs('KPATH'))
    

FindPathDirs returns a callable object that, when called, will essentially expand the elements in env['KPATH'] and tell the scanner to search in those dirs. It will also properly add related repository and variant dirs to the search list. As a side note, the returned method stores the path in an efficient way so lookups are fast even when variable substitutions may be needed. This is important since many files get scanned in a typical build.