SConsUtilsEnvironment¶
- class lsst.sconsUtils.installation.SConsUtilsEnvironment(platform=None, tools=None, toolpath=None, variables=None, parse_flags=None, **kw)¶
Bases:
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)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])Return a list of all source files.
Flatten
(sequence)GetBuildPath
(files)GetOption
(name)Glob
(pattern[, ondisk, source, strings, exclude])Help
(text[, append, keep_local])Update the help text.
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])Find and run tool module tool.
Value
(value[, built_value, name])Return a Value (Python expression) node.
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_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).
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.
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) 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) None ¶
Append values to construction variables in an Environment.
The variable is created if it is not already present.
- AppendENVPath(name, newpath, envname: str = 'ENV', sep=':', delete_existing: bool = False) None ¶
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: bool = False, **kw) None ¶
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:
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)¶
- 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.
- 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 passedas 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 theFILE_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 searchedrecursively (used for the Doxygen RECURSIVE setting).
outputs
A sequence of output formats which will alsobe 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 toinclude. 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. Itwill 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 fileto be generated.
projectName
: Sets the Doxygen PROJECT_NAME setting.projectNumber
: Sets the Doxygen PROJECT_NUMBER setting.excludeSwig
If True (default), looks for SWIG .i filesin 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”).
- config
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: str = '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"
)
- static EnsurePythonVersion(major, minor) None ¶
Exit abnormally if the Python version is not late enough.
- static EnsureSConsVersion(major, minor, revision: int = 0) None ¶
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
- 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
- Flatten(sequence)¶
- GetBuildPath(files)¶
- static GetLaunchDir()¶
- GetOption(name)¶
- Help(text, append: bool = False, keep_local: bool = False) None ¶
Update the help text.
The previous help text has text appended to it, except on the first call. On first call, the values of append and keep_local are considered to determine what is appended to.
- Arguments:
text: string to add to the help text. append: on first call, if true, keep the existing help text
(default False).
- keep_local: on first call, if true and append is also true,
keep only the help text from AddOption calls.
Changed in version 4.6.0: The keep_local parameter was added.
- 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.
- 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.
- env
- Returns:
- acts
list
Commands to execute.
- acts
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.
- Literal(string)¶
- Local(*targets)¶
- MergeFlags(args, unique: bool = 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()
.As a side effect, if unique is true, a new object is created for each modified construction variable by the loop at the end. This is silently expected by the
Override()
parse_flags functionality, which does not want to share the list (or whatever) with the environment being overridden.- 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: bool = True)¶
Parse the result of running a command to update construction vars.
Use
function
to parse the output of runningcommand
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
. Iffunction
is omitted orNone
,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: bool = 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) None ¶
Prepend values to construction variables in an Environment.
The variable is created if it is not already present.
- PrependENVPath(name, newpath, envname: str = 'ENV', sep=':', delete_existing: bool = True) None ¶
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: bool = False, **kw) None ¶
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.
- 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) None ¶
Removes the specified function’s MethodWrapper from the added_methods list, so we don’t re-bind it when making a clone.
- Replace(**kw) None ¶
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.
- 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.
- Scanner(*args, **kw)¶
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.
- objs
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, **kwargs) Tool ¶
Find and run tool module tool.
Changed in version 4.2: returns the tool module rather than
None
.
- Value(value, built_value=None, name=None)¶
Return a Value (Python expression) node.
Changed in version 4.0: the name parameter was added.
- 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) andParseConfig()
.- 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.
- categories
- Returns:
- libs
list
Libraries to use.
- libs
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")
.
- get_CacheDir()¶
- get_builder(name)¶
Fetch the builder with the specified name from the environment.
- get_factory(factory, default: str = '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).
- gvars()¶
- items()¶
Emulates the items() method of dictionaries.
- keys()¶
Emulates the keys() method of dictionaries.
- lvars()¶
- setdefault(key, default=None)¶
Emulates the setdefault() method of dictionaries.
- subst(string, raw: int = 0, target=None, source=None, conv=None, executor=None, overrides: dict | None = 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_list(string, raw: int = 0, target=None, source=None, conv=None, executor=None, overrides: dict | None = 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.
Turns EntryProxies into Nodes, leaving Nodes (and other objects) as-is.
- subst_target_source(string, raw: int = 0, target=None, source=None, conv=None, executor=None, overrides: dict | None = 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.