Commits

Anonymous committed ea3b919

Initialize the new branch.

Comments (0)

Files changed (29)

 Python 1.5.2, you may not have distutils installed.  If you are running
 Python version 1.6 or later, you should be fine.
 
-NOTE TO RED HAT USERS:  All Red Hat Linux versions up to 7.3 still ship
-Python 1.5.2 as the default, so you probably do *not* have distutils
+NOTE TO RED HAT USERS:  Red Hat shipped Python 1.5.2 as the default all
+the way up to Red Hat Linux 7.3, so you probably do *not* have distutils
 installed, unless you have already done so manually or are running Red
 Hat 8.0 or later.
 
     --  (Optional.)  Install from a pre-packaged SCons package that
         does not require distutils:
 
-            Red Hat Linux       scons-0.92-1.noarch.rpm
+            Red Hat Linux       scons-0.93-1.noarch.rpm
 
-            Debian GNU/Linux    scons_0.92-1_all.deb
+            Debian GNU/Linux    scons_0.93-1_all.deb
                                 (or use apt-get)
 
-            Windows             scons-0.92.win32.exe
+            Windows             scons-0.93.win32.exe
 
     --  (Recommended.)  Download the latest distutils package from the
         following URL:
 Depending on the utilities installed on your system, any or all of the
 following packages will be built:
 
-        build/dist/scons-0.92-1.noarch.rpm
-        build/dist/scons-0.92-1.src.rpm
-        build/dist/scons-0.92.linux-i686.tar.gz
-        build/dist/scons-0.92.tar.gz
-        build/dist/scons-0.92.win32.exe
-        build/dist/scons-0.92.zip
-        build/dist/scons-doc-0.92.tar.gz
-        build/dist/scons-local-0.92.tar.gz
-        build/dist/scons-local-0.92.zip
-        build/dist/scons-src-0.92.tar.gz
-        build/dist/scons-src-0.92.zip
-        build/dist/scons_0.92-1_all.deb
+        build/dist/scons-0.93-1.noarch.rpm
+        build/dist/scons-0.93-1.src.rpm
+        build/dist/scons-0.93.linux-i686.tar.gz
+        build/dist/scons-0.93.tar.gz
+        build/dist/scons-0.93.win32.exe
+        build/dist/scons-0.93.zip
+        build/dist/scons-doc-0.93.tar.gz
+        build/dist/scons-local-0.93.tar.gz
+        build/dist/scons-local-0.93.zip
+        build/dist/scons-src-0.93.tar.gz
+        build/dist/scons-src-0.93.zip
+        build/dist/scons_0.93-1_all.deb
 
 The SConstruct file is supposed to be smart enough to avoid trying to
 build packages for which you don't have the proper utilities installed.
 import time
 
 project = 'scons'
-default_version = '0.92'
+default_version = '0.93'
 copyright = "Copyright (c) %s Steven Knight" % copyright_years
 
 Default('.')
+scons (0.93-1) unstable; urgency=low
+
+  * Fourth beta release.
+
+ -- Steven Knight <knight@baldmt.com>  Thu, 23 Oct 2003 07:26:55 -0500
+
+
 scons (0.92-1) unstable; urgency=low
 
   * Third beta release.
 <!ENTITY implicit-cache "<literal>--implicit-cache</literal>">
 <!ENTITY implicit-deps-changed "<literal>--implicit-deps-changed</literal>">
 <!ENTITY implicit-deps-unchanged "<literal>--implicit-deps-unchanged</literal>">
+<!ENTITY Q "<literal>-Q</literal>">
 
 <!--
 
 <!ENTITY Export "<function>Export</function>">
 <!ENTITY Help "<function>Help</function>">
 <!ENTITY Ignore "<function>Ignore</function>">
+<!ENTITY Import "<function>Import</function>">
 <!ENTITY Install "<function>Install</function>">
 <!ENTITY InstallAs "<function>InstallAs</function>">
 <!ENTITY Link "<function>Link</function>">
 <!ENTITY Prepend "<function>Prepend</function>">
 <!ENTITY Replace "<function>Replace</function>">
 <!ENTITY Repository "<function>Repository</function>">
+<!ENTITY Return "<function>Return</function>">
 <!ENTITY RuleSet "<function>RuleSet</function>">
 <!ENTITY Salt "<function>Salt</function>">
 <!ENTITY SetBuildSignatureType "<function>SetBuildSignatureType</function>">
 
 <!ENTITY BUILDERMAP "<varname>BUILDERMAP</varname>">
 <!ENTITY BUILDERS "<varname>BUILDERS</varname>">
+<!ENTITY LIBDIRPREFIX "<varname>LIBDIRPREFIX</varname>">
+<!ENTITY LIBDIRSUFFIX "<varname>LIBDIRSUFFIX</varname>">
+<!ENTITY LIBLINKPREFIX "<varname>LIBLINKPREFIX</varname>">
+<!ENTITY LIBLINKSUFFIX "<varname>LIBLINKSUFFIX</varname>">
+<!ENTITY LINK "<varname>LINK</varname>">
+<!ENTITY LINKCOM "<varname>LINKCOM</varname>">
+<!ENTITY LINKFLAGS "<varname>LINKFLAGS</varname>">
 <!ENTITY SCANNERMAP "<varname>SCANNERMAP</varname>">
 <!ENTITY SCANNERS "<varname>SCANNERS</varname>">
 <!ENTITY TARFLAGS "<varname>TARFLAGS</varname>">
 
 -->
 
+<!ENTITY bar "<application>bar</application>">
 <!ENTITY common1_c "<application>common1.c</application>">
 <!ENTITY common2_c "<application>common2.c</application>">
 <!ENTITY goodbye "<application>goodbye</application>">
+<!ENTITY file_dll "<application>file.dll</application>">
+<!ENTITY file_lib "<application>file.lib</application>">
+<!ENTITY file_o "<application>file.o</application>">
+<!ENTITY file_obj "<application>file.obj</application>">
+<!ENTITY foo "<application>foo</application>">
 <!ENTITY hello "<application>hello</application>">
 <!ENTITY hello_c "<filename>hello.c</filename>">
 <!ENTITY hello_exe "<filename>hello.exe</filename>">
 <!ENTITY hello_h "<filename>hello.h</filename>">
 <!ENTITY hello_o "<filename>hello.o</filename>">
