1 files changed, 168 insertions, 0 deletions
diff --git a/doc/user/ENV.in b/doc/user/ENV.in
new file mode 100644
index 0000000..3fc3a29
--- /dev/null
+++ b/doc/user/ENV.in
@@ -0,0 +1,168 @@
+
+<!--
+
+  Copyright (c) 2001, 2002, 2003 Steven Knight
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+  <para>
+
+    When &SCons; builds a target file,
+    it does not execute the commands with
+    the same external environment
+    that you used to execute &SCons;.
+    Instead, it uses the dictionary
+    stored in the &ENV; construction variable
+    as the external environment
+    for executing commands.
+
+  </para>
+
+  <para>
+
+    The most important ramification of this behavior
+    is that the &PATH; environment variable,
+    which controls where the operating system
+    will look for commands and utilities,
+    is not the same as in the external environment
+    from which you called &SCons;.
+    This means that &SCons; will not, by default,
+    necessarily find all of the tools
+    that you can execute from the command line.
+
+  </para>
+
+  <para>
+
+    The default value of the &PATH; environment variable
+    on a POSIX system
+    is <literal>/usr/local/bin:/bin:/usr/bin</literal>.
+    The default value of the &PATH; environment variable
+    on a Win32 system comes from the Windows registry
+    value for the command interpreter.
+    If you want to execute any commands--compilers, linkers, etc.--that
+    are not in these default locations,
+    you need to set the &PATH; value
+    in the &ENV; dictionary
+    in your construction environment.
+
+  </para>
+
+  <para>
+
+    The simplest way to do this is to initialize explicitly
+    the value when you create the construction environment;
+    this is one way to do that:
+
+  </para>
+
+  <sconstruct>
+    path = ['/usr/local/bin', '/bin', '/usr/bin']
+    env = Environment(ENV = {'PATH' : path})
+  </sconstruct>
+
+  <!--
+
+  <scons_example name="ex1">
+    <file name="SConstruct" printme="1">
+    env = Environment()
+    env.Command('foo', [], '__ROOT__/usr/bin/printenv.py')
+    </file>
+    <file name="__ROOT__/usr/bin/printenv.py" chmod="0755">
+    #!/usr/bin/env python
+    import os
+    import sys
+    if len(sys.argv) > 1:
+        keys = sys.argv[1:]
+    else:
+        keys = os.environ.keys()
+        keys.sort()
+    for key in keys:
+        print "    " + key + "=" + os.environ[key]
+    </file>
+  </scons_example>
+
+  <para>
+
+  </para>
+
+  <scons_output example="ex1">
+    <command>scons -Q</command>
+  </scons_output>
+
+  -->
+
+  <section>
+  <title>Propagating &PATH; From the External Environment</title>
+
+    <para>
+
+    You may want to propagate the external &PATH;
+    to the execution environment for commands.
+    You do this by initializing the &PATH;
+    variable with the &PATH; value from
+    the <literal>os.environ</literal>
+    dictionary,
+    which is Python's way of letting you
+    get at the external environment:
+
+    </para>
+
+    <sconstruct>
+      import os
+      env = Environment(ENV = {'PATH' : os.environ['PATH']})
+    </sconstruct>
+
+    <para>
+
+    Alternatively, you may find it easier
+    to just propagate the entire external
+    environment to the execution environment
+    for commands.
+    This is simpler to code than explicity
+    selecting the &PATH; value:
+
+    </para>
+
+    <sconstruct>
+      import os
+      env = Environment(ENV = os.environ)
+    </sconstruct>
+
+    <para>
+
+    Either of these will guarantee that
+    &SCons; will be able to execute
+    any command that you can execute from the command line.
+    The drawback is that the build can behave
+    differently if it's run by people with
+    different &PATH; values in their environment--for example,
+    both the <literal>/bin</literal> and
+    <literal>/usr/local/bin</literal> directories
+    have different &cc; commands,
+    then which one will be used to compile programs
+    will depend on which directory is listed
+    first in the user's &PATH; variable.
+
+    </para>
+
+  </section>