diff --git a/RELEASE.txt b/RELEASE.txt old mode 100755 new mode 100644 index 91d680daf1..78fcc16e3e --- a/RELEASE.txt +++ b/RELEASE.txt @@ -73,6 +73,7 @@ DOCUMENTATION - EnsureSConsVersion, EnsurePythonVersion, Exit, GetLaunchDir and SConscriptChdir are now listed as Global functions only. - Updated the docs for Glob. +- Updated SHELL_ENV_GENERATORS description and added versionadded indicator. DEVELOPMENT ----------- @@ -83,4 +84,4 @@ Thanks to the following contributors listed below for their contributions to thi ========================================================================================== .. code-block:: text - git shortlog --no-merges -ns 4.0.1..HEAD + git shortlog --no-merges -ns 4.4.0..HEAD diff --git a/SCons/Action.py b/SCons/Action.py index 6e67c7ff1c..ccb3a2c747 100644 --- a/SCons/Action.py +++ b/SCons/Action.py @@ -110,6 +110,7 @@ from collections import OrderedDict import SCons.Debug +import SCons.Util from SCons.Debug import logInstanceCreation import SCons.Errors import SCons.Util @@ -733,34 +734,42 @@ def _string_from_cmd_list(cmd_list): def get_default_ENV(env): - """ - A fiddlin' little function that has an 'import SCons.Environment' which - can't be moved to the top level without creating an import loop. Since - this import creates a local variable named 'SCons', it blocks access to - the global variable, so we move it here to prevent complaints about local - variables being used uninitialized. + """Returns an execution environment. + + If there is one in *env*, just use it, else return the Default + Environment, insantiated if necessary. + + A fiddlin' little function that has an ``import SCons.Environment`` + which cannot be moved to the top level without creating an import + loop. Since this import creates a local variable named ``SCons``, + it blocks access to the global variable, so we move it here to + prevent complaints about local variables being used uninitialized. """ global default_ENV + try: return env['ENV'] except KeyError: if not default_ENV: import SCons.Environment - # This is a hideously expensive way to get a default shell + # This is a hideously expensive way to get a default execution # environment. What it really should do is run the platform # setup to get the default ENV. Fortunately, it's incredibly - # rare for an Environment not to have a shell environment, so - # we're not going to worry about it overmuch. + # rare for an Environment not to have an execution environment, + # so we're not going to worry about it overmuch. default_ENV = SCons.Environment.Environment()['ENV'] return default_ENV def _resolve_shell_env(env, target, source): - """ - First get default environment. - Then if SHELL_ENV_GENERATORS is set and is iterable, - call each callable in that list to allow it to alter - the created execution environment. + """Returns a resolved execution environment. + + First get the execution environment. Then if ``SHELL_ENV_GENERATORS`` + is set and is iterable, call each function to allow it to alter the + created execution environment, passing each the returned execution + environment from the previous call. + + .. versionadded:: 4.4 """ ENV = get_default_ENV(env) shell_gen = env.get('SHELL_ENV_GENERATORS') @@ -793,7 +802,7 @@ def _subproc(scons_env, cmd, error='ignore', **kw): if is_String(io) and io == 'devnull': kw[stream] = DEVNULL - # Figure out what shell environment to use + # Figure out what execution environment to use ENV = kw.get('env', None) if ENV is None: ENV = get_default_ENV(scons_env) diff --git a/SCons/Action.xml b/SCons/Action.xml index 209c3890f6..becd30f792 100644 --- a/SCons/Action.xml +++ b/SCons/Action.xml @@ -26,14 +26,13 @@ See its __doc__ string for a discussion of the format. -Controls whether or not SCons will +Controls whether or not &SCons; will add implicit dependencies for the commands executed to build targets. -By default, SCons will add -to each target +By default, &SCons; will add to each target an implicit dependency on the command represented by the first argument of any command line it executes (which is typically @@ -224,21 +223,39 @@ defining the execution environment in which the command should be executed. -Must be a list (or an iterable) containing functions where each function generates or -alters the environment dictionary which will be used -when executing the &cv-link-SPAWN; function. The functions will initially -be passed a reference of the current execution environment (e.g. env['ENV']), -and each called while iterating the list. Each function must return a dictionary -which will then be passed to the next function iterated. The return dictionary -should contain keys which represent the environment variables and their respective -values. +A hook allowing the execution environment to be modified prior +to the actual execution of a command line from an action +via the spawner function defined by &cv-link-SPAWN;. +Allows substitution based on targets and sources, +as well as values from the &consenv;, +adding extra environment variables, etc. + -This primary purpose of this construction variable is to give the user the ability -to substitute execution environment variables based on env, targets, and sources. -If desired, the user can completely customize the execution environment for particular -targets. + +The value must be a list (or other iterable) +of functions which each generate or +alter the execution environment dictionary. +The first function will be passed a copy of the initial execution environment +(&cv-link-ENV; in the current &consenv;); +the dictionary returned by that function is passed to the next, +until the iterable is exhausted and the result returned +for use by the command spawner. +The original execution environment is not modified. + +Each function provided in &cv-SHELL_ENV_GENERATORS; must accept four +arguments and return a dictionary: +env is the &consenv; for this action; +target is the list of targets associated with this action; +source is the list of sources associated with this action; +and shell_env is the current dictionary after iterating +any previous &cv-SHELL_ENV_GENERATORS; functions +(this can be compared to the original execution environment, +which is available as env['ENV'], to detect any changes). + + + Example: def custom_shell_env(env, target, source, shell_env): """customize shell_env if desired""" @@ -249,24 +266,7 @@ def custom_shell_env(env, target, source, shell_env): env["SHELL_ENV_GENERATORS"] = [custom_shell_env] - - env -The SCons construction environment from which the -execution environment can be derived from. - - - target -The list of targets associated with this action. - - - source -The list of sources associated with this action. - - - shell_env -The current shell_env after iterating other SHELL_ENV_GENERATORS functions. This can be compared -to the passed env['ENV'] to detect any changes. - + Available since 4.4