SCons.Scanner package

Submodules

SCons.Scanner.C module

Dependency scanner for C/C++ code.

SCons.Scanner.C.CConditionalScanner()

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()

Return a prototype Scanner instance for scanning source files that use the C pre-processor

class SCons.Scanner.C.SConsCPPConditionalScanner(*args, **kwargs)

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.

_do_if_else_condition(condition)

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)

do_define(t)

Default handling of a #define line.

do_elif(t)

Default handling of a #elif line.

do_else(t)

Default handling of a #else line.

do_endif(t)

Default handling of a #endif line.

do_if(t)

Default handling of a #if line.

do_ifdef(t)

Default handling of a #ifdef line.

do_ifndef(t)

Default handling of a #ifndef line.

do_import(t)

Default handling of a #import line.

do_include(t)

Default handling of a #include line.

do_include_next(t)

Default handling of a #include line.

do_nothing(t)

Null method for when we explicitly want the action for a specific preprocessor directive to do nothing.

do_undef(t)

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)

find_include_file(t)

Finds the #include file for a given preprocessor tuple.

initialize_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.

read_file(file)

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()

Pops the previous dispatch table off the stack and makes it the current one.

save()

Pushes the current dispatch table on the stack and re-initializes the current dispatch table to the default.

scons_current_file(t)

start_handling_includes(t=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)

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)

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.

recurse_nodes(nodes)

select(node)

class SCons.Scanner.C.SConsCPPScanner(*args, **kwargs)

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.

_do_if_else_condition(condition)

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)

do_define(t)

Default handling of a #define line.

do_elif(t)

Default handling of a #elif line.

do_else(t)

Default handling of a #else line.

do_endif(t)

Default handling of a #endif line.

do_if(t)

Default handling of a #if line.

do_ifdef(t)

Default handling of a #ifdef line.

do_ifndef(t)

Default handling of a #ifndef line.

do_import(t)

Default handling of a #import line.

do_include(t)

Default handling of a #include line.

do_include_next(t)

Default handling of a #include line.

do_nothing(t)

Null method for when we explicitly want the action for a specific preprocessor directive to do nothing.

do_undef(t)

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)

find_include_file(t)

Finds the #include file for a given preprocessor tuple.

initialize_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.

read_file(file)

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()

Pops the previous dispatch table off the stack and makes it the current one.

save()

Pushes the current dispatch table on the stack and re-initializes the current dispatch table to the default.

scons_current_file(t)

start_handling_includes(t=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)

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)

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.

recurse_nodes(nodes)

select(node)

SCons.Scanner.C.dictify_CPPDEFINES(env) → dict

Returns CPPDEFINES converted to a dict.

SCons.Scanner.D module

Scanner for the Digital Mars “D” programming language.

Coded by Andy Friesen, 17 Nov 2003

class SCons.Scanner.D.D

Bases: Classic

static _recurse_all_nodes(nodes)

static _recurse_no_nodes(nodes)

add_scanner(skey, scanner)

add_skey(skey)

Add a skey to the list of skeys

find_include(include, source_dir, path)

find_include_names(node)

get_skeys(env=None)

path(env, dir=None, target=None, source=None)

scan(node, path=())

select(node)

static sort_key(include)

SCons.Scanner.D.DScanner()

Return a prototype Scanner instance for scanning D source files

SCons.Scanner.Dir module

SCons.Scanner.Dir.DirEntryScanner(**kwargs)

Return a prototype Scanner instance for “scanning” directory Nodes for their in-memory entries

SCons.Scanner.Dir.DirScanner(**kwargs)

Return a prototype Scanner instance for scanning directories for on-disk files

SCons.Scanner.Dir.do_not_scan(k)

SCons.Scanner.Dir.only_dirs(nodes)

SCons.Scanner.Dir.scan_in_memory(node, env, path=())

“Scans” a Node.FS.Dir for its in-memory entries.

SCons.Scanner.Dir.scan_on_disk(node, env, path=())

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)

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.

static _recurse_all_nodes(nodes)

static _recurse_no_nodes(nodes)

add_scanner(skey, scanner)

add_skey(skey)

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)

scan(node, env, path=())

