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, **kw)

Bases: SCons.cpp.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, **kw)

Bases: SCons.cpp.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)

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: SCons.Scanner.Classic

_recurse_all_nodes(nodes)

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

SCons.Scanner.D.DScanner()

Return a prototype Scanner instance for scanning D source files

SCons.Scanner.Dir module

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

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

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

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, **kw)

Bases: SCons.Scanner.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.

_recurse_all_nodes(nodes)

_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, env, path=())

select(node)

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, **kw)

Bases: SCons.Scanner.Base

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)

_recurse_all_nodes(nodes)

_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 SCons.Scanner.LaTeX._Null

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

SCons.Scanner.Prog module

Dependency scanner for program files.

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

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.

class SCons.Scanner.Base(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.

This implements straightforward, single-pass scanning of a single file.

_recurse_all_nodes(nodes)

_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.Classic(name, suffixes, path_variable, regex, *args, **kw)

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

_recurse_all_nodes(nodes)

_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.ClassicCPP(name, suffixes, path_variable, regex, *args, **kw)

Bases: SCons.Scanner.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.

_recurse_all_nodes(nodes)

_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, **kw)

Bases: SCons.Scanner.Base

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

_recurse_all_nodes(nodes)

_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, **kw)

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 Base 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.Selector(dict, *args, **kw)

Bases: SCons.Scanner.Base

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

_recurse_all_nodes(nodes)

_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 SCons.Scanner._Null