From d960416fc4caa6e799812357fe91c3f3e11a9174 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 13 Dec 2019 08:25:01 -0700 Subject: Tweak DefaultEnvironment descriptions (ci skip) Doc-only change to be more explicit about when the default construction environment is used, and what it means to call DefaultEnvironment() - only the first call instantiates it, later calls return the object. Fixes #2477 Signed-off-by: Mats Wichmann --- doc/user/environments.xml | 58 ++++++++++++++++++++----------------------- src/engine/SCons/Defaults.xml | 16 ++++++++---- 2 files changed, 38 insertions(+), 36 deletions(-) diff --git a/doc/user/environments.xml b/doc/user/environments.xml index 43503a6..d3e5d6d 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -886,33 +886,30 @@ print("value is: %s"%env.subst( '->${1 / 0}<-' )) All of the &Builder; functions that we've introduced so far, - like &Program; and &Library;, - actually use a default &consenv; - that contains settings - for the various compilers - and other tools that - &SCons; configures by default, - or otherwise knows about - and has discovered on your system. - The goal of the default construction environment - is to make many configurations to "just work" - to build software using - readily available tools + like &Program; and &Library;, use a &consenv; + that contains settings for the various compilers + and other tools that &SCons; configures by default, + or otherwise knows about and has discovered on your system. + If not invoked as methods of a specific &consenv;, + they use the default &consenv; + The goal of the default &consenv; + is to make many configurations "just work" + to build software using readily available tools with a minimum of configuration changes. - You can, however, control the settings - in the default construction environment + If needed, you can control the default &consenv; by using the &DefaultEnvironment; function - to initialize various settings: + to initialize various settings by passing + them as keyword arguments: -DefaultEnvironment(CC = '/usr/local/bin/gcc') +DefaultEnvironment(CC='/usr/local/bin/gcc') @@ -928,15 +925,15 @@ DefaultEnvironment(CC = '/usr/local/bin/gcc') - Note that the &DefaultEnvironment; function - returns the initialized - default construction environment object, - which can then be manipulated like any - other construction environment. - So the following - would be equivalent to the - previous example, - setting the &cv-CC; + The &DefaultEnvironment; function + returns the initialized default &consenv; object, + which can then be manipulated like any other &consenv; + (note that the default environment works like a singleton - + it can have only one instance - so the keyword arguments + are processed only on the first call. On any subsequent + call the existing object is returned). + So the following would be equivalent to the + previous example, setting the &cv-CC; variable to /usr/local/bin/gcc but as a separate step after the default construction environment has been initialized: @@ -971,8 +968,8 @@ env['CC'] = '/usr/local/bin/gcc' -env = DefaultEnvironment(tools = ['gcc', 'gnulink'], - CC = '/usr/local/bin/gcc') +env = DefaultEnvironment(tools=['gcc', 'gnulink'], + CC='/usr/local/bin/gcc') @@ -994,9 +991,8 @@ env = DefaultEnvironment(tools = ['gcc', 'gnulink'], - The real advantage of construction environments - is that you can create as many different construction - environments as you need, + The real advantage of &consenvs; + is that you can create as many different ones as you need, each tailored to a different way to build some piece of software or other file. If, for example, we need to build @@ -1029,7 +1025,7 @@ int main() { } - We can even use multiple construction environments to build + We can even use multiple &consenvs; to build multiple versions of a single program. If you do this by simply trying to use the &b-link-Program; builder with both environments, though, diff --git a/src/engine/SCons/Defaults.xml b/src/engine/SCons/Defaults.xml index f215f5a..5002411 100644 --- a/src/engine/SCons/Defaults.xml +++ b/src/engine/SCons/Defaults.xml @@ -572,15 +572,21 @@ searching the repositories. -([args]) +([**kwargs]) -Creates and returns a default construction environment object. -This construction environment is used internally by SCons -in order to execute many of the global functions in this list, -and to fetch source files transparently +Creates and returns a default &consenv; object. +The default &consenv; is used internally by SCons +in order to execute many of the global functions in this list +(i.e. those not called as methods of a specific +&consenv;), and to fetch source files transparently from source code management systems. +The default environment is a singleton, so the keyword +arguments affect it only on the first call, on subsequent +calls the already-constructed object is returned. +The default environment can be modified in the same way +as any &consenv;. -- cgit v0.12 From ddab0035a4ec1b2de1d105e26f82dcc7d153dc4b Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 13 Dec 2019 09:07:12 -0700 Subject: [PR #3493] fix review comment [ci skip] Signed-off-by: Mats Wichmann --- src/engine/SCons/Defaults.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/SCons/Defaults.xml b/src/engine/SCons/Defaults.xml index 5002411..22f46fe 100644 --- a/src/engine/SCons/Defaults.xml +++ b/src/engine/SCons/Defaults.xml @@ -576,7 +576,7 @@ searching the repositories. -Creates and returns a default &consenv; object. +Creates and returns the default &consenv; object. The default &consenv; is used internally by SCons in order to execute many of the global functions in this list (i.e. those not called as methods of a specific -- cgit v0.12