From e0415bbb6c282ad3ae05754c1a98265051b9e2ae Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 3 Dec 2021 08:26:21 -0700 Subject: Update Scanners chapter in User Guide [skip appveyor] Just adds a bit more polish, better use of markup, etc. Functionally unchanged. Doc-only change. Signed-off-by: Mats Wichmann --- doc/user/scanners.xml | 126 ++++++++++++++++++++++++++------------------------ 1 file changed, 66 insertions(+), 60 deletions(-) diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml index 522bfb6..b9a5084 100644 --- a/doc/user/scanners.xml +++ b/doc/user/scanners.xml @@ -147,7 +147,8 @@ over the file scanning rather than being called for each input line: &SCons; has built-in scanners that know how to look in - C, Fortran and IDL source files for information about + C/C++, Fortran, D, IDL, LaTeX, Python and SWIG source files + for information about other files that targets built from those files depend on--for example, in the case of files that use the C preprocessor, the .h files that are specified @@ -203,8 +204,8 @@ def kfile_scan(node, env, path, arg): have to return a list of File nodes from the scanner function, simple strings for the file names won't do. As in the examples we are showing here, you can use the &File; - function of your current Environment in order to create nodes on the fly from - a sequence of file names with relative paths. + function of your current &consenv; in order to create nodes + on the fly from a sequence of file names with relative paths. @@ -246,9 +247,9 @@ def kfile_scan(node, env, path, arg): - The construction environment in effect for this scan. - The scanner function may choose to use construction - variables from this environment to affect its behavior. + The &consenv; in effect for this scan. + The scanner function may choose to use &consvars; + from this environment to affect its behavior. @@ -287,19 +288,18 @@ def kfile_scan(node, env, path, arg): - A Scanner object is created using the &Scanner; function, - which typically takes an skeys argument - to associate the type of file suffix with this scanner. + A Scanner object is created using the &f-link-Scanner; function, + which typically takes an skeys argument + to associate a file suffix with this scanner. The Scanner object must then be associated with the - &cv-link-SCANNERS; construction variable of a construction environment, - typically by using the &Append; method: + &cv-link-SCANNERS; &consvar; in the current &consenv;, + typically by using the &f-link-Append; method: -kscan = Scanner(function = kfile_scan, - skeys = ['.k']) -env.Append(SCANNERS = kscan) +kscan = Scanner(function=kfile_scan, skeys=['.k']) +env.Append(SCANNERS=kscan) @@ -310,23 +310,22 @@ env.Append(SCANNERS = kscan) - import re +import re - include_re = re.compile(r'^include\s+(\S+)$', re.M) +include_re = re.compile(r'^include\s+(\S+)$', re.M) - def kfile_scan(node, env, path): - contents = node.get_text_contents() - includes = include_re.findall(contents) - return env.File(includes) +def kfile_scan(node, env, path): + contents = node.get_text_contents() + includes = include_re.findall(contents) + return env.File(includes) - kscan = Scanner(function = kfile_scan, - skeys = ['.k']) +kscan = Scanner(function=kfile_scan, skeys=['.k']) - env = Environment(ENV = {'PATH' : '__ROOT__/usr/local/bin'}) - env.Append(SCANNERS = kscan) +env = Environment(ENV={'PATH': '__ROOT__/usr/local/bin'}) +env.Append(SCANNERS=kscan) - env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') - +env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') + include other_file @@ -369,17 +368,19 @@ cat - 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 path argument. Path variables + If the build tool in question will use a path variable to search + for included files or other dependencies, then the Scanner will + need to take that path variable into account as well - + &cv-link-CPPPATH; and &cv-link-LIBPATH; are used this way, + for example. The path to search is passed to your + scanner as the path 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 + contain &consvars; which need to be expanded. + &SCons; provides the &f-link-FindPathDirs; function which returns + a callable to expand a given path (given as a SCons &consvar; + 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 &cv-link-TARGET; references which differ for each file scanned. @@ -387,26 +388,24 @@ cat 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: + using KPATH as the &consvar; with the search path + (analogous to &cv-link-CPPPATH;), we just modify the call to + the &Scanner; factory function to include a path keyword arg: -kscan = Scanner(function = kfile_scan, - skeys = ['.k'], - path_function = FindPathDirs('KPATH')) +kscan = Scanner(function=kfile_scan, skeys=['.k'], path_function=FindPathDirs('KPATH')) - 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 + &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. @@ -419,34 +418,41 @@ kscan = Scanner(function = kfile_scan, - One approach for the use of scanners is with builders. - There are two optional parameters we can use with a builder - source_scanner and target_scanner. + One approach for introducing scanners into the build is in + conjunction with a Builder. There are two relvant optional + parameters we can use when creating a builder: + source_scanner and + target_scanner. + source_scanner is used for scanning + source files, and target_scanner + is used for scanning the target once it is generated. +import re + +include_re = re.compile(r'^include\s+(\S+)$', re.M) def kfile_scan(node, env, path, arg): contents = node.get_text_contents() return env.File(include_re.findall(contents)) -kscan = Scanner(function = kfile_scan, - skeys = ['.k'], - path_function = FindPathDirs('KPATH')) +kscan = Scanner(function=kfile_scan, skeys=['.k'], path_function=FindPathDirs('KPATH') def build_function(target, source, env): # Code to build "target" from "source" return None -bld = Builder(action = build_function, - suffix = '.foo', - source_scanner = kscan - src_suffix = '.input') -env = Environment(BUILDERS = {'Foo' : bld}) +bld = Builder( + action=build_function, + suffix='.foo', + source_scanner=kscan, + src_suffix='.input', +) +env = Environment(BUILDERS={'Foo': bld}) env.Foo('file') - @@ -457,11 +463,11 @@ env.Foo('file') - + A scanner function will not affect the list of sources or targets seen by the builder during the build action. The scanner function - will however affect if the builder should be rebuilt (if any of + will however affect if the builder should rebuild (if any of the files sourced by the scanner have changed for example). -- cgit v0.12