+<!ENTITY libfile_a "<filename>libfile_a</filename>">
+<!ENTITY libfile_so "<filename>libfile_so</filename>">
 <!ENTITY prog "<filename>prog</filename>">
 <!ENTITY prog1 "<filename>prog1</filename>">
 <!ENTITY prog2 "<filename>prog2</filename>">

doc/user/builders-writing.in

        <file name="SConstruct">
        bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env = Environment(BUILDERS = {'Foo' : bld})
+       import os
+       env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
        env.Foo('file.foo', 'file.input')
        </file>
        <file name="file.input">
        file.input
        </file>
+       <file name="foobuild" chmod="0755">
+       cat
+       </file>
     </scons_example>
 
-    <programlisting>
+    <sconstruct>
        bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env = Environment(BUILDERS = {'Foo' : bld})
-    </programlisting>
+    </sconstruct>
 
     <para>
 
     </para>
 
     <scons_output example="ex1">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
        </file>
     </scons_example>
 
-    <!--
-      scons: Reading SConscript files ...
-      other errors
-      Traceback (most recent call last):
-        File "/usr/lib/scons/SCons/Script/__init__.py", line 901, in main
-          _main()
-        File "/usr/lib/scons/SCons/Script/__init__.py", line 762, in _main
-          SCons.Script.SConscript.SConscript(script)
-        File "/usr/lib/scons/SCons/Script/SConscript.py", line 207, in SConscript
-          exec _file_ in stack[-1].globals
-        File "SConstruct", line 4, in ?
-          env.Program('hello.c')
-      scons: Environment instance has no attribute 'Program'
-    -->
-
     <scons_output example="ex2">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
     <scons_example name="ex3">
        <file name="SConstruct">
        env = Environment()
+       import os
+       env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
        bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env.Append(BUILDERS = {'Foo' : bld})
        env.Foo('file.foo', 'file.input')
        <file name="hello.c">
        hello.c
        </file>
+       <file name="foobuild" chmod="0755">
+       cat
+       </file>
     </scons_example>
 
+    <sconstruct>
+       env = Environment()
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
+       env.Append(BUILDERS = {'Foo' : bld})
+       env.Foo('file.foo', 'file.input')
+       env.Program('hello.c')
+    </sconstruct>
+
     <para>
 
     Or you can explicitly set the appropriately-named
 
     </para>
 
-    <programlisting>
+    <sconstruct>
        env = Environment()
        bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env['BUILDERS']['Foo'] = bld
        env.Foo('file.foo', 'file.input')
        env.Program('hello.c')
-    </programlisting>
+    </sconstruct>
 
     <para>
 
     </para>
 
     <scons_output example="ex3">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
   </section>
     </para>
 
     <scons_example name="ex4">
-       <file name="SConstruct" printme="1">
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE',
+       <file name="SConstruct">
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET',
                      suffix = '.foo',
                      src_suffix = '.input')
        env = Environment(BUILDERS = {'Foo' : bld})
+       import os
+       env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
        env.Foo('file1')
        env.Foo('file2')
        </file>
        <file name="file2.input">
        file2.input
        </file>
+       <file name="foobuild" chmod="0755">
+       cat
+       </file>
     </scons_example>
 
+    <sconstruct>
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET',
+                     suffix = '.foo',
+                     src_suffix = '.input')
+       env = Environment(BUILDERS = {'Foo' : bld})
+       env.Foo('file1')
+       env.Foo('file2')
+    </sconstruct>
+
     <scons_output example="ex4">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
 
     <programlisting>
        def build_function(target, source, env):
-           # XXX
+           # Code to build "target" from "source"
            return None
     </programlisting>
 
     <scons_example name="ex5">
        <file name="SConstruct" printme="1">
        def build_function(target, source, env):
