Branch for documentation changes.

1 files changed, 329 insertions, 34 deletions

diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml
index eb9bf5b..1ff2fb3 100644
--- a/doc/user/environments.sgml
+++ b/doc/user/environments.sgml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003 Steven Knight
+  __COPYRIGHT__
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -410,7 +410,34 @@ environment undisturbed.
 
  <para>
 
-   A &consenv; is created by the &Environment; method.
+   A &consenv; is created by the &Environment; method:
+
+ </para>
+
+  <programlisting>
+    env = Environment()
+  </programlisting>
+
+ <para>
+
+   By default, &SCons; intializes every
+   new construction environment
+   with a set of &consvars;
+   based on the tools that it finds on your system,
+   plus the default set of builder methods
+   necessary for using those tools.
+   The construction variables
+   are initialized with values describing
+   the C compiler,
+   the Fortran compiler,
+   the linker,
+   etc.,
+   as well as the command lines to invoke them.
+
+ </para>
+
+ <para>
+
    When you initialize a construction environment
    you can set the values of the
    environment's &consvars;
@@ -428,21 +455,26 @@ environment undisturbed.
 
  <para>
    
-   This example, rather than using the default,
-   explicitly specifies use of the
+   The construction environment in this example
+   is still initialized with the same default
+   construction variable values,
+   except that the user has explicitly specified use of the
    GNU C compiler &gcc;,
    and further specifies that the <literal>-O2</literal>
    (optimization level two)
    flag should be used when compiling the object file.
+   In other words, the explicit initializations of &CC; and &CCFLAGS;
+   override the default values in the newly-created
+   construction environment.
    So a run from this example would look like:
 
  </para>
 
- <literallayout>
+ <screen>
     % <userinput>scons -Q</userinput>
     gcc -O2 -c -o foo.o foo.c
     gcc -o foo foo.o
- </literallayout>
+ </screen>
 
  <section>
  <title>Multiple &ConsEnvs;</title>
@@ -470,13 +502,13 @@ environment undisturbed.
       dbg.Program('bar', 'bar.c')
    </programlisting>
 
-   <literallayout>
+   <screen>
       % <userinput>scons -Q</userinput>
       cc -g -c -o bar.o bar.c
       cc -o bar bar.o
       cc -O2 -c -o foo.o foo.c
       cc -o foo foo.o
-   </literallayout>
+   </screen>
 
    <para>
 
@@ -503,12 +535,12 @@ environment undisturbed.
 
    </para>
 
-   <literallayout>
+   <screen>
       % <userinput>scons -Q</userinput>
       
       scons: *** Two environments with different actions were specified for the same target: foo.o
       File "SConstruct", line 6, in ?
-   </literallayout>
+   </screen>
 
    <para>
 
@@ -532,9 +564,6 @@ environment undisturbed.
    </para>
 
    <programlisting>
-   </programlisting>
-
-   <programlisting>
       opt = Environment(CCFLAGS = '-O2')
       dbg = Environment(CCFLAGS = '-g')
 
@@ -561,13 +590,13 @@ environment undisturbed.
 
    </para>
 
-   <literallayout>
+   <screen>
       % <userinput>scons -Q</userinput>
       cc -g -c -o foo-dbg.o foo.c
       cc -o foo-dbg foo-dbg.o
       cc -O2 -c -o foo-opt.o foo.c
       cc -o foo-opt foo-opt.o
-   </literallayout>
+   </screen>
 
  </section>
 
@@ -621,7 +650,7 @@ environment undisturbed.
 
    </para>
 
-   <literallayout>
+   <screen>
       % <userinput>scons -Q</userinput>
       gcc -c -o foo.o foo.c
       gcc -o foo foo.o
@@ -629,7 +658,7 @@ environment undisturbed.
       gcc -o foo-dbg foo-dbg.o
       gcc -O2 -c -o foo-opt.o foo.c
       gcc -o foo-opt foo-opt.o
-   </literallayout>
+   </screen>
 
  </section>
 
@@ -657,17 +686,16 @@ environment undisturbed.
 
    </para>
 
-   <literallayout>
+   <screen>
       % <userinput>scons -Q</userinput>
       CC is: cc
       scons: `.' is up to date.
-   </literallayout>
+   </screen>
 
    <para>
 
    A construction environment, however,
-   is actually a Python object with
-   associated methods, etc.
+   is actually an object with associated methods, etc.
    If you want to have direct access to only the
    dictionary of construction variables,
    you can fetch this using the &Dictionary; method:
@@ -689,13 +717,13 @@ environment undisturbed.
 
    </para>
 
-   <literallayout>
+   <screen>
       % <userinput>scons -Q</userinput>
       key = OBJSUFFIX, value = .o
       key = LIBSUFFIX, value = .a
       key = PROGSUFFIX, value = 
       scons: `.' is up to date.
