summaryrefslogtreecommitdiff
path: root/doc/user/scanners.xml
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2010-06-15 14:28:22 +0000
committerLuca Falavigna <dktrkranz@debian.org>2010-06-15 14:28:22 +0000
commit738149c9bfb9965d013d01ef99f9bb1c2819e7e8 (patch)
tree0397d9bf3b12c903dc73419585df231397ff343c /doc/user/scanners.xml
parente7885e3af440eaef38a9301fd92a105afc8ddebb (diff)
Imported Upstream version 2.0.0upstream/2.0.0
Diffstat (limited to 'doc/user/scanners.xml')
-rw-r--r--doc/user/scanners.xml48
1 files changed, 48 insertions, 0 deletions
diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml
index 7921577..2aba7d2 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>