From a91b87f78c9d854b048dadcf44c7b468dd58108e Mon Sep 17 00:00:00 2001
From: Gary Oberbrunner <garyo@oberbrunner.com>
Date: Fri, 4 Jun 2010 02:16:13 +0000
Subject: Document FindPathDirs in Users Guide

---
 doc/user/scanners.in  | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/user/scanners.xml | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+)

diff --git a/doc/user/scanners.in b/doc/user/scanners.in
index c585230..3743295 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>
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>
-- 
cgit v0.12