diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/user/scanners.in | 50 | ||||
-rw-r--r-- | doc/user/scanners.xml | 48 |
2 files changed, 98 insertions, 0 deletions
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> |