Ensure that the ENV values are all strings. (Anthony Roach)

11 files changed, 447 insertions, 36 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>
diff --git a/doc/user/ENV.sgml b/doc/user/ENV.sgml
new file mode 100644
index 0000000..d3078f1
--- /dev/null
+++ b/doc/user/ENV.sgml
@@ -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>
+
+  <programlisting>
+    path = ['/usr/local/bin', '/bin', '/usr/bin']
+    env = Environment(ENV = {'PATH' : path})
+  </programlisting>
+
+  <!--
+
+  <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>
+
+    <programlisting>
+      import os
+      env = Environment(ENV = {'PATH' : os.environ['PATH']})
+    </programlisting>
+
+    <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>
+
+    <programlisting>
+      import os
+      env = Environment(ENV = os.environ)
+    </programlisting>
+
+    <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>
diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST
index 337c8e0..c9af4a4 100644
--- a/doc/user/MANIFEST
+++ b/doc/user/MANIFEST
@@ -10,6 +10,7 @@ cons.pl
 cons.sgml
 copyright.sgml
 depends.sgml
+ENV.sgml
 environments.sgml
 errors.sgml
 example.sgml
diff --git a/doc/user/command-line.in b/doc/user/command-line.in
index 9367c09..6f523a8 100644
--- a/doc/user/command-line.in
+++ b/doc/user/command-line.in
@@ -40,8 +40,25 @@
     the same command-line options every time
     they run &SCons;.
     For example, a user might find that it saves time
-    to always specify a value of <literal>-j 2</literal>
+    to specify a value of <literal>-j 2</literal>
     to run the builds in parallel.
+    To avoid having to type <literal>-j 2</literal> by hand
+    every time,
+    you can set the external environment variable
+    &SCONSFLAGS; to a string containing
+    command-line options that you want &SCons; to use.
+
+    </para>
+
+    <para>
+
+    If, for example,
+    and you're using a POSIX shell that's
+    compatible with the Bourne shell,
+    and you always want &SCons; to use the
+    <literal>-Q</literal> option,
+    you can set the &SCONSFLAGS;
+    environment as follows:
 
     </para>
 
@@ -68,6 +85,21 @@
 
     <para>
 
+    Users of &csh;-style shells on POSIX systems
+    can set the &SCONSFLAGS; environment as follows:
+
+    </para>
+
+    <literallayout>
+      $ setenv SCONSFLAGS "-Q"
+    </literallayout>
+
+    <para>
+
+    Windows users may typically want to set this
+    &SCONSFLAGS; in the appropriate tab of the
+    <literal>System Properties</literal> window.
+
     </para>
 
   </section>
diff --git a/doc/user/command-line.sgml b/doc/user/command-line.sgml
index f6f219c..cf15b93 100644
--- a/doc/user/command-line.sgml
+++ b/doc/user/command-line.sgml
@@ -40,8 +40,25 @@
     the same command-line options every time
     they run &SCons;.
     For example, a user might find that it saves time
-    to always specify a value of <literal>-j 2</literal>
+    to specify a value of <literal>-j 2</literal>
     to run the builds in parallel.
+    To avoid having to type <literal>-j 2</literal> by hand
+    every time,
+    you can set the external environment variable
+    &SCONSFLAGS; to a string containing
+    command-line options that you want &SCons; to use.
+
+    </para>
+
+    <para>
+
+    If, for example,
+    and you're using a POSIX shell that's
+    compatible with the Bourne shell,
+    and you always want &SCons; to use the
+    <literal>-Q</literal> option,
+    you can set the &SCONSFLAGS;
+    environment as follows:
 
     </para>
 
@@ -67,6 +84,21 @@
 
     <para>
 
+    Users of &csh;-style shells on POSIX systems
+    can set the &SCONSFLAGS; environment as follows:
+
+    </para>
+
+    <literallayout>
+      $ setenv SCONSFLAGS "-Q"
+    </literallayout>
+
+    <para>
+
+    Windows users may typically want to set this
+    &SCONSFLAGS; in the appropriate tab of the
+    <literal>System Properties</literal> window.
+
     </para>
 
   </section>
diff --git a/doc/user/environments.in b/doc/user/environments.in
index 2083d4f..7e68b5e 100644
--- a/doc/user/environments.in
+++ b/doc/user/environments.in
@@ -402,7 +402,7 @@ environment undisturbed.
    Technically, a &consenv; is an object
    that has a number of associated
    &consvars;, each with a name and a value.