-   </literallayout>
+   </screen>
 
    <para>
 
@@ -703,13 +731,123 @@ environment undisturbed.
 
    </para>
 
-   <literallayout>
+   <screen>
       C:\><userinput>scons -Q</userinput>
       key = OBJSUFFIX, value = .obj
       key = LIBSUFFIX, value = .lib
       key = PROGSUFFIX, value = .exe
       scons: `.' is up to date.
-   </literallayout>
+   </screen>
+
+   <para>
+
+   If you want to loop through and print the values of
+   all of the construction variables in a construction environment,
+   the Python code to do that in sorted order might look something like:
+
+   </para>
+
+   <programlisting>
+      env = Environment()
+      dict = env.Dictionary()
+      keys = dict.keys()
+      keys.sort()
+      for key in keys:
+          print "construction variable = '%s', value = '%s'" % (key, dict[key])
+   </programlisting>
+
+ </section>
+
+ <section>
+ <title>Expanding Values From a &ConsEnv;</title>
+
+   <para>
+
+   Another way to get information from
+   a construction environment.
+   is to use the &subst; method
+   on a string containing $-expansions
+   of construction variable names.
+   As a simple example,
+   the example from the previous
+   section that used
+   <literal>env['CC']</literal>
+   to fetch the value of &CC;
+   could also be written as:
+
+   </para>
+
+   <programlisting>
+     env = Environment()
+     print "CC is:", env.subst('$CC')
+   </programlisting>
+
+   <para>
+
+   The real advantage of using
+   &subst; to expand strings is
+   that construction variables
+   in the result get
+   re-expanded until
+   there are no expansions left in the string.
+   So a simple fetch of a value like
+   <varname>$CCCOM</varname>:
+
+   </para>
+
+   <programlisting>
+     env = Environment(CCFLAGS = '-DFOO')
+     print "CCCOM is:", env['CCCOM']
+   </programlisting>
+
+   <para>
+
+   Will print the unexpanded value of &CCCOM;,
+   showing us the construction
+   variables that still need to be expanded:
+
+   </para>
+
+   <screen>
+     % <userinput>scons -Q</userinput>
+     CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
+     scons: `.' is up to date.
+   </screen>
+
+   <para>
+
+   Calling the &subst; method on <varname>$CCOM</varname>,
+   however:
+
+   </para>
+
+   <programlisting>
+     env = Environment(CCFLAGS = '-DFOO')
+     print "CCCOM is:", env.subst('$CCCOM')
+   </programlisting>
+
+   <para>
+
+   Will recursively expand all of
+   the $-prefixed construction variables,
+   showing us the final output:
+
+   </para>
+
+   <screen>
+     % <userinput>scons -Q</userinput>
+     CCCOM is: gcc -DFOO -c -o
+     scons: `.' is up to date.
+   </screen>
+
+   <para>
+
+   (Note that because we're not expanding this
+   in the context of building something
+   there are no target or source files
+   for <varname>$TARGET</varname> and <varname>$SOURCES</varname> to expand.
+
+   </para>
 
  </section>
 
@@ -735,24 +873,117 @@ environment undisturbed.
 
      <programlisting>
         env = Environment(CCFLAGS = '-DDEFINE1')
+        env.Replace(CCFLAGS = '-DDEFINE2')
+        env.Program('foo.c')
+     </programlisting>
+
+     <para>
+
+     The replacing value
+     (<literal>-DDEFINE2</literal> in the above example)
+     completely replaces the value in the
+     construction environment:
+
+     </para>
+
+     <screen>
+        % <userinput>scons -Q</userinput>
+        cc -DDEFINE2 -c -o foo.o foo.c
+        cc -o foo foo.o
+     </screen>
+
+     <para>
+
+     You can safely call &Replace;
+     for construction variables that
+     don't exist in the construction environment:
+
+     </para>
+
+     <programlisting>
+        env = Environment()
+        env.Replace(NEW_VARIABLE = 'xyzzy')
+        print "NEW_VARIABLE =", env['NEW_VARIABLE']
+     </programlisting>
+
+     <para>
+
+     In this case,
+     the construction variable simply
+     gets added to the construction environment:
+
+     </para>
+
+     <screen>
+        % <userinput>scons -Q</userinput>
+        NEW_VARIABLE = xyzzy
+        scons: `.' is up to date.
+     </screen>
+
+     <para>
+
+     Because the variables
+     aren't expanded until the construction environment
+     is actually used to build the targets,
+     and because &SCons; function and method calls
+     are order-independent,
+     the last replacement "wins"
+     and is used to build all targets,
+     regardless of the order in which
+     the calls to Replace() are
+     interspersed with calls to
+     builder methods:
+
+     </para>
+
+     <programlisting>
+        env = Environment(CCFLAGS = '-DDEFINE1')
+        print "CCFLAGS =", env['CCFLAGS']
         env.Program('foo.c')
