SConsUtilsEnvironment

class lsst.sconsUtils.installation.SConsUtilsEnvironment(platform=None, tools=None, toolpath=None, variables=None, parse_flags=None, **kw)

Bases: SCons.Script.SConscript.SConsEnvironment

Dummy class to make visible the methods injected into the SCons parent environment.

Methods Summary

Action(*args, **kw)
AddMethod(function[, name])	Adds the specified function as a method of this construction environment with the specified name.
AddPostAction(files, action)
AddPreAction(files, action)
Alias(target[, source, action])
AlwaysBuild(*targets)
Append(**kw)	Append values to construction variables in an Environment.
AppendENVPath(name, newpath[, envname, sep, …])	Append path elements to the path name in the envname dictionary for this environment.
AppendUnique([delete_existing])	Append values to existing construction variables in an Environment, if they’re not already there.
BuildETags([root, fileRegex, ignoreDirs])	Build Emacs tags (see man etags for more information).
Builder(**kw)
CacheDir(path[, custom_class])
Clean(targets, files)
CleanTree(filePatterns[, dirPatterns, …])	Remove files matching the argument list starting at directory when scons is invoked with -c/–clean and no explicit targets are listed.
Clone([tools, toolpath, parse_flags])	Return a copy of a construction Environment.
Command(target, source, action, **kw)	Builds the supplied target files from the supplied source files using the supplied action.
Configure(*args, **kw)
Decider(function)
Declare([products])	Create current and declare targets for products.
Default(*targets)
Depends(target, dependency)	Explicity specify that ‘target’s depend on ‘dependency’.
Detect(progs)	Return the first available program from one or more possibilities.
Dictionary(*args)	Return construction variables from an environment.
Dir(name, *args, **kw)
Doxygen(config, **kwargs)	Generate a Doxygen config file and run Doxygen on it.
Dump([key, format])	Return construction variables serialized to a string.
EnsurePythonVersion(major, minor)	Exit abnormally if the Python version is not late enough.
EnsureSConsVersion(major, minor[, revision])	Exit abnormally if the SCons version is not late enough.
Entry(name, *args, **kw)
Environment(**kw)
Execute(action, *args, **kw)	Directly execute an action through an Environment
Exit([value])
Export(*vars, **kw)
File(name, *args, **kw)
FindFile(file, dirs)
FindInstalledFiles()	returns the list of all targets of the Install and InstallAs Builder.
FindIxes(paths, prefix, suffix)	Search a list of paths for something that matches the prefix and suffix.
FindSourceFiles([node])	returns a list of all source files.
Flatten(sequence)
GetBuildPath(files)
GetLaunchDir()
GetOption(name)
Glob(pattern[, ondisk, source, strings, exclude])
Help(text[, append])
Ignore(target, dependency)	Ignore a dependency.
Import(*vars)
InstallDir(prefix, dir[, ignoreRegex, recursive])	Install the directory dir into prefix, ignoring certain files.
InstallEups(dest[, files, presetup])	Install a ups directory, setting absolute versions as appropriate (unless you’re installing from the trunk, in which case no versions are expanded).
InstallLSST(prefix, dirs[, ignoreRegex])	Install directories in the usual LSST way, handling “ups” specially.
Literal(string)
Local(*targets)
MergeFlags(args[, unique])	Merge flags into construction variables.
NoCache(*targets)	Tags a target so that it will not be cached
NoClean(*targets)	Tags a target so that it will not be cleaned by -c
Override(overrides)	Produce a modified environment whose variables are overridden by the overrides dictionaries.
ParseConfig(command[, function, unique])	Parse the result of running a command to update construction vars.
ParseDepends(filename[, must_exist, only_one])	Parse a mkdep-style file for explicit dependencies.
ParseFlags(*flags)	Return a dict of parsed flags.
Platform(platform)
Precious(*targets)
Prepend(**kw)	Prepend values to construction variables in an Environment.
PrependENVPath(name, newpath[, envname, …])	Prepend path elements to the path name in the envname dictionary for this environment.
PrependUnique([delete_existing])	Prepend values to existing construction variables in an Environment, if they’re not already there.
ProductDir(product)	Return the product directory.
Pseudo(*targets)
PyPackageDir(modulename)
Pybind11LoadableModule(target, source, …)	Like LoadableModule, but don’t insist that all symbols are resolved, and set some pybind11-specific flags.
RemoveMethod(function)	Removes the specified function’s MethodWrapper from the added_methods list, so we don’t re-bind it when making a clone.
Replace(**kw)	Replace existing construction variables in an Environment with new construction variables and/or values.
ReplaceIxes(path, old_prefix, old_suffix, …)	Replace old_prefix with new_prefix and old_suffix with new_suffix.
Repository(*dirs, **kw)
Requires(target, prerequisite)	Specify that ‘prerequisite’ must be built before ‘target’, (but ‘target’ does not actually depend on ‘prerequisite’ and need not be rebuilt if it changes).
SConscript(*ls, **kw)	Execute SCons configuration files.
SConscriptChdir(flag)
SConsignFile([name, dbm_module])
Scanner(*args, **kw)
SetDefault(**kw)
SetOption(name, value)
SharedLibraryIncomplete(target, source, …)	Like SharedLibrary, but don’t insist that all symbols are resolved.
SideEffect(side_effect, target)	Tell scons that side_effects are built as side effects of building targets.
SourcesForSharedLibrary(files)	Prepare the list of files to be passed to a SharedLibrary constructor.
Split(arg)	This function converts a string or list into a list of strings or Nodes.
Tool(tool[, toolpath])
Value(value[, built_value, name])
VariantDir(variant_dir, src_dir[, duplicate])
VersionModule(filename[, versionString])
WhereIs(prog[, path, pathext, reject])	Find prog in the path.
arg2nodes(args[, node_factory, lookup_list])
backtick(command)	Emulate command substitution.
get(key[, default])	Emulates the get() method of dictionaries.
getLibs([categories])	Get the libraries the package should be linked with.
get_CacheDir()
get_builder(name)	Fetch the builder with the specified name from the environment.
get_factory(factory[, default])	Return a factory function for creating Nodes for this construction environment.
get_scanner(skey)	Find the appropriate scanner given a key (usually a file suffix).
get_src_sig_type()
get_tgt_sig_type()
gvars()
items()	Emulates the items() method of dictionaries.
keys()	Emulates the keys() method of dictionaries.
lvars()
scanner_map_delete([kw])	Delete the cached scanner map (if we need to).
setdefault(key[, default])	Emulates the setdefault() method of dictionaries.
subst(string[, raw, target, source, conv, …])	Recursively interpolates construction variables from the Environment into the specified string, returning the expanded result.
subst_kw(kw[, raw, target, source])
subst_list(string[, raw, target, source, …])	Calls through to SCons.Subst.scons_subst_list().
subst_path(path[, target, source])	Substitute a path list, turning EntryProxies into Nodes and leaving Nodes (and other objects) as-is.
subst_target_source(string[, raw, target, …])	Recursively interpolates construction variables from the Environment into the specified string, returning the expanded result.
validate_CacheDir_class([custom_class])	Validate the passed custom CacheDir class, or if no args are passed, validate the custom CacheDir class from the environment.
values()	Emulates the values() method of dictionaries.

