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 ‘ENV’ 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)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])Use the specified function to parse the output of the command in order to modify the current environment. 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 ‘ENV’ 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)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
()has_key
(key)Emulates the has_key() method of dictionaries. 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. 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=0)¶ Append path elements to the path ‘name’ in the ‘ENV’ 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 0, a newpath which is already in the path will not be moved to the end (it will be left where it is).
-
AppendUnique
(delete_existing=0, **kw)¶ Append values to existing construction variables in an Environment, if they’re not already there. If delete_existing is 1, 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: 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)¶
-
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: 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: Returns: - acts :
list
Commands to execute.
- acts :
-
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.
- config :
-
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: Returns: - result :
bool
Was installation successful?
- result :
-
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']})
- env :
-
InstallLSST
(prefix, dirs, ignoreRegex=None)¶ Install directories in the usual LSST way, handling “ups” specially.
Parameters: Returns: - results :
list
Commands to execute.
- results :
-
Literal
(string)¶
-
Local
(*targets)¶
-
MergeFlags
(args, unique=True)¶ Merge flags into construction variables.
Merges the flags from
args
into this construction environent. Ifargs
is not a dict, it is first converted to a dictionary with flags distributed into appropriate construction variables. SeeParseFlags()
.- Args:
- args: flags to merge unique: merge flags rather than appending (default: True)
-
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)¶ Use the specified function to parse the output of the command in order to modify the current environment. The ‘command’ can be a string or a list of strings representing a command and its arguments. ‘Function’ is an optional argument that takes the environment, the output of the command, and the unique flag. If no function is specified, MergeFlags, which treats the output as the result of a typical ‘X-config’ command (i.e. gtk-config), will merge the output into the appropriate variables.
-
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)¶ 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-like 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=1)¶ Prepend path elements to the path ‘name’ in the ‘ENV’ 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 0, a newpath which is already in the path will not be moved to the front (it will be left where it is).
-
PrependUnique
(delete_existing=0, **kw)¶ Prepend values to existing construction variables in an Environment, if they’re not already there. If delete_existing is 1, removes existing values first, so values move to front.
-
ProductDir
(product)¶ Return the product directory.
Parameters: - product :
str
The EUPS product name.
Returns: - product :
-
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)¶
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.
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 optionnoOptFile="file1 file2"
) are built without optimisation and files listed inenv.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, **kw)¶
-
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=[])¶ Find prog in the path.
-
arg2nodes
(args, node_factory=<class 'SCons.Environment._Null'>, lookup_list=<class 'SCons.Environment._Null'>, **kw)¶
-
backtick
(command)¶
-
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 withLIBS=getLibs("main python")
and C++-coded test programs will be linked withLIBS=getLibs("main test")
.- categories :
-
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
()¶
-
has_key
(key)¶ Emulates the has_key() method of dictionaries.
-
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.
-
values
()¶ Emulates the values() method of dictionaries.
-