+
         env.Replace(CCFLAGS = '-DDEFINE2')
+        print "CCFLAGS =", env['CCFLAGS']
         env.Program('bar.c')
      </programlisting>
 
      <para>
 
-     The replaced value completely overwrites
+     The timing of when the replacement
+     actually occurs relative
+     to when the targets get built
+     becomes apparent
+     if we run &scons; without the <literal>-Q</literal>
+     option:
 
      </para>
 
-     <literallayout>
-        % <userinput>scons -Q</userinput>
+     <screen>
+        % <userinput>scons</userinput>
+        scons: Reading SConscript files ...
+        CCFLAGS = -DDEFINE1
+        CCFLAGS = -DDEFINE2
+        scons: done reading SConscript files.
+        scons: Building targets ...
         cc -DDEFINE2 -c -o bar.o bar.c
         cc -o bar bar.o
-        cc -DDEFINE1 -c -o foo.o foo.c
+        cc -DDEFINE2 -c -o foo.o foo.c
         cc -o foo foo.o
-     </literallayout>
+        scons: done building targets.
+     </screen>
+
+     <para>
+
+     Because the replacement occurs while
+     the &SConscript; files are being read,
+     the <literal>$CCFLAGS</literal>
+     variable has already been set to
+     <literal>-DDEFINE2</literal>
+     by the time the &foo_o; target is built,
+     even though the call to the &Replace;
+     method does not occur until later in
+     the &SConscript; file.
+
+     </para>
 
    </section>
 
@@ -773,11 +1004,43 @@ environment undisturbed.
         env.Program('foo.c')
      </programlisting>
 
-     <literallayout>
+     <para>
+
+     &SCons; then supplies both the <literal>-DMY_VALUE</literal> and
+     <literal>-DLAST</literal> flags when compiling the object file:
+
+     </para>
+
+     <screen>
         % <userinput>scons -Q</userinput>
         cc -DMY_VALUE -DLAST -c -o foo.o foo.c
         cc -o foo foo.o
-     </literallayout>
+     </screen>
+
+     <para>
+
+     If the construction variable doesn't already exist,
+     the &Append; method will create it:
+
+     </para>
+
+     <programlisting>
+        env = Environment()
+        env.Append(NEW_VARIABLE = 'added')
+        print "NEW_VARIABLE =", env['NEW_VARIABLE']
+     </programlisting>
+
+     <para>
+
+     Which yields:
+
+     </para>
+
+     <screen>
+        % <userinput>scons -Q</userinput>
+        NEW_VARIABLE = added
+        scons: `.' is up to date.
+     </screen>
 
    </section>
 
@@ -798,11 +1061,43 @@ environment undisturbed.
         env.Program('foo.c')
      </programlisting>
 
-     <literallayout>
+     <para>
+
+     &SCons; then supplies both the <literal>-DFIRST</literal> and
+     <literal>-DMY_VALUE</literal> flags when compiling the object file:
+
+     </para>
+
+     <screen>
         % <userinput>scons -Q</userinput>
         cc -DFIRST -DMY_VALUE -c -o foo.o foo.c
         cc -o foo foo.o
-     </literallayout>
+     </screen>
+
+     <para>
+
+     If the construction variable doesn't already exist,
+     the &Prepend; method will create it:
+
+     </para>
+
+     <programlisting>
+        env = Environment()
+        env.Prepend(NEW_VARIABLE = 'added')
+        print "NEW_VARIABLE =", env['NEW_VARIABLE']
+     </programlisting>
+
+     <para>
+
+     Which yields:
+
+     </para>
+
+     <screen>
+        % <userinput>scons -Q</userinput>
+        NEW_VARIABLE = added
+        scons: `.' is up to date.
+     </screen>
 
    </section>