Methods Documentation

Action(*args, **kw)

AddMethod(function, name=None)

Adds the specified function as a method of this construction environment with the specified name. If the name is omitted, the default name is the name of the function itself.

AddPostAction(files, action)

AddPreAction(files, action)

Alias(target, source=[], action=None, **kw)

AlwaysBuild(*targets)

Append(**kw)

Append values to construction variables in an Environment.

The variable is created if it is not already present.

AppendENVPath(name, newpath, envname='ENV', sep=':', delete_existing=False)

Append path elements to the path name in the envname dictionary for this environment. Will only add any particular path once, and will normpath and normcase all paths to help assure this. This can also handle the case where the env variable is a list instead of a string.

If delete_existing is False, a newpath element already in the path will not be moved to the end (it will be left where it is).

AppendUnique(delete_existing=False, **kw)

Append values to existing construction variables in an Environment, if they’re not already there. If delete_existing is True, removes existing values first, so values move to end.

BuildETags(root=None, fileRegex=None, ignoreDirs=None)

Build Emacs tags (see man etags for more information).

Parameters:

env : SCons.Environment

Environment to use to run etags command.

root : str, optional

Directory to begin search.

fileRegex : str

Regular expression to match files.

ignoreDirs : list

List of directories to ignore.

Notes

Files are chosen if they match fileRegex; toplevel directories in list ignoreDirs are ignored. This routine won’t do anything unless you specified a “TAGS” target.

