From 693b6f94e49f6efee1f65b124102a843abd439a1 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 10 Jan 2022 12:30:14 -0700 Subject: Update manpage bits about env['ENV'] [skip appveyor] Signed-off-by: Mats Wichmann --- SCons/Environment.py | 24 ++++---- SCons/Environment.xml | 153 +++++++++++++++++++++++++++----------------------- 2 files changed, 95 insertions(+), 82 deletions(-) diff --git a/SCons/Environment.py b/SCons/Environment.py index c8cddf7..d0a4baf 100644 --- a/SCons/Environment.py +++ b/SCons/Environment.py @@ -1279,15 +1279,15 @@ class Base(SubstitutionEnvironment): path = str(self.fs.Dir(path)) return path - def AppendENVPath(self, name, newpath, envname = 'ENV', - sep = os.pathsep, delete_existing=0): - """Append path elements to the path 'name' in the 'ENV' + def AppendENVPath(self, name, newpath, envname='ENV', + sep=os.pathsep, 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 0, a newpath which is already in the path + 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). """ @@ -1302,10 +1302,10 @@ class Base(SubstitutionEnvironment): self._dict[envname][name] = nv - def AppendUnique(self, delete_existing=0, **kw): + def AppendUnique(self, delete_existing=False, **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 + If delete_existing is True, removes existing values first, so values move to end. """ kw = copy_non_reserved_keywords(kw) @@ -1756,15 +1756,15 @@ class Base(SubstitutionEnvironment): self.scanner_map_delete(kw) - def PrependENVPath(self, name, newpath, envname = 'ENV', sep = os.pathsep, - delete_existing=1): - """Prepend path elements to the path 'name' in the 'ENV' + def PrependENVPath(self, name, newpath, envname='ENV', + sep=os.pathsep, 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 0, a newpath which is already in the path + 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). """ @@ -1780,10 +1780,10 @@ class Base(SubstitutionEnvironment): self._dict[envname][name] = nv - def PrependUnique(self, delete_existing=0, **kw): + def PrependUnique(self, delete_existing=False, **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 + If delete_existing is True, removes existing values first, so values move to front. """ kw = copy_non_reserved_keywords(kw) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 43e3b25..630d77b 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -78,49 +78,41 @@ env['BUILDERS']['NewBuilder'] = bld -A dictionary of environment variables -to use when invoking commands. When -&cv-ENV; is used in a command all list -values will be joined using the path separator and any other non-string -values will simply be coerced to a string. -Note that, by default, -&scons; +The execution environment - +a dictionary of environment variables +used when &SCons; invokes external commands +to build targets defined in this &consenv;. +When &cv-ENV; is passed to a command, +all list values are assumed to be path lists and +are joined using the search path separator. +Any other non-string values are coerced to a string. + + + +Note that by default +&SCons; does not -propagate the environment in effect when you -execute -&scons; -to the commands used to build target files. +propagate the environment in effect when you execute +&scons; (the "shell environment") +to the execution environment. This is so that builds will be guaranteed repeatable regardless of the environment variables set at the time &scons; is invoked. - - - -If you want to propagate your -environment variables +If you want to propagate a +shell environment variable to the commands executed to build target files, -you must do so explicitly: - - - -import os -env = Environment(ENV=os.environ.copy()) - - - -Note that you can choose only to propagate -certain environment variables. +you must do so explicitly. A common example is the system PATH environment variable, so that &scons; -uses the same utilities +will find utilities the same way as the invoking shell (or other process): @@ -128,6 +120,18 @@ as the invoking shell (or other process): import os env = Environment(ENV={'PATH': os.environ['PATH']}) + + +Although it is usually not recommended, +you can propagate the entire shell environment +in one go: + + + +import os +env = Environment(ENV=os.environ.copy()) + + @@ -645,26 +649,26 @@ See also &f-link-env-AppendUnique;, -Append new path elements to the given path in the -specified external environment (&cv-link-ENV; by default). -This will only add -any particular path once (leaving the last one it encounters and -ignoring the rest, to preserve path order), -and to help assure this, -will normalize all paths (using -os.path.normpath +Append path elements specified by newpath +to the given search path string or list name +in mapping envname in the &consenv;. +Supplying envname is optional: +the default is the execution environment &cv-link-ENV;. +Optional sep is used as the search path separator, +the default is the platform's separator (os.pathsep). +A path element will only appear once. +Any duplicates in newpath are dropped, +keeping the last appearing (to preserve path order). +If delete_existing +is False (the default) +any addition duplicating an existing path element is ignored; +if delete_existing +is True the existing value will +be dropped and the path element will be added at the end. +To help maintain uniqueness all paths are normalized (using +os.path.normpath and -os.path.normcase). -This can also handle the -case where the given old path variable is a list instead of a -string, in which case a list will be returned instead of a string. - - - -If -delete_existing -is False, then adding a path that already exists -will not move it to the end; it will stay where it is in the list. +os.path.normcase). @@ -683,6 +687,11 @@ print('after:', env['ENV']['INCLUDE']) before: /foo:/biz after: /biz:/foo/bar:/foo + + +See also &f-link-env-PrependENVPath;. + + @@ -1437,10 +1446,11 @@ Find an executable from one or more choices: progs may be a string or a list of strings. Returns the first value from progs that was found, or None. -Executable is searched by checking the paths specified -by env['ENV']['PATH']. +Executable is searched by checking the paths in the execution enviroment +(env['ENV']['PATH']). On Windows systems, additionally applies the filename suffixes found in -env['ENV']['PATHEXT'] +the execution environment +(env['ENV']['PATHEXT']) but will not include any such extension in the return value. &f-env-Detect; is a wrapper around &f-link-env-WhereIs;. @@ -2614,32 +2624,30 @@ and &f-link-env-PrependUnique;. -(name, newpath, [envname, sep, delete_existing]) +(name, newpath, [envname, sep, delete_existing=True]) -Prepend new path elements to the given path in the -specified external environment (&cv-link-ENV; by default). -This will only add -any particular path once (leaving the first one it encounters and -ignoring the rest, to preserve path order), -and to help assure this, -will normalize all paths (using +Prepend path elements specified by newpath +to the given search path string or list name +in mapping envname in the &consenv;. +Supplying envname is optional: +the default is the execution environment &cv-link-ENV;. +Optional sep is used as the search path separator, +the default is the platform's separator (os.pathsep). +A path element will only appear once. +Any duplicates in newpath are dropped, +keeping the first appearing (to preserve path order). +If delete_existing +is False +any addition duplicating an existing path element is ignored; +if delete_existing +is True (the default) the existing value will +be dropped and the path element will be inserted at the beginning. +To help maintain uniqueness all paths are normalized (using os.path.normpath and os.path.normcase). -This can also handle the -case where the given old path variable is a list instead of a -string, in which case a list will be returned instead of a string. - - - -If -delete_existing -is False, -then adding a path that already exists -will not move it to the beginning; -it will stay where it is in the list. @@ -2659,6 +2667,11 @@ print('after:', env['ENV']['INCLUDE']) before: /biz:/foo after: /foo/bar:/foo:/biz + + +See also &f-link-env-AppendENVPath;. + + -- cgit v0.12