-           # XXX
+           # Code to build "target" from "source"
            return None
        bld = Builder(action = build_function,
                      suffix = '.foo',
     </para>
 
     <scons_output example="ex5">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
   </section>
 
     &SCons; Builder objects can create an action "on the fly"
     by using a function called a &generator;.
-    This provides a great deal of flexibility XXX
+    This provides a great deal of flexibility to
+    construct just the right list of commands
+    to build your target.
     A &generator; looks like:
 
     </para>
 
     <programlisting>
        def generate_actions(source, target, env, for_signature):
-           return XXX
+           return 'foobuild < %s > %s' % (target[0], source[0])
     </programlisting>
 
     <para>
       generator is being called to contribute to a build signature,
       as opposed to actually executing the command.
 
-      XXX
+      <!-- XXX NEED MORE HERE -->
 
       </para>
       </listitem>
     </para>
 
     <scons_example name="ex6">
-       <file name="SConstruct" printme="1">
+       <file name="SConstruct">
+       def generate_actions(source, target, env, for_signature):
+           return 'foobuild < %s > %s' % (source[0], target[0])
+       bld = Builder(generator = generate_actions,
+                     suffix = '.foo',
+                     src_suffix = '.input')
+       env = Environment(BUILDERS = {'Foo' : bld})
+       import os
+       env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
+       env.Foo('file')
+       </file>
+       <file name="file.input">
+       file.input
+       </file>
+       <file name="foobuild" chmod="0755">
+       cat
+       </file>
+    </scons_example>
+
+    <sconstruct>
+       def generate_actions(source, target, env, for_signature):
+           return 'foobuild < %s > %s' % (source[0], target[0])
        bld = Builder(generator = generate_actions,
                      suffix = '.foo',
                      src_suffix = '.input')
        env = Environment(BUILDERS = {'Foo' : bld})
        env.Foo('file')
-       </file>
-       <file name="file.input">
-       file.input
-       </file>
-    </scons_example>
+    </sconstruct>
 
     <scons_output example="ex6">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
     </para>
 
     <scons_example name="ex7">
-       <file name="SConstruct" printme="1">
-       def modify_targets(XXX):
-           return XXX
-       bld = Builder(action = 'XXX',
+       <file name="SConstruct">
+       def modify_targets(target, source, env):
+           target.append('new_target')
+           source.append('new_source')
+           return target, source
+       bld = Builder(action = 'foobuild $TARGETS - $SOURCES',
+                     suffix = '.foo',
+                     src_suffix = '.input',
+                     emitter = modify_targets)
+       env = Environment(BUILDERS = {'Foo' : bld})
+       import os
+       env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
+       env.Foo('file')
+       </file>
+       <file name="file.input">
+       file.input
+       </file>
+       <file name="new_source">
+       new_source
+       </file>
+       <file name="foobuild" chmod="0755">
+       cat
+       </file>
+    </scons_example>
+
+    <sconstruct>
+       def modify_targets(target, source, env):
+           target.append('new_target')
+           source.append('new_source')
+           return target, source
+       bld = Builder(action = 'foobuild $TARGETS - $SOURCES',
                      suffix = '.foo',
                      src_suffix = '.input',
                      emitter = modify_targets)
        env = Environment(BUILDERS = {'Foo' : bld})
        env.Foo('file')
-       </file>
-       <file name="file.input">
-       file.input
-       </file>
-    </programlisting>
+    </sconstruct>
 
     <scons_output example="ex7">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <programlisting>
                      suffix = '.foo',
                      src_suffix = '.input',
                      emitter = 'MY_EMITTER')
-       def modify1(XXX):
-           return XXX
-       def modify2(XXX):
-           return XXX
+       def modify1(target, source, env):
+           return target, source
+       def modify2(target, source, env):
+           return target, source
        env1 = Environment(BUILDERS = {'Foo' : bld},
                           MY_EMITTER = modify1)
        env2 = Environment(BUILDERS = {'Foo' : bld},
 
   </section>
 
+  <!--
+
   <section>
   <title>Builders That Use Other Builders</title>
 
     <scons_example name="ex8">
        <file name="SConstruct" printme="1">
        env = Environment()
-       env.SourceCode('.', env.BitKeeper('XXX'))
+       #env.SourceCode('.', env.BitKeeper('XXX'))
        env.Program('hello.c')
        </file>
-    </programlisting>
+       <file name="hello.c">
+       hello.c
+       </file>
+    </scons_example>
 
     <scons_output example="ex8">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
   </section>
+
+  -->

doc/user/builders-writing.sgml

     </para>
 
     <programlisting>
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
     </programlisting>
 
     <para>
 
     </para>
 
+    
+
     <programlisting>
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env = Environment(BUILDERS = {'Foo' : bld})
     </programlisting>
 
     </para>
 
     <literallayout>
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       foobuild < file.input > file.foo
     </literallayout>
 
     </para>
 
     <programlisting>
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env = Environment(BUILDERS = {'Foo' : bld})
        env.Foo('file.foo', 'file.input')
        env.Program('hello.c')
     </programlisting>
 
     <literallayout>
-      % <userinput>scons</userinput>
-      scons: Reading SConscript files ...
-      other errors
-      Traceback (most recent call last):
-        File "/usr/lib/scons/SCons/Script/__init__.py", line 901, in main
-          _main()
-        File "/usr/lib/scons/SCons/Script/__init__.py", line 762, in _main
-          SCons.Script.SConscript.SConscript(script)
-        File "/usr/lib/scons/SCons/Script/SConscript.py", line 207, in SConscript
-          exec _file_ in stack[-1].globals
-        File "SConstruct", line 4, in ?
-          env.Program('hello.c')
-      scons: Environment instance has no attribute 'Program'
+      % <userinput>scons -Q</userinput>
+      AttributeError: SConsEnvironment instance has no attribute 'Program':
     </literallayout>
 
     <para>
 
     </para>
 
+    
+
     <programlisting>
        env = Environment()
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env.Append(BUILDERS = {'Foo' : bld})
        env.Foo('file.foo', 'file.input')
        env.Program('hello.c')
 
     <programlisting>
        env = Environment()
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env['BUILDERS']['Foo'] = bld
        env.Foo('file.foo', 'file.input')
        env.Program('hello.c')
     </para>
 
     <literallayout>
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       foobuild < file.input > file.foo
-      cc -c hello.c -o hello.o
+      cc -c -o hello.o hello.c
       cc -o hello hello.o
     </literallayout>
 
 
     </para>
 
+    
+
     <programlisting>
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE',
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET',
                      suffix = '.foo',
                      src_suffix = '.input')
        env = Environment(BUILDERS = {'Foo' : bld})
     </programlisting>
 
     <literallayout>
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       foobuild < file1.input > file1.foo
       foobuild < file2.input > file2.foo
     </literallayout>
 
     <programlisting>
        def build_function(target, source, env):
-           # XXX
+           # Code to build "target" from "source"
            return None
     </programlisting>
 
 
     <programlisting>
        def build_function(target, source, env):
-           # XXX
+           # Code to build "target" from "source"
            return None
        bld = Builder(action = build_function,
                      suffix = '.foo',
     </para>
 
     <literallayout>
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       build_function("file.foo", "file.input")
     </literallayout>
 
 
     &SCons; Builder objects can create an action "on the fly"
     by using a function called a &generator;.
-    This provides a great deal of flexibility XXX
+    This provides a great deal of flexibility to
+    construct just the right list of commands
+    to build your target.
     A &generator; looks like:
 
     </para>
 
     <programlisting>
        def generate_actions(source, target, env, for_signature):
-           return XXX
+           return 'foobuild < %s > %s' % (target[0], source[0])
     </programlisting>
 
     <para>
       generator is being called to contribute to a build signature,
       as opposed to actually executing the command.
 
-      XXX
+      <!-- XXX NEED MORE HERE -->
 
       </para>
       </listitem>
 
     </para>
 
+    
+
     <programlisting>
+       def generate_actions(source, target, env, for_signature):
+           return 'foobuild < %s > %s' % (source[0], target[0])
        bld = Builder(generator = generate_actions,
                      suffix = '.foo',
                      src_suffix = '.input')
     </programlisting>
 
     <literallayout>
-      % <userinput>scons</userinput>
-      XXX
+      % <userinput>scons -Q</userinput>
+      foobuild < file.input > file.foo
     </literallayout>
 
     <para>
 
     </para>
 
+    
+
     <programlisting>
-       def modify_targets(XXX):
-           return XXX
-       bld = Builder(action = 'XXX',
+       def modify_targets(target, source, env):
+           target.append('new_target')
+           source.append('new_source')
+           return target, source
+       bld = Builder(action = 'foobuild $TARGETS - $SOURCES',
                      suffix = '.foo',
                      src_suffix = '.input',
                      emitter = modify_targets)
     </programlisting>
 
     <literallayout>
-      % <userinput>scons</userinput>
-      XXX
+      % <userinput>scons -Q</userinput>
+      foobuild file.foo new_target - file.input new_source
     </literallayout>
 
     <programlisting>
                      suffix = '.foo',
                      src_suffix = '.input',
                      emitter = 'MY_EMITTER')
-       def modify1(XXX):
-           return XXX
-       def modify2(XXX):
-           return XXX
+       def modify1(target, source, env):
+           return target, source
+       def modify2(target, source, env):
+           return target, source
        env1 = Environment(BUILDERS = {'Foo' : bld},
                           MY_EMITTER = modify1)
        env2 = Environment(BUILDERS = {'Foo' : bld},
 
   </section>
 
+  <!--
+
   <section>
   <title>Builders That Use Other Builders</title>
 
 
     </para>
 
-    <programlisting>
+    <scons_example name="ex8">
+       <file name="SConstruct" printme="1">
        env = Environment()
-       env.SourceCode('.', env.BitKeeper('XXX')
+       #env.SourceCode('.', env.BitKeeper('XXX'))
        env.Program('hello.c')
-    </programlisting>
+       </file>
+       <file name="hello.c">
+       hello.c
+       </file>
+    </scons_example>
 
-    <literallayout>
-      % <userinput>scons</userinput>
-      XXX
-    </literallayout>
+    <scons_output example="ex8">
+      <command>scons -Q</command>
+    </scons_output>
 
   </section>
+
+  -->
 
   <scons_example name="ex1">
     <file name="SConstruct">
-    env = Environment()
-    env.Program('hello.c')
+    Program('hello.c')
     </file>
     <file name="hello.c">
     int main() { printf("Hello, world!\n"); }
   </scons_example>
 
   <scons_output example="ex1" os="posix">
-     <command>scons</command>
-     <command>scons</command>
+     <command>scons -Q</command>
+     <command>scons -Q</command>
   </scons_output>
 
   <para>
   </para>
 
   <scons_output example="ex1" os="posix">
-     <command>scons hello</command>
-     <command>scons hello</command>
+     <command>scons -Q hello</command>
+     <command>scons -Q hello</command>
   </scons_output>
 
   <para>
       </para>
 
       <scons_output example="ex1" os="posix">
-         <command>scons hello</command>
+         <command>scons -Q hello</command>
          <command>touch hello.c</command>
-         <command>scons hello</command>
+         <command>scons -Q hello</command>
       </scons_output>
 
       <para>
       </para>
 
       <scons_output example="ex1" os="posix">
-         <command>scons hello</command>
-         <command output="[CHANGE THE CONTENTS OF hello.c]">edit hello.c</command>
-         <command>scons hello</command>
-      </scons>
-
-      <!--
-
-      <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
-         cc -o hello hello.o
-         % <userinput>edit hello.c</userinput>
-             [CHANGE THE CONTENTS OF hello.c]
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
-         cc -o hello hello.o
-         %
-      </literallayout>
-
-      -->
+         <command>scons -Q hello</command>
+         <command output="    [CHANGE THE CONTENTS OF hello.c]">edit hello.c</command>
+         <command>scons -Q hello</command>
+      </scons_output>
 
       <para>
 
       </para>
 
       <sconstruct>
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         SourceSignatures('MD5')
       </sconstruct>
 
 
       <scons_example name="ex2">
         <file name="SConstruct" printme="1">
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         SourceSignatures('timestamp')
         </file>
         <file name="hello.c">
 
       </para>
 
-      <scons_output example="ex1" os="posix">
-         <command>scons hello</command>
+      <scons_output example="ex2" os="posix">
+         <command>scons -Q hello</command>
          <command>touch hello.c</command>
-         <command>scons hello</command>
-      </scons>
+         <command>scons -Q hello</command>
+      </scons_output>
 
     </section>
 
     target file is up to date or must be rebuilt.
     When a target file depends on another target file,
     &SCons; allows you to separately configure
-    how the signatures of an "intermediate" target file
-    is used when deciding if a dependent target file
+    how the signatures of "intermediate" target files
+    are used when deciding if a dependent target file
     must be rebuilt.
 
     </para>
       </para>
 
       <scons_output example="ex1" os="posix">
-         <command>scons hello</command>
-         <command output="[CHANGE THE CONTENTS OF hello.c]">edit hello.c</command>
-         <command>scons hello</command>
-      </scons>
-
-      <!--
-
-      <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
-         cc -o hello hello.o
-         % <userinput>edit hello.c</userinput>
-           [CHANGE THE CONTENTS OF hello.c]
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
-         cc -o hello hello.o
-         %
-      </literallayout>
-
-      -->
+         <command>scons -Q hello</command>
+         <command output="    [CHANGE THE CONTENTS OF hello.c]">edit hello.c</command>
+         <command>scons -Q hello</command>
+      </scons_output>
 
       <para>
 
       </para>
 
       <sconstruct>
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         TargetSignatures('build')
       </sconstruct>
 
       If so, then any other target files
       that depend on such a built-but-not-changed target
       file actually need not be rebuilt.
-      You can have &SCons;
-      realize that a dependent target file
-      need not be rebuilt in this situation
+      You can make &SCons;
+      realize that it does not need to rebuild
+      a dependent target file in this situation
       using the &TargetSignatures; function as follows:
 
       </para>
 
       <scons_example name="ex3">
         <file name="SConstruct" printme="1">
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         TargetSignatures('content')
         </file>
         <file name="hello.c">
       </para>
 
       <scons_output example="ex3" os="posix">
-         <command>scons hello</command>
-         <command output="[CHANGE A COMMENT IN hello.c]">edit hello.c</command>
-         <command>scons hello</command>
-      </scons>
+         <command>scons -Q hello</command>
+         <command output="  [CHANGE A COMMENT IN hello.c]" edit="STRIP CCCOM line">edit hello.c</command>
+         <command>scons -Q hello</command>
+      </scons_output>
 
       <para>
 
 
     <scons_example name="ex4">
       <file name="SConstruct">
-      env = Environment(CPPPATH = '.')
-      hello = env.Program('hello.c')
+       Program('hello.c', CPPPATH = '.')
       </file>
       <file name="hello.c" printme="1">
-      #include "hello.h" 
-      int
-      main()
-      {
-          printf("Hello, %s!\n", string);
-      }
+       #include "hello.h" 
+       int
+       main()
+       {
+           printf("Hello, %s!\n", string);
+       }
       </file>
       <file name="hello.h">
-      #define string    "world"
+       #define string    "world"
       </file>
     </scons_example>
 
 
     <para>
 
-    The &CPPPATH; assignment in the &Environment; call
+    The &CPPPATH; value
     tells &SCons; to look in the current directory
     (<literal>'.'</literal>)
     for any files included by C source files
     </para>
 
     <scons_output example="ex4" os="posix">
-       <command>scons hello</command>
-       <command>scons hello</command>
-       <command output="[CHANGE THE CONTENTS IN hello.h]">edit hello.h</command>
-       <command>scons hello</command>
-    </scons>
+       <command>scons -Q hello</command>
+       <command>scons -Q hello</command>
+       <command output="    [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command>
+       <command>scons -Q hello</command>
+    </scons_output>
 
     <para>
 
 
     </para>
 
-    <programlisting>
-    </programlisting>
-
     <scons_example name="ex5">
-      <file name="SConstruct">
-      env = Environment(CPPPATH = ['include', '/home/project/inc'])
-      hello = env.Program('hello.c')
+      <file name="SConstruct" printme="1">
+       Program('hello.c', CPPPATH = ['include', '/home/project/inc'])
       </file>
       <file name="hello.c">
       int main() { printf("Hello, world!\n"); }
 
     </para>
 
-    <scons_output example="ex4" os="posix">
-       <command>scons hello</command>
+    <scons_output example="ex5" os="posix">
+       <command>scons -Q hello</command>
     </scons_output>
 
     <para>
 
     </para>
 
-    <scons_output example="ex4" os="win32">
-       <command>scons hello</command>
+    <scons_output example="ex5" os="win32">
+       <command>scons -Q hello.exe</command>
     </scons_output>
 
   </section>
     the implicit dependencies
     that its scanners find,
     for use by later builds.
-    You do this either by specifying the
+    You can do this by specifying the
     &implicit-cache; option on the command line:
 
     </para>
 
-    <scons_output example="ex1" os="win32">
-       <command>scons --implicit-cache hello</command>
-       <command>scons hello</command>
+    <scons_output example="ex1">
+       <command>scons -Q --implicit-cache hello</command>
+       <command>scons -Q hello</command>
     </scons_output>
 
     <para>
 
-    Or by setting the &implicit_cache; option
+    If you don't want to specify &implicit-cache;
+    on the command line each time,
+    you can make it the default behavior for your build
+    by setting the &implicit_cache; option
     in an &SConscript; file:
 
     </para>
        SetOption('implicit_cache', 1)
     </sconstruct>
 
+    <!--
+
+    <para>
+    
+    XXX
+
+    </para>
+
     <para>
 
     &SCons; does not cache implicit dependencies like this by default
     
     </para>
 
-    <para>
-    
-    XXX
-
-    </para>
+    -->
 
     <section>
     <title>The &implicit-deps-changed; Option</title>
 
       <para>
 
-      XXX
+      When using cached implicit dependencies,
+      sometimes you want to "start fresh"
+      and have &SCons; re-scan the files
+      for which it previously cached the dependencies.
+      For example,
+      if you have recently installed a new version of
+      external code that you use for compilation,
+      the external header files will have changed
+      and the previously-cached implicit dependencies
+      will be out of date.
+      You can update them by
+      running &SCons; with the &implicit-deps-changed; option:
+
+      </para>
+
+      <scons_output example="ex1">
+         <command>scons -Q --implicit-deps-changed hello</command>
+         <command>scons -Q hello</command>
+      </scons_output>
+
+      <para>
+
+      In this case, &SCons; will re-scan all of the implicit dependencies
+      and cache updated copies of the information.
 
       </para>
 
 
       <para>
 
-      XXX
+      By default when caching dependencies,
+      &SCons; notices when a file has been modified
+      and re-scans the file for any updated
+      implicit dependency information.
+      Sometimes, however, you may want
+      to force &SCons; to use the cached implicit dependencies, 
+      even if the source files changed.
+      This can speed up a build for example,
+      when you have changed your source files
+      but know that you haven't changed
+      any <literal>#include</literal> lines.
+      In this case,
+      you can use the &implicit-deps-unchanged; option:
+
+      </para>
+
+      <scons_output example="ex1">
+         <command>scons -Q --implicit-deps-unchanged hello</command>
+         <command>scons -Q hello</command>
+      </scons_output>
+
+      <para>
+
+      In this case,
+      &SCons; will assume that the cached implicit
+      dependencies are correct and
+      will not bother to re-scan changed files.
+      For typical builds after small,
+      incremental changes to source files,
+      the savings may not be very big,
+      but sometimes every bit of
+      improved performance counts.
 
       </para>
 
 
     </para>
 
-    <programlisting>
-       env = Environment()
-       hello = env.Program('hello.c')
-       env.Ignore(hello, 'hello.h')
-    </programlisting>
+    <scons_example name="ignore">
+      <file name="SConstruct" printme="1">
+      hello = Program('hello.c')
+      Ignore(hello, 'hello.h')
+      </file>
+      <file name="hello.c">
+      #include "hello.h" 
+      int main() { printf("Hello, %s!\n", string); }
+      </file>
+      <file name="hello.h">
+      #define string    "world"
+      </file>
+    </scons_example>
 
     <!-- XXX mention that you can use arrays for target and source? -->
 
+    <!--
+    <scons_output example="ignore">
+      <command>scons -Q hello</command>
+      <command>scons -Q hello</command>
+      <command output="    [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command>
+      <command>scons -Q hello</command>
+      XXX THIS EXAMPLE SHOULD BE UP-TO-DATE! XXX
+    </scons_output>
+    -->
+
     <literallayout>
-       % <userinput>scons hello</userinput>
-       cc -c hello.c -o hello.o
-       cc -o hello hello.o
-       % <userinput>scons hello</userinput>
-       scons: `hello' is up to date.
-       % <userinput>edit hello.h</userinput>
-           [CHANGE THE CONTENTS OF hello.h]
-       % <userinput>scons hello</userinput>
-       scons: `hello' is up to date.
+      % <userinput>scons -Q hello</userinput>
+      cc -c -o hello.o hello.c
+      cc -o hello hello.o
+      % <userinput>scons -Q hello</userinput>
+      scons: `hello' is up to date.
+      % <userinput>edit hello.h</userinput>
+        [CHANGE THE CONTENTS OF hello.h]
+      % <userinput>scons -Q hello</userinput>
+      scons: `hello' is up to date.
     </literallayout>
 
     <para>
 
     On the other hand,
     sometimes a file depends on another file
-    that has no &SCons; scanner will detect.
+    that is not detected by an &SCons; scanner.
     For this situation,
     &SCons; allows you to specific explicitly that one file
     depends on another file,
     <!-- XXX mention that you can use arrays for target and source? -->
 
     <literallayout>
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        cc -c hello.c -o hello.o
        cc -o hello hello.o
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        scons: `hello' is up to date.
        % <userinput>edit other_file</userinput>
            [CHANGE THE CONTENTS OF other_file]
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        cc -c hello.c -o hello.o
        cc -o hello hello.o
     </literallayout>

doc/user/depends.sgml

 
   </para>
 
+  
+
   <literallayout>
-     % <userinput>scons</userinput>
-     cc -c hello.c -o hello.o
+     % <userinput>scons -Q</userinput>
+     cc -c -o hello.o hello.c
      cc -o hello hello.o
-     % <userinput>scons</userinput>
-     %
+     % <userinput>scons -Q</userinput>
+     scons: `.' is up to date.
   </literallayout>
 
   <para>
   </para>
 
   <literallayout>
-     % <userinput>scons hello</userinput>
-     cc -c hello.c -o hello.o
+     % <userinput>scons -Q hello</userinput>
+     cc -c -o hello.o hello.c
      cc -o hello hello.o
-     % <userinput>scons hello</userinput>
+     % <userinput>scons -Q hello</userinput>
      scons: `hello' is up to date.
-     %
   </literallayout>
 
   <para>
       </para>
 
       <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
          % <userinput>touch hello.c</userinput>
-         % <userinput>scons hello</userinput>
+         % <userinput>scons -Q hello</userinput>
          scons: `hello' is up to date.
-         %
       </literallayout>
 
       <para>
       </para>
 
       <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
          % <userinput>edit hello.c</userinput>
              [CHANGE THE CONTENTS OF hello.c]
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
-         %
       </literallayout>
 
       <para>
       </para>
 
       <programlisting>
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         SourceSignatures('MD5')
       </programlisting>
 
       </para>
 
       <programlisting>
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         SourceSignatures('timestamp')
       </programlisting>
 
       </para>
 
       <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
          % <userinput>touch hello.c</userinput>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
-         %
       </literallayout>
 
     </section>
     target file is up to date or must be rebuilt.
     When a target file depends on another target file,
     &SCons; allows you to separately configure
-    how the signatures of an "intermediate" target file
-    is used when deciding if a dependent target file
+    how the signatures of "intermediate" target files
+    are used when deciding if a dependent target file
     must be rebuilt.
 
     </para>
       </para>
 
       <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
          % <userinput>edit hello.c</userinput>
-           [CHANGE THE CONTENTS OF hello.c]
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+             [CHANGE THE CONTENTS OF hello.c]
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
-         %
       </literallayout>
 
       <para>
       </para>
 
       <programlisting>
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         TargetSignatures('build')
       </programlisting>
 
       If so, then any other target files
       that depend on such a built-but-not-changed target
       file actually need not be rebuilt.
-      You can have &SCons;
-      realize that a dependent target file
-      need not be rebuilt in this situation
+      You can make &SCons;
+      realize that it does not need to rebuild
+      a dependent target file in this situation
       using the &TargetSignatures; function as follows:
 
       </para>
 
       <programlisting>
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         TargetSignatures('content')
       </programlisting>
 
       </para>
 
       <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
          % <userinput>edit hello.c</userinput>
            [CHANGE A COMMENT IN hello.c]
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
-         %
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
+         scons: `hello' is up to date.
       </literallayout>
 
       <para>
 
     </para>
 
+    
     <programlisting>
        #define string    "world"
-    </programlisting>
+      </programlisting>
 
     <para>
 
 
     </para>
 
+    
     <programlisting>
-       env = Environment(CPPPATH = '.')
-       hello = env.Program('hello.c')
-    </programlisting>
+       Program('hello.c', CPPPATH = '.')
+      </programlisting>
 
     <para>
 
-    The &CPPPATH; assignment in the &Environment; call
+    The &CPPPATH; value
     tells &SCons; to look in the current directory
     (<literal>'.'</literal>)
     for any files included by C source files
     </para>
 
     <literallayout>
-       % <userinput>scons hello</userinput>
-       cc -I. -c hello.c -o hello.o
+       % <userinput>scons -Q hello</userinput>
+       cc -I. -c -o hello.o hello.c
        cc -o hello hello.o
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        scons: `hello' is up to date.
        % <userinput>edit hello.h</userinput>
            [CHANGE THE CONTENTS OF hello.h]
-       % <userinput>scons hello</userinput>
-       cc -I. -c hello.c -o hello.o
+       % <userinput>scons -Q hello</userinput>
+       cc -I. -c -o hello.o hello.c
        cc -o hello hello.o
-       %
     </literallayout>
 
     <para>
     (':' on POSIX/Linux, ';' on Windows).
     Either way, &SCons; creates the
     right command-line options
-    so that the followin example:
+    so that the following example:
 
     </para>
 
     <programlisting>
-       env = Environment(CPPPATH = ['include', '/home/project/inc'])
-       hello = env.Program('hello.c')
+       Program('hello.c', CPPPATH = ['include', '/home/project/inc'])
     </programlisting>
 
     <para>
     </para>
 
     <literallayout>
-       % <userinput>scons hello</userinput>
-       cc -Iinclude -I/home/project/inc -c hello.c -o hello.o
+       % <userinput>scons -Q hello</userinput>
+       cc -Iinclude -I/home/project/inc -c -o hello.o hello.c
        cc -o hello hello.o
     </literallayout>
 
     </para>
 
     <literallayout>
-      % <userinput>scons hello</userinput>
-      cl /Iinclude /I\home\project\inc /Fohello.obj hello.c
-      link /OUT:hello.exe hello.obj
+       C:\><userinput>scons -Q hello.exe</userinput>
+       cl /nologo /Iinclude /I\home\project\inc /c hello.c /Fohello.obj
+       link /nologo /OUT:hello.exe hello.obj
     </literallayout>
 
   </section>
     the implicit dependencies
     that its scanners find,
     for use by later builds.
-    You do this either by specifying the
+    You can do this by specifying the
     &implicit-cache; option on the command line:
 
     </para>
 
     <literallayout>
-       % <userinput>scons --implicit-cache hello</userinput>
-       cc -c hello.c -o hello.o
+       % <userinput>scons -Q --implicit-cache hello</userinput>
+       cc -c -o hello.o hello.c
        cc -o hello hello.o
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        scons: `hello' is up to date.
     </literallayout>
 
     <para>
 
-    Or by setting the &implicit_cache; option
+    If you don't want to specify &implicit-cache;
+    on the command line each time,
+    you can make it the default behavior for your build
+    by setting the &implicit_cache; option
     in an &SConscript; file:
 
     </para>
 
-    <literallayout>
+    <programlisting>
        SetOption('implicit_cache', 1)
-    </literallayout>
+    </programlisting>
+
+    <!--
+
+    <para>
+    
+    XXX
+
+    </para>
 
     <para>
 
     
     </para>
 
-    <para>
-    
-    XXX
-
-    </para>
+    -->
 
     <section>
     <title>The &implicit-deps-changed; Option</title>
 
       <para>
 
-      XXX
+      When using cached implicit dependencies,
+      sometimes you want to "start fresh"
+      and have &SCons; re-scan the files
+      for which it previously cached the dependencies.
+      For example,
+      if you have recently installed a new version of
+      external code that you use for compilation,
+      the external header files will have changed
+      and the previously-cached implicit dependencies
+      will be out of date.
+      You can update them by
+      running &SCons; with the &implicit-deps-changed; option:
+
+      </para>
+
+      <literallayout>
+         % <userinput>scons -Q --implicit-deps-changed hello</userinput>
+         cc -c -o hello.o hello.c
+         cc -o hello hello.o
+         % <userinput>scons -Q hello</userinput>
+         scons: `hello' is up to date.
+      </literallayout>
+
+      <para>
+
+      In this case, &SCons; will re-scan all of the implicit dependencies
+      and cache updated copies of the information.
 
       </para>
 
 
       <para>
 
-      XXX
+      By default when caching dependencies,
+      &SCons; notices when a file has been modified
+      and re-scans the file for any updated
+      implicit dependency information.
+      Sometimes, however, you may want
+      to force &SCons; to use the cached implicit dependencies, 
+      even if the source files changed.
+      This can speed up a build for example,
+      when you have changed your source files
+      but know that you haven't changed
+      any <literal>#include</literal> lines.
+      In this case,
+      you can use the &implicit-deps-unchanged; option:
+
+      </para>
+
+      <literallayout>
+         % <userinput>scons -Q --implicit-deps-unchanged hello</userinput>
+         cc -c -o hello.o hello.c
+         cc -o hello hello.o
+         % <userinput>scons -Q hello</userinput>
+         scons: `hello' is up to date.
+      </literallayout>
+
+      <para>
+
+      In this case,
+      &SCons; will assume that the cached implicit
+      dependencies are correct and
+      will not bother to re-scan changed files.
+      For typical builds after small,
+      incremental changes to source files,
+      the savings may not be very big,
+      but sometimes every bit of
+      improved performance counts.
 
       </para>
 
     </para>
 
     <programlisting>
-       env = Environment()
-       hello = env.Program('hello.c')
-       env.Ignore(hello, 'hello.h')
+      hello = Program('hello.c')
+      Ignore(hello, 'hello.h')
     </programlisting>
 
     <!-- XXX mention that you can use arrays for target and source? -->
 
+    <!--
+    <scons_output example="ignore">
+      <command>scons -Q hello</command>
+      <command>scons -Q hello</command>
+      <command output="    [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command>
+      <command>scons -Q hello</command>
+      XXX THIS EXAMPLE SHOULD BE UP-TO-DATE! XXX
+    </scons_output>
+    -->
+
     <literallayout>
-       % <userinput>scons hello</userinput>
-       cc -c hello.c -o hello.o
-       cc -o hello hello.o
-       % <userinput>scons hello</userinput>
-       scons: `hello' is up to date.
-       % <userinput>edit hello.h</userinput>
-           [CHANGE THE CONTENTS OF hello.h]
-       % <userinput>scons hello</userinput>
-       scons: `hello' is up to date.
+      % <userinput>scons -Q hello</userinput>
+      cc -c -o hello.o hello.c
+      cc -o hello hello.o
+      % <userinput>scons -Q hello</userinput>
+      scons: `hello' is up to date.
+      % <userinput>edit hello.h</userinput>
+        [CHANGE THE CONTENTS OF hello.h]
+      % <userinput>scons -Q hello</userinput>
+      scons: `hello' is up to date.
     </literallayout>
 
     <para>
 
     On the other hand,
     sometimes a file depends on another file
-    that has no &SCons; scanner will detect.
+    that is not detected by an &SCons; scanner.
     For this situation,
     &SCons; allows you to specific explicitly that one file
     depends on another file,
     <!-- XXX mention that you can use arrays for target and source? -->
 
     <literallayout>
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        cc -c hello.c -o hello.o
        cc -o hello hello.o
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        scons: `hello' is up to date.
        % <userinput>edit other_file</userinput>
            [CHANGE THE CONTENTS OF other_file]
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        cc -c hello.c -o hello.o
        cc -o hello hello.o
     </literallayout>

doc/user/hierarchy.in

     </para>
 
     <scons_output example="ex1">
-       <command>scons</command>
+       <command>scons -Q</command>
     </scons_output>
 
     <para>
     in multiple directories, like main.c in the above example.
 
     Second, unlike standard recursive use of &Make;,
-    &SCons; stays in the top-level directory and
-    issues commands
+    &SCons; stays in the top-level directory
+    (where the &SConstruct; file lives)
+    and issues commands that use the path names
+    from the top-level directory to the
+    target and source files within the hierarchy.
 
     </para>
 
     by appending a &hash; (hash mark)
     to the beginning of the path name:
 
-
     </para>
 
     <scons_example name="ex2">
     </para>
 
     <scons_output example="ex2">
-       <command>scons</command>
+       <command>scons -Q</command>
     </scons_output>
 
     <para>
     </para>
 
     <scons_output example="ex3">
-       <command>scons</command>
+       <command>scons -Q</command>
     </scons_output>
 
     <para>
 
       There are two ways to export a variable,
       such as a construction environment,
-      from one &SConscript; file,
+      from an &SConscript; file,
       so that it may be used by other &SConscript; files.
       First, you can call the &Export;
       function with a list of variables,
 
       <para>
 
-      XXX
+      You may export more than one variable name at a time:
 
       </para>
 
 
       <para>
 
-      XXX
+      Because white space is not legal in Python variable names,
+      the &Export; function will even automatically split
+      a string into separate names for you:
 
       </para>
 
 
       <para>
 
-      XXX
+      Once a variable has been exported from a calling
+      &SConscript; file,
+      it may be used in other &SConscript; files
+      by calling the &Import; function:
 
       </para>
 
 
       <para>
 
-      XXX
+      The &Import; call makes the <literal>env</literal> construction
+      environment available to the &SConscript; file,
+      after which the variable can be used to build
+      programs, libraries, etc.
+
+      </para>
+
+      <para>
+
+      Like the &Export; function,
+      the &Import; function can be used
+      with multiple variable names:
 
       </para>
 
 
       <para>
 
-      Which is exactly equivalent to:
+      And the &Import; function will similarly
+      split a string along white-space
+      into separate variable names:
 
       </para>
 
 
       <para>
 
-      XXX
+      Lastly, as a special case,
+      you may import all of the variables that
+      have been exported by supplying an asterisk
+      to the &Import; function:
+
+      </para>
+
+      <sconstruct>
+        Import('*')
+        env = env.Copy(DEBUG = debug)
+        env.Program('prog', ['prog.c'])
+      </sconstruct>
+
+      <para>
+
+      If you're dealing with a lot of &SConscript; files,
+      this can be a lot simpler than keeping
+      arbitrary lists of imported variables in each file.
 
       </para>
 
 
       <para>
 
-      XXX
+      Sometimes, you would like to be able to
+      use information from a subsidiary
+      &SConscript file in some way.
+      For example,
+      suppose that you want to create one
+      library from source files
+      scattered throughout a number
+      of subsidiary &SConscript; files.
+      You can do this by using the &Return;
+      function to return values
+      from the subsidiary &SConscript; files
+      to the calling file.
 
       </para>
 
-      <sconstruct>
-        obj = env.Object('foo.c')
-        Return('obj')
-      </sconstruct>
+      <para>
+
+      If, for example, we have two subdirectories
+      &foo; and &bar;
+      that should each contribute a source
+      file to a Library,
+      what we'd like to be able to do is
+      collect the object files
+      from the subsidiary &SConscript; calls
+      like this:
+
+      </para>
+
+      <scons_example name="Return">
+        <file name="SConstruct" printme="1">
+          env = Environment()
+          Export('env')
+          objs = []
+          for subdir in ['foo', 'bar']:
+              o = SConscript('%s/SConscript' % subdir)
+              objs.append(o)
+          env.Library('prog', objs)
+        </file>
+        <directory name="foo"></directory>
+        <directory name="bar"></directory>
+        <file name="foo/SConscript">
+          Import('env')
+          obj = env.Object('foo.c')
+          Return('obj')
+        </file>
+        <file name="bar/SConscript">
+          Import('env')
+          obj = env.Object('bar.c')
+          Return('obj')
+        </file>
+        <file name="foo/foo.c">
+          void foo(void) { printf("foo/foo.c\n"); }
+        </file>
+        <file name="bar/bar.c">
+          void bar(void) { printf("bar/bar.c\n"); }
+        </file>
+      </scons_example>
 
       <para>
 
-      XXX
+      We can do this by using the &Return;
+      function in the
+      <literal>foo/SConscript</literal> file like this:
 
       </para>
 
-      <sconstruct>
-        objs = []
-        for subdir in ['foo', 'bar']:
-            o = SConscript('%s/SConscript' % subdir)
-            objs.append(o)
-        env.Library('prog', objs)
-      </sconstruct>
+      <scons_example_file example="Return" name="foo/SConscript">
+      </scons_example_file>
 
       <para>
 
-      XXX
+      (The corresponding
+      <literal>bar/SConscript</literal>
+      file should be pretty obvious.)
+      Then when we run &SCons;,
+      the object files from the subsidiary subdirectories
+      are all correctly archived in the desired library:
 
       </para>
 
+      <scons_output example="Return">
+        <command>scons -Q</command>
+      </scons_output>
+
     </section>
 
   </section>

doc/user/hierarchy.sgml

 
     </para>
 
+    
     <programlisting>
       env = Environment()
       env.Program('prog1', ['main.c', 'foo1.c', 'foo2.c'])
-    </programlisting>
+      </programlisting>
 
     <para>
 
 
     </para>
 
+    
     <programlisting>
       env = Environment()
       env.Program('prog2', ['main.c', 'bar1.c', 'bar2.c'])
-    </programlisting>
+      </programlisting>
 
     <para>
 
     </para>
 
     <literallayout>
-       % <userinput>scons</userinput>
-       cc -c prog1/foo1.c -o prog1/foo1.o
-       cc -c prog1/foo2.c -o prog1/foo2.o
-       cc -c prog1/main.c -o prog1/main.o
+       % <userinput>scons -Q</userinput>
+       cc -c -o prog1/foo1.o prog1/foo1.c
+       cc -c -o prog1/foo2.o prog1/foo2.c
+       cc -c -o prog1/main.o prog1/main.c
        cc -o prog1/prog1 prog1/main.o prog1/foo1.o prog1/foo2.o
-       cc -c prog2/bar1.c -o prog2/bar1.o
-       cc -c prog2/bar2.c -o prog2/bar2.o
-       cc -c prog2/main.c -o prog2/main.o
+       cc -c -o prog2/bar1.o prog2/bar1.c
+       cc -c -o prog2/bar2.o prog2/bar2.c
+       cc -c -o prog2/main.o prog2/main.c
        cc -o prog2/prog2 prog2/main.o prog2/bar1.o prog2/bar2.o
     </literallayout>
 
     in multiple directories, like main.c in the above example.
 
     Second, unlike standard recursive use of &Make;,
-    &SCons; stays in the top-level directory and
-    issues commands
+    &SCons; stays in the top-level directory
+    (where the &SConstruct; file lives)
+    and issues commands that use the path names
+    from the top-level directory to the
+    target and source files within the hierarchy.
 
     </para>
 
     by appending a &hash; (hash mark)