Builder(**kw)

CacheDir(path, custom_class=None)

Clean(targets, files)

CleanTree(filePatterns, dirPatterns='', directory='.', verbose=False)

Remove files matching the argument list starting at directory when scons is invoked with -c/–clean and no explicit targets are listed.

Parameters:

filePatterns : str

Glob to match for files to be deleted.

dirPatterns : str, optional

Specification of directories to be removed.

directory : str, optional

Directory to clean.

verbose : bool, optional

If True print each filename after deleting it.

Notes

Can be run as:

env.CleanTree(r"*~ core")

Clone(tools=[], toolpath=None, parse_flags=None, **kw)

Return a copy of a construction Environment.

The copy is like a Python “deep copy”–that is, independent copies are made recursively of each objects–except that a reference is copied when an object is not deep-copyable (like a function). There are no references to any mutable objects in the original Environment.

Command(target, source, action, **kw)

Builds the supplied target files from the supplied source files using the supplied action. Action may be any type that the Builder constructor will accept for an action.

Configure(*args, **kw)

Decider(function)

Declare(products=None)

Create current and declare targets for products.

Parameters:

products : list of tuple, optional

A list of (product, version) tuples. If product is None it’s taken to be self['eupsProduct']; if version is None it’s taken to be self['version'].

Returns:

acts : list

Commands to execute.

Default(*targets)

Depends(target, dependency)

Explicity specify that ‘target’s depend on ‘dependency’.

Detect(progs)

Return the first available program from one or more possibilities.

Args:

progs (str or list): one or more command names to check for

Dictionary(*args)

Return construction variables from an environment.

Args:

*args (optional): variable names to look up

Returns:

If args omitted, the dictionary of all construction variables. If one arg, the corresponding value is returned. If more than one arg, a list of values is returned.

Raises:

KeyError: if any of args is not in the construction environment.

Dir(name, *args, **kw)

Doxygen(config, **kwargs)

Generate a Doxygen config file and run Doxygen on it.

Rather than parse a complete Doxygen config file for SCons sources and targets, this Doxygen builder builds a Doxygen config file, adding INPUT, FILE_PATTERNS, RECURSIVE, EXCLUDE, XX_OUTPUT and GENERATE_XX options (and possibly others) to an existing proto-config file. Generated settings will override those in the proto-config file.

Parameters:

config : str

A Doxygen config file, usually with the extension .conf.in; a new file with the .in removed will be generated and passed to Doxygen. Settings in the original config file will be overridden by those generated by this method.

**kwargs

Keyword arguments.

• inputs : A sequence of folders or files to be passed

  as the INPUT setting for Doxygen. This list will be turned into absolute paths by SCons, so the #folder syntax will work. Otherwise, the list is passed in as-is, but the builder will also examine those directories to find which source files the Doxygen output actually depends on.

• patterns : A sequence of glob patterns for the

  FILE_PATTERNS Doxygen setting. This will be passed directly to Doxygen, but it is also used to determine which source files should be considered dependencies.

• recursive : Whether the inputs should be searched

  recursively (used for the Doxygen RECURSIVE setting).

• outputs : A sequence of output formats which will also

  be used as output directories.

• exclude : A sequence of folders or files (not globs)

  to be ignored by Doxygen (the Doxygen EXCLUDE setting). Hidden directories are automatically ignored.

• includes : A sequence of Doxygen config files to

  include. These will automatically be separated into paths and files to fill in the @INCLUDE_PATH and @INCLUDE settings.

• useTags : A sequence of Doxygen tag files to use. It

  will be assumed that the html directory for each tag file is in an “html” subdirectory in the same directory as the tag file.

• makeTag A string indicating the name of a tag file

  to be generated.

• projectName : Sets the Doxygen PROJECT_NAME setting.
• projectNumber : Sets the Doxygen PROJECT_NUMBER setting.

