Merge pull request #3493 from mwichmann/defenv-2477

Tweak DefaultEnvironment descriptions

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}<-' ))
       <para>
 
       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.
 
       </para>
 
       <para>
 
-      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:
 
       </para>
 
       <sconstruct>
-DefaultEnvironment(CC = '/usr/local/bin/gcc')
+DefaultEnvironment(CC='/usr/local/bin/gcc')
       </sconstruct>
 
       <para>
@@ -928,15 +925,15 @@ DefaultEnvironment(CC = '/usr/local/bin/gcc')
 
       <para>
 
-      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 <filename>/usr/local/bin/gcc</filename>
       but as a separate step after
       the default construction environment has been initialized:
@@ -971,8 +968,8 @@ env['CC'] = '/usr/local/bin/gcc'
       </para>
 
       <sconstruct>
-env = DefaultEnvironment(tools = ['gcc', 'gnulink'],
-                         CC = '/usr/local/bin/gcc')
+env = DefaultEnvironment(tools=['gcc', 'gnulink'],
+                         CC='/usr/local/bin/gcc')
       </sconstruct>
 
       <para>
@@ -994,9 +991,8 @@ env = DefaultEnvironment(tools = ['gcc', 'gnulink'],
 
       <para>
 
-      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() { }
 
       <para>
 
-      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..22f46fe 100644
--- a/src/engine/SCons/Defaults.xml
+++ b/src/engine/SCons/Defaults.xml
@@ -572,15 +572,21 @@ searching the repositories.
 
 <scons_function name="DefaultEnvironment">
 <arguments signature="global">
-([args])
+([**kwargs])
 </arguments>
 <summary>
 <para>
-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 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
+&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;.
 </para>
 </summary>
 </scons_function>