select(node)

static sort_key(include)

SCons.Scanner.Fortran.FortranScan(path_variable='FORTRANPATH')

Return a prototype Scanner instance for scanning source files for Fortran USE & INCLUDE statements

SCons.Scanner.IDL module

Dependency scanner for IDL (Interface Definition Language) files.

SCons.Scanner.IDL.IDLScan()

Return a prototype Scanner instance for scanning IDL source files

SCons.Scanner.LaTeX module

Dependency scanner for LaTeX code.

class SCons.Scanner.LaTeX.FindENVPathDirs(variable)

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)

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{}

_latex_names(include_type, filename)

static _recurse_all_nodes(nodes)

static _recurse_no_nodes(nodes)

add_scanner(skey, scanner)

add_skey(skey)

Add a skey to the list of skeys

canonical_text(text)

Standardize an input TeX-file contents.

Currently:

• removes comments, unwrapping comment-wrapped lines.

env_variables = ['TEXINPUTS', 'BIBINPUTS', 'BSTINPUTS', 'INDEXSTYLE']

find_include(include, source_dir, path)

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(node, subdir='.')

scan_recurse(node, path=())

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)

sort_key(include)

two_arg_commands = ['import', 'subimport', 'includefrom', 'subincludefrom', 'inputfrom', 'subinputfrom']

SCons.Scanner.LaTeX.LaTeXScanner()

Return a prototype Scanner instance for scanning LaTeX source files when built with latex.

SCons.Scanner.LaTeX.PDFLaTeXScanner()

Return a prototype Scanner instance for scanning LaTeX source files when built with pdflatex.

class SCons.Scanner.LaTeX._Null

Bases: object

SCons.Scanner.LaTeX._null

alias of _Null

SCons.Scanner.LaTeX.modify_env_var(env, var, abspath)

SCons.Scanner.Prog module

Dependency scanner for program files.

SCons.Scanner.Prog.ProgramScanner(**kwargs)

Return a prototype Scanner instance for scanning executable files for static-lib dependencies

SCons.Scanner.Prog._subst_libs(env, libs)

Substitute environment variables and split into list.

SCons.Scanner.Prog.scan(node, env, libpath=())

Scans program files for static-library dependencies.

It will search the LIBPATH environment variable for libraries specified in the LIBS variable, returning any files it finds as dependencies.

SCons.Scanner.RC module

Dependency scanner for RC (Interface Definition Language) files.

SCons.Scanner.RC.RCScan()

Return a prototype Scanner instance for scanning RC source files

SCons.Scanner.RC.no_tlb(nodes)

Filter out .tlb files as they are binary and shouldn’t be scanned.

SCons.Scanner.SWIG module

Dependency scanner for SWIG code.

SCons.Scanner.SWIG.SWIGScanner()

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)

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() and sort_key1() methods), the regular expression passed to the constructor must return the name of the include file in group 0.

static _recurse_all_nodes(nodes)

static _recurse_no_nodes(nodes)

add_scanner(skey, scanner)

add_skey(skey)

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)

scan(node, path=())

select(node)

static sort_key(include)

class SCons.Scanner.ClassicCPP(name, suffixes, path_variable, regex, *args, **kwargs)

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.

static _recurse_all_nodes(nodes)

static _recurse_no_nodes(nodes)

add_scanner(skey, scanner)

add_skey(skey)

Add a skey to the list of skeys

find_include(include, source_dir, path)

find_include_names(node)

get_skeys(env=None)

path(env, dir=None, target=None, source=None)

scan(node, path=())

select(node)

sort_key(include)

class SCons.Scanner.Current(*args, **kwargs)

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).

static _recurse_all_nodes(nodes)

static _recurse_no_nodes(nodes)

add_scanner(skey, scanner)

add_skey(skey)

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)

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)

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='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)

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 is None, 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.

static _recurse_all_nodes(nodes)

static _recurse_no_nodes(nodes)

add_scanner(skey, scanner)

add_skey(skey)

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.Selector(mapping, *args, **kwargs)

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_scanner(skey, scanner)

add_skey(skey)

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._Null

Bases: object

SCons.Scanner._null

alias of _Null