• excludeSwig : If True (default), looks for SWIG .i files

  in the input directories and adds Python and C++ files generated by SWIG to the list of files to exclude. For this to work, the SWIG-generated filenames must be the default ones (“module.i” generates “module.py” and “moduleLib_wrap.cc”).

Notes

When building documentation from a clean source tree, generated source files (like headers generated with M4) will not be included among the dependencies, because they aren’t present when we walk the input folders. The workaround is just to build the docs after building the source.

Dump(key=None, format='pretty')

Return construction variables serialized to a string.

Args:

key (optional): if None, format the whole dict of variables.

Else format the value of key (Default value = None)

format (str, optional): specify the format to serialize to.

"pretty" generates a pretty-printed string, "json" a JSON-formatted string. (Default value = "pretty")

EnsurePythonVersion(major, minor)

Exit abnormally if the Python version is not late enough.

EnsureSConsVersion(major, minor, revision=0)

Exit abnormally if the SCons version is not late enough.

Entry(name, *args, **kw)

Environment(**kw)

Execute(action, *args, **kw)

Directly execute an action through an Environment

Exit(value=0)

Export(*vars, **kw)

File(name, *args, **kw)

FindFile(file, dirs)

FindInstalledFiles()

returns the list of all targets of the Install and InstallAs Builder.

FindIxes(paths, prefix, suffix)

Search a list of paths for something that matches the prefix and suffix.

Args:

paths: the list of paths or nodes. prefix: construction variable for the prefix. suffix: construction variable for the suffix.

Returns: the matched path or None

FindSourceFiles(node='.')

returns a list of all source files.

Flatten(sequence)

GetBuildPath(files)

GetLaunchDir()

GetOption(name)

Glob(pattern, ondisk=True, source=False, strings=False, exclude=None)

Help(text, append=False)

Ignore(target, dependency)

Ignore a dependency.

Import(*vars)

InstallDir(prefix, dir, ignoreRegex='(~$|\\.pyc$|\\.os?$)', recursive=True)

Install the directory dir into prefix, ignoring certain files.

Parameters:

prefix : str

Prefix to use for installation.

dir : str

Directory to install.

ignoreRegex : str

Regular expression to control whether a file is ignored.

recursive : bool

Recurse into directories?

Returns:

result : bool

Was installation successful?

InstallEups(dest, files=[], presetup='')

Install a ups directory, setting absolute versions as appropriate (unless you’re installing from the trunk, in which case no versions are expanded).

Parameters:

env : SCons.Environment

Environment to use.

dest : str

Destination directory.

files : list, optional

List of files to install. Any build/table files present in ./ups are automatically added to this list.

presetup : dict, optional

A dictionary with keys product names and values the version that should be installed into the table files, overriding eups expandtable’s usual behaviour.

Returns:

acts : list

Commands to execute.

Notes

Sample usage:

env.InstallEups(os.path.join(env['prefix'], "ups"),
                presetup={"sconsUtils" : env['version']})

InstallLSST(prefix, dirs, ignoreRegex=None)

Install directories in the usual LSST way, handling “ups” specially.

Parameters:

prefix : str

Installation prefix.

dirs : list

Directories to install.

ignoreRegex : str

Regular expression for files and directories to ignore.

Returns:

results : list

Commands to execute.

Literal(string)

Local(*targets)

MergeFlags(args, unique=True) → None

Merge flags into construction variables.

Merges the flags from args into this construction environent. If args is not a dict, it is first converted to one with flags distributed into appropriate construction variables. See ParseFlags().

Args:

args: flags to merge unique: merge flags rather than appending (default: True).

When merging, path variables are retained from the front, other construction variables from the end.

NoCache(*targets)

Tags a target so that it will not be cached

NoClean(*targets)

Tags a target so that it will not be cleaned by -c

Override(overrides)

Produce a modified environment whose variables are overridden by the overrides dictionaries. “overrides” is a dictionary that will override the variables of this environment.

This function is much more efficient than Clone() or creating a new Environment because it doesn’t copy the construction environment dictionary, it just wraps the underlying construction environment, and doesn’t even create a wrapper object if there are no overrides.

ParseConfig(command, function=None, unique=True)

Parse the result of running a command to update construction vars.

Use function to parse the output of running command in order to modify the current environment.

Args:

command: a string or a list of strings representing a command

