From a6fa9edaededa491684a874508bdf689e28f78dc Mon Sep 17 00:00:00 2001
From: Steven Knight <knight@baldmt.com>
Date: Mon, 31 Mar 2003 22:37:35 +0000
Subject: More User's Guide updates.

---
 doc/scons.mod              |  2 ++
 doc/user/depends.sgml      | 71 +++++++++++++++++++++++++--------------
 doc/user/environments.sgml | 83 ++++++++++++++++++++++++++++++++++++++++++----
 doc/user/main.sgml         |  2 +-
 doc/user/separate.sgml     |  6 ++--
 doc/user/simple.sgml       |  2 +-
 6 files changed, 131 insertions(+), 35 deletions(-)

diff --git a/doc/scons.mod b/doc/scons.mod
index 1c2653e..32283c3 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -101,6 +101,8 @@
 <!ENTITY Module "<function>Module</function>">
 <!ENTITY Objects "<function>Objects</function>">
 <!ENTITY Precious "<function>Precious</function>">
+<!ENTITY Prepend "<function>Prepend</function>">
+<!ENTITY Replace "<function>Replace</function>">
 <!ENTITY Repository "<function>Repository</function>">
 <!ENTITY RuleSet "<function>RuleSet</function>">
 <!ENTITY Salt "<function>Salt</function>">
diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml
index 8669c72..bc46618 100644
--- a/doc/user/depends.sgml
+++ b/doc/user/depends.sgml
@@ -124,10 +124,10 @@ operating system on which the build is performed (as reported by C<uname
 
     <para>
 
-    This saves time by avoiding unnecessary rebuilds when,
+    This avoids unnecessary rebuilds when,
     for example, someone rewrites the
     contents of a file without making a change.
-    But if the contents of the file change,
+    But if the contents of the file really change,
     then &SCons; detects the change
     and rebuilds the program as required:
 
@@ -145,29 +145,8 @@ operating system on which the build is performed (as reported by C<uname
        %
     </literallayout>
 
-    <para>
-
-    X
-
-    </para>
-
   </section>
 
- <!--
-
- Now it turns out that F<hello.c> also includes the interface definition
- file, F<world.h>:
-
- How does Cons know that F<hello.c> includes F<world.h>, and that F<hello.o>
- must therefore be recompiled? For now, suffice it to say that when
- considering whether or not F<hello.o> is up-to-date, Cons invokes a scanner
- for its dependency, F<hello.c>. This scanner enumerates the files included
- by F<hello.c> to come up with a list of further dependencies, beyond those
- made explicit by the Cons script. This process is recursive: any files
- included by included files will also be scanned.
-
- -->
-
   <section>
   <title>Implicit Dependencies</title>
 
@@ -257,9 +236,24 @@ operating system on which the build is performed (as reported by C<uname
 
     </para>
 
+  </section>
+
+  <section>
+  <title>Caching Implicit Dependencies</title>
+
     <para>
 
-    X
+    Scanning each file for <literal>#include</literal> lines
+    does take some extra processing time.
+    When you're doing a full build of a large system,
+    the scanning time is a small percentage
+    of the overall time spent on the build.
+    You're most likely to notice the scanning time,
+    however, when you rebuild all or part of a large system:
+    &SCons; will take some extra time to "think about"
+    what must be built before it issues the
+    first build command,
+    or decides that nothing must be rebuilt.
 
  <!--
  Isn't this expensive? The answer is, it depends. If you do a full build of a
@@ -272,6 +266,35 @@ operating system on which the build is performed (as reported by C<uname
 
     </para>
 
+    <para>
+
+    In practice, having &SCons; scan files saves time
+    relative to the amount of potential time
+    lost to tracking down subtle problems
+    introduced by incorrect dependencies.
+    Nevertheless, the "waiting time"
+    while &SCons; scans files can annoy
+    individual developers waiting for their builds.
+    Consequently, &SCons; lets you cache
+    the implicit dependencies
+
+    </para>
+
+    <literallayout>
+       % <userinput>scons --implicit-cache hello</userinput>
+       cc -c hello.c -o hello.o
+       cc -o hello hello.o
+       % <userinput>scons hello</userinput>
+       scons: `hello' is up to date.
+    </literallayout>
+
+    <para>
+
+    &SCons; does not cache implicit dependencies like this by default
+    because XXX
+
+    </para>
+
   </section>
 
   <section>
diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml
index 8117cf0..77d9c6b 100644
--- a/doc/user/environments.sgml
+++ b/doc/user/environments.sgml
@@ -592,6 +592,11 @@ environment undisturbed.
    variables when you create each &consenv;,
    you can use the &Copy; method
    to create a copy of a &consenv;.
+
+   </para>
+
+   <para>
+
    Like the &Environment; call that creates a &consenv;,
    the &Copy; method takes &consvar; assignments,
    which will override the values in the copied &consenv;.
@@ -643,16 +648,47 @@ environment undisturbed.
 
    <para>
 
-   X
+   You can fetch individual construction variables
+   using the normal Python syntax
+   for accessing individual named items in a dictionary:
+
+   </para>
+
+   <programlisting>
+      env = Environment()
+      print "CCCOM is:", env['CCCOM']
+   </programlisting>
+
+   <literallayout>
+      % <userinput>scons</userinput>
+      CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
+   </literallayout>
+
+   <para>
+
+   Note, however, that a &consenv;
+   is actually a Python 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.
+   This provides the
 
    </para>
 
    <programlisting>
       env = Environment()
+      dict = env.Dictionary()
+      # XXX SOMETHING WHERE A DICT IS NEEDED
    </programlisting>
 
+   <para>
+
+   </para>
+
    <literallayout>
       % <userinput>scons</userinput>
+      # XXX
    </literallayout>
 
  </section>
@@ -660,21 +696,42 @@ environment undisturbed.
  <section>
  <title>Modifying a &ConsEnv;</title>
 
+   <para>
+
+   &SCons; provides various methods that
+   support modifying existing values in a &consenv;.
+
+   </para>
+
    <section>
    <title>Replacing Values in a &ConsEnv;</title>
 
      <para>
 
-     X
+     You can replace existing construction variable values
+     using the &Replace; method:
 
      </para>
 
      <programlisting>
-        env = Environment()
+        env = Environment(CCFLAGS = '-DDEFINE1)
+        env.Program('foo.c')
+        env.Replace(CCFLAGS = '-DDEFINE2')
+        env.Program('bar.c')
      </programlisting>
 
+     <para>
+
+     The replaced value completely overwrites
+
+     </para>
+
      <literallayout>
         % <userinput>scons</userinput>
+        gcc -DDEFINE2 -c bar.c -o bar.o
+        gcc -o bar bar.o
+        gcc -DDEFINE2 -c foo.c -o foo.o
+        gcc -o foo foo.o
      </literallayout>
 
    </section>
@@ -684,16 +741,22 @@ environment undisturbed.
 
      <para>
 
-     X
+     You can append a value to
+     an existing construction variable
+     using the &Append; method:
 
      </para>
 
      <programlisting>
-        env = Environment()
+        env = Environment(CCFLAGS = '-DMY_VALUE')
+        env.Append(CCFLAGS = ' -DLAST')
+        env.Program('foo.c')
      </programlisting>
 
      <literallayout>
         % <userinput>scons</userinput>
+        gcc -DMY_VALUE -DLAST -c foo.c -o foo.o
+        gcc -o foo foo.o
      </literallayout>
 
    </section>
@@ -703,16 +766,22 @@ environment undisturbed.
 
      <para>
 
-     X
+     You can append a value to the beginning
+     an existing construction variable
+     using the &Prepend; method:
 
      </para>
 
      <programlisting>
-        env = Environment()
+        env = Environment(CCFLAGS = '-DMY_VALUE')
+        env.Prepend(CCFLAGS = '-DFIRST ')
+        env.Program('foo.c')
      </programlisting>
 
      <literallayout>
         % <userinput>scons</userinput>
+        gcc -DFIRST -DMY_VALUE -c foo.c -o foo.o
+        gcc -o foo foo.o
      </literallayout>
 
    </section>
diff --git a/doc/user/main.sgml b/doc/user/main.sgml
index 68bc59c..9ea4dd5 100644
--- a/doc/user/main.sgml
+++ b/doc/user/main.sgml
@@ -148,7 +148,7 @@
   </chapter>
 
   <chapter id="chap-command">
-    <title>Avoiding Having to Write Builders</title>
+    <title>Not Writing a Builder (for One-Time Builds)</title>
     &command;
   </chapter>
 
diff --git a/doc/user/separate.sgml b/doc/user/separate.sgml
index 9050eb7..21fcabc 100644
--- a/doc/user/separate.sgml
+++ b/doc/user/separate.sgml
@@ -129,7 +129,9 @@ program using the F<build/foo.c> path name.
 
    <para>
 
-   X
+   Use the &BuildDir; function to establish that target
+   files should be built in a separate directory
+   from the source files:
 
    </para>
 
@@ -141,7 +143,7 @@ program using the F<build/foo.c> path name.
 
    <para>
 
-   X
+   Note that XXX
 
    </para>
 
diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml
index a86fd34..2acd669 100644
--- a/doc/user/simple.sgml
+++ b/doc/user/simple.sgml
@@ -105,7 +105,7 @@ requirements of a build.
 
  <para>
 
- Second, notice that the same input &SConstruct; file
+ Second, notice that the same input &SConstruct; file,
  without any changes,
  generates the correct output file names on both systems:
  <filename>hello.o</filename> and <filename>hello</filename>
-- 
cgit v0.12