diff options
author | Gary Oberbrunner <garyo@oberbrunner.com> | 2010-06-04 02:16:13 (GMT) |
---|---|---|
committer | Gary Oberbrunner <garyo@oberbrunner.com> | 2010-06-04 02:16:13 (GMT) |
commit | a91b87f78c9d854b048dadcf44c7b468dd58108e (patch) | |
tree | 34c70590a83eeb3b54bd025ea5100d5f87417676 /doc/user/scanners.xml | |
parent | 7aa9de00000a3bba9746c18d46bf79c4ca1f69f2 (diff) | |
download | SCons-a91b87f78c9d854b048dadcf44c7b468dd58108e.zip SCons-a91b87f78c9d854b048dadcf44c7b468dd58108e.tar.gz SCons-a91b87f78c9d854b048dadcf44c7b468dd58108e.tar.bz2 |
Document FindPathDirs in Users Guide
Diffstat (limited to 'doc/user/scanners.xml')
-rw-r--r-- | doc/user/scanners.xml | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml index 0fa4d2e..1435077 100644 --- a/doc/user/scanners.xml +++ b/doc/user/scanners.xml @@ -315,3 +315,51 @@ over the file scanning rather than being called for each input line: --> </section> + + <section> + <title>Adding a search path to a scanner: &FindPathDirs;</title> + + <para> + + Many scanners need to search for included files or dependencies + using a path variable; this is how &cv-link-CPPPATH; and + &cv-link-LIBPATH; work. The path to search is passed to your + scanner as the <literal>path</literal> 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. + + </para> + + <para> + + Using &FindPathDirs; is quite easy. Continuing the above example, + using KPATH as the construction variable with the search path + (analogous to &cv-link-CPPPATH;), we just modify the &Scanner; + constructor call to include a path keyword arg: + + </para> + + <programlisting> + kscan = Scanner(function = kfile_scan, + skeys = ['.k'], + path=FindPathDirs('KPATH')) + </programlisting> + + <para> + + 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. + + </para> + </section> |