and its arguments.

function: called to process the result of command, which will

be passed as args. If function is omitted or None, MergeFlags() is used. Takes 3 args (env, args, unique)

unique: whether no duplicate values are allowed (default true)

ParseDepends(filename, must_exist=None, only_one=False)

Parse a mkdep-style file for explicit dependencies. This is completely abusable, and should be unnecessary in the “normal” case of proper SCons configuration, but it may help make the transition from a Make hierarchy easier for some people to swallow. It can also be genuinely useful when using a tool that can write a .d file, but for which writing a scanner would be too complicated.

ParseFlags(*flags) → dict

Return a dict of parsed flags.

Parse flags and return a dict with the flags distributed into the appropriate construction variable names. The flags are treated as a typical set of command-line flags for a GNU-style toolchain, such as might have been generated by one of the {foo}-config scripts, and used to populate the entries based on knowledge embedded in this method - the choices are not expected to be portable to other toolchains.

If one of the flags strings begins with a bang (exclamation mark), it is assumed to be a command and the rest of the string is executed; the result of that evaluation is then added to the dict.

Platform(platform)

Precious(*targets)

Prepend(**kw)

Prepend values to construction variables in an Environment.

The variable is created if it is not already present.

PrependENVPath(name, newpath, envname='ENV', sep=':', delete_existing=True)

Prepend path elements to the path name in the envname dictionary for this environment. Will only add any particular path once, and will normpath and normcase all paths to help assure this. This can also handle the case where the env variable is a list instead of a string.

If delete_existing is False, a newpath component already in the path will not be moved to the front (it will be left where it is).

PrependUnique(delete_existing=False, **kw)

Prepend values to existing construction variables in an Environment, if they’re not already there. If delete_existing is True, removes existing values first, so values move to front.

ProductDir(product)

Return the product directory.

Parameters:

product : str

The EUPS product name.

Returns:

dir : str

The product directory. None if the product is not known.

Pseudo(*targets)

PyPackageDir(modulename)

Pybind11LoadableModule(target, source, **keywords)

Like LoadableModule, but don’t insist that all symbols are resolved, and set some pybind11-specific flags.

RemoveMethod(function)

Removes the specified function’s MethodWrapper from the added_methods list, so we don’t re-bind it when making a clone.

Replace(**kw)

Replace existing construction variables in an Environment with new construction variables and/or values.

ReplaceIxes(path, old_prefix, old_suffix, new_prefix, new_suffix)

Replace old_prefix with new_prefix and old_suffix with new_suffix.

env - Environment used to interpolate variables. path - the path that will be modified. old_prefix - construction variable for the old prefix. old_suffix - construction variable for the old suffix. new_prefix - construction variable for the new prefix. new_suffix - construction variable for the new suffix.

Repository(*dirs, **kw)

Requires(target, prerequisite)

Specify that ‘prerequisite’ must be built before ‘target’, (but ‘target’ does not actually depend on ‘prerequisite’ and need not be rebuilt if it changes).

SConscript(*ls, **kw)

Execute SCons configuration files.

Parameters:

*ls (str or list): configuration file(s) to execute.

Keyword arguments:

dirs (list): execute SConscript in each listed directory. name (str): execute script ‘name’ (used only with ‘dirs’). exports (list or dict): locally export variables the

called script(s) can import.

variant_dir (str): mirror sources needed for the build in

a variant directory to allow building in it.

duplicate (bool): physically duplicate sources instead of just

adjusting paths of derived files (used only with ‘variant_dir’) (default is True).

must_exist (bool): fail if a requested script is missing

(default is False, default is deprecated).

Returns:

list of variables returned by the called script

Raises:

UserError: a script is not found and such exceptions are enabled.

SConscriptChdir(flag)

SConsignFile(name='.sconsign', dbm_module=None)

Scanner(*args, **kw)

SetDefault(**kw)

SetOption(name, value)

SharedLibraryIncomplete(target, source, **keywords)

Like SharedLibrary, but don’t insist that all symbols are resolved.

SideEffect(side_effect, target)

Tell scons that side_effects are built as side effects of building targets.

SourcesForSharedLibrary(files)

Prepare the list of files to be passed to a SharedLibrary constructor.

Parameters:

