summaryrefslogtreecommitdiff
path: root/doc/user/scanners.in
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2010-06-15 14:28:28 +0000
committerLuca Falavigna <dktrkranz@debian.org>2010-06-15 14:28:28 +0000
commit0ed55e71a9f4b9cda836c6a4a5408cece60db0c6 (patch)
treeb1e82f6e428ac15ed9b4de93e48d8079420d537d /doc/user/scanners.in
parentfe00e4f75ba00298c30d6854b245c2a42c6542b8 (diff)
parent738149c9bfb9965d013d01ef99f9bb1c2819e7e8 (diff)
Merge commit 'upstream/2.0.0'
Diffstat (limited to 'doc/user/scanners.in')
-rw-r--r--doc/user/scanners.in50
1 files changed, 50 insertions, 0 deletions
diff --git a/doc/user/scanners.in b/doc/user/scanners.in
index 1c7ee7e..db3170a 100644
--- a/doc/user/scanners.in
+++ b/doc/user/scanners.in
@@ -329,3 +329,53 @@ 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>
+
+ <scons_example name="findpathdirs">
+ <file name="SConstruct" printme="1">
+ kscan = Scanner(function = kfile_scan,
+ skeys = ['.k'],
+ path=FindPathDirs('KPATH'))
+ </file>
+ </scons_example>
+
+ <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>