-   (A &consenv; also has an attached
+   (A construction environment also has an attached
    set of &Builder; methods,
    about which we'll learn more later.)
 
@@ -411,7 +411,7 @@ environment undisturbed.
  <para>
 
    A &consenv; is created by the &Environment; method.
-   When you initialize a &consenv;,
+   When you initialize a construction environment
    you can set the values of the
    environment's &consvars;
    to control how a program is built.
@@ -453,8 +453,7 @@ environment undisturbed.
    <para>
 
    The real advantage of construction environments
-   become apparent when you realize
-   that you can create as many different construction
+   is that you can create as many different construction
    environments as you need,
    each tailored to a different way to build
    some piece of software or other file.
@@ -488,7 +487,7 @@ environment undisturbed.
 
    <para>
 
-   We can even use multiple &consenvs; to build
+   We can even use multiple construction environments to build
    multiple versions of a single program.
    If you do this by simply trying to use the
    &Program; builder with both environments, though,
@@ -587,24 +586,24 @@ environment undisturbed.
 
    <para>
 
-   Sometimes you want more than one &consenv;
+   Sometimes you want more than one construction environment
    to share the same values for one or more variables.
    Rather than always having to repeat all of the common
-   variables when you create each &consenv;,
+   variables when you create each construction environment,
    you can use the &Copy; method
-   to create a copy of a &consenv;.
+   to create a copy of a construction environment.
 
    </para>
 
    <para>
 
-   Like the &Environment; call that creates a &consenv;,
+   Like the &Environment; call that creates a construction environment,
    the &Copy; method takes &consvar; assignments,
-   which will override the values in the copied &consenv;.
+   which will override the values in the copied construction environment.
    For example, suppose we want to use &gcc;
    to create three versions of a program,
    one optimized, one debug, and one with neither.
-   We could do this by creating a "base" &consenv;
+   We could do this by creating a "base" construction environment
    that sets &CC; to &gcc;,
    and then creating two copies,
    one which sets &CCFLAGS; for optimization
@@ -675,7 +674,7 @@ environment undisturbed.
 
    <para>
 
-   A &consenv;, however,
+   A construction environment, however,
    is actually a Python object with
    associated methods, etc.
    If you want to have direct access to only the
@@ -723,7 +722,7 @@ environment undisturbed.
    <para>
 
    &SCons; provides various methods that
-   support modifying existing values in a &consenv;.
+   support modifying existing values in a construction environment.
 
    </para>
 
diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml
index 2be8614..2b4fb5d 100644
--- a/doc/user/environments.sgml
+++ b/doc/user/environments.sgml
@@ -402,7 +402,7 @@ environment undisturbed.
    Technically, a &consenv; is an object
    that has a number of associated
    &consvars;, each with a name and a value.
-   (A &consenv; also has an attached
+   (A construction environment also has an attached
    set of &Builder; methods,
    about which we'll learn more later.)
 
@@ -411,7 +411,7 @@ environment undisturbed.
  <para>
 
    A &consenv; is created by the &Environment; method.
-   When you initialize a &consenv;,
+   When you initialize a construction environment
    you can set the values of the
    environment's &consvars;
    to control how a program is built.
@@ -450,8 +450,7 @@ environment undisturbed.
    <para>
 
    The real advantage of construction environments
-   become apparent when you realize
-   that you can create as many different construction
+   is that you can create as many different construction
    environments as you need,
    each tailored to a different way to build
    some piece of software or other file.
@@ -481,7 +480,7 @@ environment undisturbed.
 
    <para>
 
-   We can even use multiple &consenvs; to build
+   We can even use multiple construction environments to build
    multiple versions of a single program.
    If you do this by simply trying to use the
    &Program; builder with both environments, though,
@@ -577,24 +576,24 @@ environment undisturbed.
 
    <para>
 
-   Sometimes you want more than one &consenv;
+   Sometimes you want more than one construction environment
    to share the same values for one or more variables.
    Rather than always having to repeat all of the common
-   variables when you create each &consenv;,
+   variables when you create each construction environment,
    you can use the &Copy; method
-   to create a copy of a &consenv;.
+   to create a copy of a construction environment.
 
    </para>
 
    <para>
 
-   Like the &Environment; call that creates a &consenv;,
+   Like the &Environment; call that creates a construction environment,
    the &Copy; method takes &consvar; assignments,
-   which will override the values in the copied &consenv;.
+   which will override the values in the copied construction environment.
    For example, suppose we want to use &gcc;
    to create three versions of a program,
    one optimized, one debug, and one with neither.
-   We could do this by creating a "base" &consenv;
+   We could do this by creating a "base" construction environment
    that sets &CC; to &gcc;,
    and then creating two copies,
    one which sets &CCFLAGS; for optimization
@@ -666,7 +665,7 @@ environment undisturbed.
 
    <para>
 
-   A &consenv;, however,
+   A construction environment, however,
    is actually a Python object with
    associated methods, etc.
    If you want to have direct access to only the
@@ -720,7 +719,7 @@ environment undisturbed.
    <para>
 
    &SCons; provides various methods that
-   support modifying existing values in a &consenv;.
+   support modifying existing values in a construction environment.
 
    </para>
 
diff --git a/doc/user/libraries.in b/doc/user/libraries.in
index a69bbee..a31b2b4 100644
--- a/doc/user/libraries.in
+++ b/doc/user/libraries.in
@@ -25,9 +25,10 @@
 
   <para>
 
-  One of the more useful ways in which you can use multiple
-  construction environments is to link programs
-  with different sets of libraries.
+  It's often useful to organize large software projects
+  by collecting parts of the software into one or more libraries.
+  &SCons; makes it easy to create libraries
+  and to use them in the programs.
 
   </para>
 
@@ -109,7 +110,6 @@
     and by specifying the directory in which
     the library will be found in the 
     &LIBPATH; construction variable:
-      env = Environment(LIBS = 'foo', LIBPATH = '.')
 
     </para>
 
diff --git a/doc/user/libraries.sgml b/doc/user/libraries.sgml
index 118a560..fedeb7f 100644
--- a/doc/user/libraries.sgml
+++ b/doc/user/libraries.sgml
@@ -25,9 +25,10 @@
 
   <para>
 
-  One of the more useful ways in which you can use multiple
-  construction environments is to link programs
-  with different sets of libraries.
+  It's often useful to organize large software projects
+  by collecting parts of the software into one or more libraries.
+  &SCons; makes it easy to create libraries
+  and to use them in the programs.
 
   </para>
 
@@ -104,7 +105,6 @@
     and by specifying the directory in which
     the library will be found in the 
     &LIBPATH; construction variable:
-      env = Environment(LIBS = 'foo', LIBPATH = '.')
 
     </para>
 
diff --git a/doc/user/main.in b/doc/user/main.in
index 4aa4d9c..1a017d3 100644
--- a/doc/user/main.in
+++ b/doc/user/main.in
@@ -43,6 +43,7 @@
     <!ENTITY cons SYSTEM "cons.sgml">
     <!ENTITY copyright SYSTEM "copyright.sgml">
     <!ENTITY depends SYSTEM "depends.sgml">
+    <!ENTITY ENV_file SYSTEM "ENV.sgml">
     <!ENTITY environments SYSTEM "environments.sgml">
     <!ENTITY errors SYSTEM "errors.sgml">
     <!ENTITY example SYSTEM "example.sgml">
@@ -115,6 +116,11 @@
     &environments;
   </chapter>
 
+  <chapter id="chap-ENV">
+    <title>Controlling the Environment Used to Execute Build Commands</title>
+    &ENV_file;
+  </chapter>
+
   <chapter id="chap-command-line">
     <title>Controlling a Build From the Command Line</title>
     &command-line;
diff --git a/doc/user/main.sgml b/doc/user/main.sgml
index 4aa4d9c..1a017d3 100644
--- a/doc/user/main.sgml
+++ b/doc/user/main.sgml
@@ -43,6 +43,7 @@
     <!ENTITY cons SYSTEM "cons.sgml">
     <!ENTITY copyright SYSTEM "copyright.sgml">
     <!ENTITY depends SYSTEM "depends.sgml">
+    <!ENTITY ENV_file SYSTEM "ENV.sgml">
     <!ENTITY environments SYSTEM "environments.sgml">
     <!ENTITY errors SYSTEM "errors.sgml">
     <!ENTITY example SYSTEM "example.sgml">
@@ -115,6 +116,11 @@
     &environments;
   </chapter>
 
+  <chapter id="chap-ENV">
+    <title>Controlling the Environment Used to Execute Build Commands</title>
+    &ENV_file;
+  </chapter>
+
   <chapter id="chap-command-line">
     <title>Controlling a Build From the Command Line</title>
     &command-line;