files

List of files to be processed.

Returns:

objs : list

Object files.

Notes

In particular, ensure that any files listed in env.NoOptFiles (set by the command line option noOptFile="file1 file2") are built without optimisation and files listed in env.optFiles are built with optimisation.

The usage pattern in an SConscript file is:

ccFiles = env.SourcesForSharedLibrary(Glob("../src/*/*.cc"))
env.SharedLibrary('afw', ccFiles, LIBS=env.getLibs("self")))

This is automatically used by lsst.sconsUtils.scripts.BasicSConscript.lib().

Split(arg)

This function converts a string or list into a list of strings or Nodes. This makes things easier for users by allowing files to be specified as a white-space separated list to be split.

The input rules are:

• A single string containing names separated by spaces. These will be split apart at the spaces.
• A single Node instance
• A list containing either strings or Node instances. Any strings in the list are not split at spaces.

In all cases, the function returns a list of Nodes and strings.

Tool(tool, toolpath=None, **kwargs) → SCons.Tool.Tool

Value(value, built_value=None, name=None)

VariantDir(variant_dir, src_dir, duplicate=1)

VersionModule(filename, versionString=None)

WhereIs(prog, path=None, pathext=None, reject=None)

Find prog in the path.

arg2nodes(args, node_factory=<class 'SCons.Environment._Null'>, lookup_list=<class 'SCons.Environment._Null'>, **kw)

backtick(command) → str

Emulate command substitution.

Provides behavior conceptually like POSIX Shell notation for running a command in backquotes (backticks) by running command and returning the resulting output string.

This is not really a public API any longer, it is provided for the use of ParseFlags() (which supports it using a syntax of !command) and ParseConfig().

Raises:

OSError: if the external command returned non-zero exit status.

get(key, default=None)

Emulates the get() method of dictionaries.

getLibs(categories='main')

Get the libraries the package should be linked with.

Parameters:

categories : str

A string containing whitespace-delimited categories. Standard categories are “main”, “python”, and “test”. Default is “main”. A special virtual category “self” can be provided, returning the results of targets=”main” with the env["packageName"] removed.

Returns:

libs : list

Libraries to use.

Notes

Typically, main libraries will be linked with LIBS=getLibs("self"), Python modules will be linked with LIBS=getLibs("main python") and C++-coded test programs will be linked with LIBS=getLibs("main test").

get_CacheDir()

get_builder(name)

Fetch the builder with the specified name from the environment.

get_factory(factory, default='File')

Return a factory function for creating Nodes for this construction environment.

get_scanner(skey)

Find the appropriate scanner given a key (usually a file suffix).

get_src_sig_type()

get_tgt_sig_type()

gvars()

items()

Emulates the items() method of dictionaries.

keys()

Emulates the keys() method of dictionaries.

lvars()

scanner_map_delete(kw=None)

Delete the cached scanner map (if we need to).

setdefault(key, default=None)

Emulates the setdefault() method of dictionaries.

subst(string, raw=0, target=None, source=None, conv=None, executor=None)

Recursively interpolates construction variables from the Environment into the specified string, returning the expanded result. Construction variables are specified by a $ prefix in the string and begin with an initial underscore or alphabetic character followed by any number of underscores or alphanumeric characters. The construction variable names may be surrounded by curly braces to separate the name from trailing characters.

subst_kw(kw, raw=0, target=None, source=None)

subst_list(string, raw=0, target=None, source=None, conv=None, executor=None)

Calls through to SCons.Subst.scons_subst_list(). See the documentation for that function.

subst_path(path, target=None, source=None)

Substitute a path list, turning EntryProxies into Nodes and leaving Nodes (and other objects) as-is.

subst_target_source(string, raw=0, target=None, source=None, conv=None, executor=None)

Recursively interpolates construction variables from the Environment into the specified string, returning the expanded result. Construction variables are specified by a $ prefix in the string and begin with an initial underscore or alphabetic character followed by any number of underscores or alphanumeric characters. The construction variable names may be surrounded by curly braces to separate the name from trailing characters.

validate_CacheDir_class(custom_class=None)

Validate the passed custom CacheDir class, or if no args are passed, validate the custom CacheDir class from the environment.

values()

Emulates the values() method of dictionaries.