SCons.Scanner package#
Module contents#
The Scanner package for the SCons software construction utility.
- SCons.Scanner.Base#
alias of
ScannerBase
- class SCons.Scanner.Classic(name, suffixes, path_variable, regex, *args, **kwargs)[source]#
Bases:
Current
A Scanner subclass to contain the common logic for classic CPP-style include scanning, but which can be customized to use different regular expressions to find the includes.
Note that in order for this to work “out of the box” (without overriding the
find_include()
andsort_key1()
methods), the regular expression passed to the constructor must return the name of the include file in group 0.- __call__(node, env, path=()) list #
Scans a single object.
- Parameters:
node – the node that will be passed to the scanner function
env – the environment that will be passed to the scanner function.
path – tuple of paths from the path_function
- Returns:
A list of direct dependency nodes for the specified node.
- static _recurse_all_nodes(nodes)#
- static _recurse_no_nodes(nodes)#
- add_scanner(skey, scanner) None #
- add_skey(skey) None #
Add a skey to the list of skeys
- get_skeys(env=None)#
- path(env, dir=None, target=None, source=None)#
- select(node)#
- class SCons.Scanner.ClassicCPP(name, suffixes, path_variable, regex, *args, **kwargs)[source]#
Bases:
Classic
A Classic Scanner subclass which takes into account the type of bracketing used to include the file, and uses classic CPP rules for searching for the files based on the bracketing.
Note that in order for this to work, the regular expression passed to the constructor must return the leading bracket in group 0, and the contained filename in group 1.
- __call__(node, env, path=()) list #
Scans a single object.
- Parameters:
node – the node that will be passed to the scanner function
env – the environment that will be passed to the scanner function.
path – tuple of paths from the path_function
- Returns:
A list of direct dependency nodes for the specified node.
- static _recurse_all_nodes(nodes)#
- static _recurse_no_nodes(nodes)#
- add_scanner(skey, scanner) None #
- add_skey(skey) None #
Add a skey to the list of skeys
- find_include_names(node)#
- get_skeys(env=None)#
- path(env, dir=None, target=None, source=None)#
- scan(node, path=())#
- select(node)#
- class SCons.Scanner.Current(*args, **kwargs)[source]#
Bases:
ScannerBase
A class for scanning files that are source files (have no builder) or are derived files and are current (which implies that they exist, either locally or in a repository).
- __call__(node, env, path=()) list #
Scans a single object.
- Parameters:
node – the node that will be passed to the scanner function
env – the environment that will be passed to the scanner function.
path – tuple of paths from the path_function
- Returns:
A list of direct dependency nodes for the specified node.
- static _recurse_all_nodes(nodes)#
- static _recurse_no_nodes(nodes)#
- add_scanner(skey, scanner) None #
- add_skey(skey) None #
Add a skey to the list of skeys
- get_skeys(env=None)#
- path(env, dir=None, target=None, source=None)#
- select(node)#
- class SCons.Scanner.FindPathDirs(variable)[source]#
Bases:
object
Class to bind a specific E{*}PATH variable name to a function that will return all of the E{*}path directories.
- SCons.Scanner.Scanner(function, *args, **kwargs)[source]#
Factory function to create a Scanner Object.
Creates the appropriate Scanner based on the type of “function”.
TODO: Deprecate this some day. We’ve moved the functionality inside the ScannerBase class and really don’t need this factory function any more. It was, however, used by some of our Tool modules, so the call probably ended up in various people’s custom modules patterned on SCons code.
- class SCons.Scanner.ScannerBase(function, name: str = 'NONE', argument=<class 'SCons.Scanner._Null'>, skeys=<class 'SCons.Scanner._Null'>, path_function=None, node_class=<class 'SCons.Node.FS.Base'>, node_factory=None, scan_check=None, recursive=None)[source]#
Bases:
object
Base class for dependency scanners.
Implements straightforward, single-pass scanning of a single file.
A Scanner is usually set up with a scanner function (and optionally a path function), but can also be a kind of dispatcher which passes control to other Scanners.
A scanner function takes three arguments: a Node to scan for dependecies, the construction environment to use, and an optional tuple of paths (as generated by the optional path function). It must return a list containing the Nodes for all the direct dependencies of the file.
The optional path function is called to return paths that can be searched for implicit dependency files. It takes five arguments: a construction environment, a Node for the directory containing the SConscript file that defined the primary target, a list of target nodes, a list of source nodes, and the optional argument for this instance.
Examples:
s = Scanner(my_scanner_function) s = Scanner(function=my_scanner_function) s = Scanner(function=my_scanner_function, argument='foo')
- Parameters:
function – either a scanner function taking two or three arguments and returning a list of File Nodes; or a mapping of keys to other Scanner objects.
name – an optional name for identifying this scanner object (defaults to “NONE”).
argument – an optional argument that will be passed to both function and path_function.
skeys – an optional list argument that can be used to determine if this scanner can be used for a given Node. In the case of File nodes, for example, the skeys would be file suffixes.
path_function – an optional function which returns a tuple of the directories that can be searched for implicit dependency files. May also return a callable which is called with no args and returns the tuple (supporting Bindable class).
node_class – optional class of Nodes which this scan will return. If not specified, defaults to
SCons.Node.FS.Base
. If node_class isNone
, then this scanner will not enforce any Node conversion and will return the raw results from function.node_factory – optional factory function to be called to translate the raw results returned by function into the expected node_class objects.
scan_check – optional function to be called to first check whether this node really needs to be scanned.
recursive – optional specifier of whether this scanner should be invoked recursively on all of the implicit dependencies it returns (for example #include lines in C source files, which may refer to header files which should themselves be scanned). May be a callable, which will be called to filter the list of nodes found to select a subset for recursive scanning (the canonical example being only recursively scanning subdirectories within a directory). The default is to not do recursive scanning.
- __call__(node, env, path=()) list [source]#
Scans a single object.
- Parameters:
node – the node that will be passed to the scanner function
env – the environment that will be passed to the scanner function.
path – tuple of paths from the path_function
- Returns:
A list of direct dependency nodes for the specified node.
- class SCons.Scanner.Selector(mapping, *args, **kwargs)[source]#
Bases:
ScannerBase
A class for selecting a more specific scanner based on the
scanner_key()
(suffix) for a specific Node.TODO: This functionality has been moved into the inner workings of the ScannerBase class, and this class will be deprecated at some point. (It was never exposed directly as part of the public interface, although it is used by the
Scanner()
factory function that was used by various Tool modules and therefore was likely a template for custom modules that may be out there.)- static _recurse_all_nodes(nodes)#
- static _recurse_no_nodes(nodes)#
- add_skey(skey) None #
Add a skey to the list of skeys
- get_skeys(env=None)#
- path(env, dir=None, target=None, source=None)#
Submodules#
SCons.Scanner.C module#
Dependency scanner for C/C++ code.
Two scanners are defined here: the default CScanner, and the optional CConditionalScanner, which must be explicitly selected by calling add_scanner() for each affected suffix.
- SCons.Scanner.C.CConditionalScanner()[source]#
Return an advanced conditional Scanner instance for scanning source files
Interprets C/C++ Preprocessor conditional syntax (#ifdef, #if, defined, #else, #elif, etc.).
- SCons.Scanner.C.CScanner()[source]#
Return a prototype Scanner instance for scanning source files that use the C pre-processor
- class SCons.Scanner.C.SConsCPPConditionalScanner(*args, **kwargs)[source]#
Bases:
PreProcessor
SCons-specific subclass of the cpp.py module’s processing.
We subclass this so that: 1) we can deal with files represented by Nodes, not strings; 2) we can keep track of the files that are missing.
- __call__(file)#
Pre-processes a file.
This is the main public entry point.
- _do_if_else_condition(condition) None #
Common logic for evaluating the conditions on #if, #ifdef and #ifndef lines.
- _match_tuples(tuples)#
- _parse_tuples(contents)#
- _process_tuples(tuples, file=None)#
- all_include(t) None #
- do_define(t) None #
Default handling of a #define line.
- do_elif(t) None #
Default handling of a #elif line.
- do_else(t) None #
Default handling of a #else line.
- do_endif(t) None #
Default handling of a #endif line.
- do_if(t) None #
Default handling of a #if line.
- do_ifdef(t) None #
Default handling of a #ifdef line.
- do_ifndef(t) None #
Default handling of a #ifndef line.
- do_import(t) None #
Default handling of a #import line.
- do_include(t) None #
Default handling of a #include line.
- do_include_next(t) None #
Default handling of a #include line.
- do_nothing(t) None #
Null method for when we explicitly want the action for a specific preprocessor directive to do nothing.
- do_undef(t) None #
Default handling of a #undef line.
- eval_expression(t)#
Evaluates a C preprocessor expression.
This is done by converting it to a Python equivalent and eval()ing it in the C preprocessor namespace we use to track #define values.
- finalize_result(fname)#
- process_contents(contents)#
Pre-processes a file contents.
Is used by tests
- process_file(file)#
Pre-processes a file.
This is the main internal entry point.
- resolve_include(t)#
Resolve a tuple-ized #include line.
This handles recursive expansion of values without “” or <> surrounding the name until an initial “ or < is found, to handle #include FILE where FILE is a #define somewhere else.
- restore() None #
Pops the previous dispatch table off the stack and makes it the current one.
- save() None #
Pushes the current dispatch table on the stack and re-initializes the current dispatch table to the default.
- scons_current_file(t) None #
- start_handling_includes(t=None) None #
Causes the PreProcessor object to start processing #import, #include and #include_next lines.
This method will be called when a #if, #ifdef, #ifndef or #elif evaluates True, or when we reach the #else in a #if, #ifdef, #ifndef or #elif block where a condition already evaluated False.
- stop_handling_includes(t=None) None #
Causes the PreProcessor object to stop processing #import, #include and #include_next lines.
This method will be called when a #if, #ifdef, #ifndef or #elif evaluates False, or when we reach the #else in a #if, #ifdef, #ifndef or #elif block where a condition already evaluated True.
- tupleize(contents)#
Turns the contents of a file into a list of easily-processed tuples describing the CPP lines in the file.
The first element of each tuple is the line’s preprocessor directive (#if, #include, #define, etc., minus the initial ‘#’). The remaining elements are specific to the type of directive, as pulled apart by the regular expression.
- class SCons.Scanner.C.SConsCPPConditionalScannerWrapper(name, variable)[source]#
Bases:
object
The SCons wrapper around a cpp.py scanner.
This is the actual glue between the calling conventions of generic SCons scanners, and the (subclass of) cpp.py class that knows how to look for #include lines with reasonably real C-preprocessor-like evaluation of #if/#ifdef/#else/#elif lines.
- class SCons.Scanner.C.SConsCPPScanner(*args, **kwargs)[source]#
Bases:
PreProcessor
SCons-specific subclass of the cpp.py module’s processing.
We subclass this so that: 1) we can deal with files represented by Nodes, not strings; 2) we can keep track of the files that are missing.
- __call__(file)#
Pre-processes a file.
This is the main public entry point.
- _do_if_else_condition(condition) None #
Common logic for evaluating the conditions on #if, #ifdef and #ifndef lines.
- _match_tuples(tuples)#
- _parse_tuples(contents)#
- _process_tuples(tuples, file=None)#
- all_include(t) None #
- do_define(t) None #
Default handling of a #define line.
- do_elif(t) None #
Default handling of a #elif line.
- do_else(t) None #
Default handling of a #else line.
- do_endif(t) None #
Default handling of a #endif line.
- do_if(t) None #
Default handling of a #if line.
- do_ifdef(t) None #
Default handling of a #ifdef line.
- do_ifndef(t) None #
Default handling of a #ifndef line.
- do_import(t) None #
Default handling of a #import line.
- do_include(t) None #
Default handling of a #include line.
- do_include_next(t) None #
Default handling of a #include line.
- do_nothing(t) None #
Null method for when we explicitly want the action for a specific preprocessor directive to do nothing.
- do_undef(t) None #
Default handling of a #undef line.
- eval_expression(t)#
Evaluates a C preprocessor expression.
This is done by converting it to a Python equivalent and eval()ing it in the C preprocessor namespace we use to track #define values.
- process_contents(contents)#
Pre-processes a file contents.
Is used by tests
- process_file(file)#
Pre-processes a file.
This is the main internal entry point.
- resolve_include(t)#
Resolve a tuple-ized #include line.
This handles recursive expansion of values without “” or <> surrounding the name until an initial “ or < is found, to handle #include FILE where FILE is a #define somewhere else.
- restore() None #
Pops the previous dispatch table off the stack and makes it the current one.
- save() None #
Pushes the current dispatch table on the stack and re-initializes the current dispatch table to the default.
- scons_current_file(t) None #
- start_handling_includes(t=None) None #
Causes the PreProcessor object to start processing #import, #include and #include_next lines.
This method will be called when a #if, #ifdef, #ifndef or #elif evaluates True, or when we reach the #else in a #if, #ifdef, #ifndef or #elif block where a condition already evaluated False.
- stop_handling_includes(t=None) None #
Causes the PreProcessor object to stop processing #import, #include and #include_next lines.
This method will be called when a #if, #ifdef, #ifndef or #elif evaluates False, or when we reach the #else in a #if, #ifdef, #ifndef or #elif block where a condition already evaluated True.
- tupleize(contents)#
Turns the contents of a file into a list of easily-processed tuples describing the CPP lines in the file.
The first element of each tuple is the line’s preprocessor directive (#if, #include, #define, etc., minus the initial ‘#’). The remaining elements are specific to the type of directive, as pulled apart by the regular expression.
- class SCons.Scanner.C.SConsCPPScannerWrapper(name, variable)[source]#
Bases:
object
The SCons wrapper around a cpp.py scanner.
This is the actual glue between the calling conventions of generic SCons scanners, and the (subclass of) cpp.py class that knows how to look for #include lines with reasonably real C-preprocessor-like evaluation of #if/#ifdef/#else/#elif lines.
- SCons.Scanner.C.dictify_CPPDEFINES(env) dict [source]#
Returns CPPDEFINES converted to a dict.
This should be similar to
processDefines()
. Unfortunately, we can’t do the simple thing of calling that routine and passing the result to the dict() constructor, because it turns the defines into a list of “name=value” pairs, which the dict constructor won’t consume correctly. Also cannot just call dict on CPPDEFINES itself - it’s fine if it’s stored in the converted form (currently deque of tuples), but CPPDEFINES could be in other formats too.So we have to do all the work here - keep concepts in sync with
processDefines
.
SCons.Scanner.D module#
Scanner for the Digital Mars “D” programming language.
Coded by Andy Friesen, 17 Nov 2003
- class SCons.Scanner.D.D[source]#
Bases:
Classic
- __call__(node, env, path=()) list #
Scans a single object.
- Parameters:
node – the node that will be passed to the scanner function
env – the environment that will be passed to the scanner function.
path – tuple of paths from the path_function
- Returns:
A list of direct dependency nodes for the specified node.
- static _recurse_all_nodes(nodes)#
- static _recurse_no_nodes(nodes)#
- add_scanner(skey, scanner) None #
- add_skey(skey) None #
Add a skey to the list of skeys
- get_skeys(env=None)#
- path(env, dir=None, target=None, source=None)#
- scan(node, path=())#
- select(node)#
- static sort_key(include)#
SCons.Scanner.Dir module#
- SCons.Scanner.Dir.DirEntryScanner(**kwargs)[source]#
Return a prototype Scanner instance for “scanning” directory Nodes for their in-memory entries
- SCons.Scanner.Dir.DirScanner(**kwargs)[source]#
Return a prototype Scanner instance for scanning directories for on-disk files
- SCons.Scanner.Dir.do_not_scan(k)#
- SCons.Scanner.Dir.scan_in_memory(node, env, path=())[source]#
“Scans” a Node.FS.Dir for its in-memory entries.
- SCons.Scanner.Dir.scan_on_disk(node, env, path=())[source]#
Scans a directory for on-disk files and directories therein.
Looking up the entries will add these to the in-memory Node tree representation of the file system, so all we have to do is just that and then call the in-memory scanning function.
SCons.Scanner.Fortran module#
Dependency scanner for Fortran code.
- class SCons.Scanner.Fortran.F90Scanner(name, suffixes, path_variable, use_regex, incl_regex, def_regex, *args, **kwargs)[source]#
Bases:
Classic
A Classic Scanner subclass for Fortran source files which takes into account both USE and INCLUDE statements. This scanner will work for both F77 and F90 (and beyond) compilers.
Currently, this scanner assumes that the include files do not contain USE statements. To enable the ability to deal with USE statements in include files, add logic right after the module names are found to loop over each include file, search for and locate each USE statement, and append each module name to the list of dependencies. Caching the search results in a common dictionary somewhere so that the same include file is not searched multiple times would be a smart thing to do.
- __call__(node, env, path=()) list #
Scans a single object.
- Parameters:
node – the node that will be passed to the scanner function
env – the environment that will be passed to the scanner function.
path – tuple of paths from the path_function
- Returns:
A list of direct dependency nodes for the specified node.
- static _recurse_all_nodes(nodes)#
- static _recurse_no_nodes(nodes)#
- add_scanner(skey, scanner) None #
- add_skey(skey) None #
Add a skey to the list of skeys
- static find_include(include, source_dir, path)#
- find_include_names(node)#
- get_skeys(env=None)#
- path(env, dir=None, target=None, source=None)#
- select(node)#
- static sort_key(include)#
SCons.Scanner.IDL module#
Dependency scanner for IDL (Interface Definition Language) files.
SCons.Scanner.Java module#
- SCons.Scanner.Java._subst_paths(env, paths) list [source]#
Return a list of substituted path elements.
If paths is a string, it is split on the search-path separator. Otherwise, substitution is done on string-valued list elements but they are not split.
Note helps support behavior like pulling in the external
CLASSPATH
and setting it directly intoJAVACLASSPATH
, however splitting onos.pathsep
makes the interpretation system-specific (this is warned about in the manpage entry forJAVACLASSPATH
).
- SCons.Scanner.Java.scan(node, env, libpath=()) list [source]#
Scan for files both on JAVACLASSPATH and JAVAPROCESSORPATH.
- JAVACLASSPATH/JAVAPROCESSORPATH path can contain:
Explicit paths to JAR/Zip files
Wildcards (*)
Directories which contain classes in an unnamed package
Parent directories of the root package for classes in a named package
Class path entries that are neither directories nor archives (.zip or JAR files) nor the asterisk (*) wildcard character are ignored.
SCons.Scanner.LaTeX module#
Dependency scanner for LaTeX code.
- class SCons.Scanner.LaTeX.FindENVPathDirs(variable)[source]#
Bases:
object
A class to bind a specific E{*}PATH variable name to a function that will return all of the E{*}path directories.
- class SCons.Scanner.LaTeX.LaTeX(name, suffixes, graphics_extensions, *args, **kwargs)[source]#
Bases:
ScannerBase
Class for scanning LaTeX files for included files.
Unlike most scanners, which use regular expressions that just return the included file name, this returns a tuple consisting of the keyword for the inclusion (“include”, “includegraphics”, “input”, or “bibliography”), and then the file name itself. Based on a quick look at LaTeX documentation, it seems that we should append .tex suffix for the “include” keywords, append .tex if there is no extension for the “input” keyword, and need to add .bib for the “bibliography” keyword that does not accept extensions by itself.
Finally, if there is no extension for an “includegraphics” keyword latex will append .ps or .eps to find the file, while pdftex may use .pdf, .jpg, .tif, .mps, or .png.
The actual subset and search order may be altered by DeclareGraphicsExtensions command. This complication is ignored. The default order corresponds to experimentation with teTeX:
$ latex --version pdfeTeX 3.141592-1.21a-2.2 (Web2C 7.5.4) kpathsea version 3.5.4
- The order is:
[‘.eps’, ‘.ps’] for latex [‘.png’, ‘.pdf’, ‘.jpg’, ‘.tif’].
Another difference is that the search path is determined by the type of the file being searched: env[‘TEXINPUTS’] for “input” and “include” keywords env[‘TEXINPUTS’] for “includegraphics” keyword env[‘TEXINPUTS’] for “lstinputlisting” keyword env[‘BIBINPUTS’] for “bibliography” keyword env[‘BSTINPUTS’] for “bibliographystyle” keyword env[‘INDEXSTYLE’] for “makeindex” keyword, no scanning support needed just allows user to set it if needed.
FIXME: also look for the class or style in document[class|style]{} FIXME: also look for the argument of bibliographystyle{}
- __call__(node, env, path=()) list #
Scans a single object.
- Parameters:
node – the node that will be passed to the scanner function
env – the environment that will be passed to the scanner function.
path – tuple of paths from the path_function
- Returns:
A list of direct dependency nodes for the specified node.
- static _recurse_all_nodes(nodes)#
- static _recurse_no_nodes(nodes)#
- add_scanner(skey, scanner) None #
- add_skey(skey) None #
Add a skey to the list of skeys
- canonical_text(text)[source]#
Standardize an input TeX-file contents.
- Currently:
removes comments, unwrapping comment-wrapped lines.
- env_variables = ['TEXINPUTS', 'BIBINPUTS', 'BSTINPUTS', 'INDEXSTYLE']#
- get_skeys(env=None)#
- keyword_paths = {'addbibresource': 'BIBINPUTS', 'addglobalbib': 'BIBINPUTS', 'addsectionbib': 'BIBINPUTS', 'bibliography': 'BIBINPUTS', 'bibliographystyle': 'BSTINPUTS', 'include': 'TEXINPUTS', 'includegraphics': 'TEXINPUTS', 'input': 'TEXINPUTS', 'lstinputlisting': 'TEXINPUTS', 'makeindex': 'INDEXSTYLE', 'usepackage': 'TEXINPUTS'}#
- path(env, dir=None, target=None, source=None)#
- scan_recurse(node, path=())[source]#
do a recursive scan of the top level target file This lets us search for included files based on the directory of the main file just as latex does
- select(node)#
- two_arg_commands = ['import', 'subimport', 'includefrom', 'subincludefrom', 'inputfrom', 'subinputfrom']#
- SCons.Scanner.LaTeX.LaTeXScanner()[source]#
Return a prototype Scanner instance for scanning LaTeX source files when built with latex.
SCons.Scanner.Prog module#
Dependency scanner for program files.
- SCons.Scanner.Prog.ProgramScanner(**kwargs)[source]#
Return a prototype Scanner instance for scanning executable files for static-lib dependencies
SCons.Scanner.RC module#
Dependency scanner for RC (Interface Definition Language) files.
SCons.Scanner.SWIG module#
Dependency scanner for SWIG code.