Add a NoClean() function. (Steven Johnson)

7 files changed, 298 insertions, 183 deletions

diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST
index 3af2c9c..04c293b 100644
--- a/doc/user/MANIFEST
+++ b/doc/user/MANIFEST
@@ -17,6 +17,7 @@ environments.sgml
 errors.sgml
 example.sgml
 factories.sgml
+file-removal.sgml
 help.sgml
 hierarchy.sgml
 install.sgml
@@ -27,7 +28,6 @@ main.sgml
 make.sgml
 nodes.sgml
 parseconfig.sgml
-precious.sgml
 preface.sgml
 python.sgml
 repositories.sgml
diff --git a/doc/user/file-removal.in b/doc/user/file-removal.in
new file mode 100644
index 0000000..1d259bf
--- /dev/null
+++ b/doc/user/file-removal.in
@@ -0,0 +1,148 @@
+<!--
+
+  __COPYRIGHT__
+
+  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>
+
+  There are two occasions when &SCons; will,
+  by default, remove target files.
+  The first is when &SCons; determines that 
+  an target file needs to be rebuilt
+  and removes the existing version of the target
+  before executing
+  The second is when &SCons; is invoked with the
+  <literal>-c</literal> option to "clean"
+  a tree of its built targets.
+
+  These behaviours can be suppressed with the
+  &Precious; and &NoClean; functions, respectively.
+
+  </para>
+
+  <section>
+  <title>Preventing target removal during build: the &Precious; Function</title>
+
+    <para>
+    
+    By default, &SCons; removes targets before building them.
+    Sometimes, however, this is not what you want.
+    For example, you may want to update a library incrementally,
+    not by having it deleted and then rebuilt from all
+    of the constituent object files.
+    In such cases, you can use the
+    &Precious; method to prevent
+    &SCons; from removing the target before it is built:
+    
+    </para>
+    
+    <scons_example name="precious-ex1">
+      <file name="SConstruct" printme="1">
+        env = Environment(RANLIBCOM='')
+        lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+        env.Precious(lib)
+      </file>
+      <file name="f1.c">
+      int f1() { }
+      </file>
+      <file name="f2.c">
+      int f2() { }
+      </file>
+      <file name="f3.c">
+      int f3() { }
+      </file>
+    </scons_example>
+    
+    <para>
+    
+    Although the output doesn't look any different,
+    &SCons; does not, in fact,
+    delete the target library before rebuilding it:
+    
+    </para>
+    
+    <scons_output example="precious-ex1">
+        <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+    
+    <para>
+    
+    &SCons; will, however, still delete files marked as &Precious;
+    when the <literal>-c</literal> option is used.
+    
+    </para>
+
+  </section>
+
+
+  <section>
+  <title>Preventing target removal during clean: the &NoClean; Function</title>
+
+    <para>
+    
+    By default, &SCons; removes all built targets when invoked
+    with the <literal>-c</literal> option to clean a source tree
+    of built tragets.
+    Sometimes, however, this is not what you want.
+    For example, you may want to remove only intermediate generated files
+    (such as object files),
+    but leave the final targets
+    (the libraries)
+    untouched.
+    
+    In such cases, you can use the &NoClean; method to prevent &SCons;
+    from removing a target during a clean:
+    
+    </para>
+    
+    <scons_example name="noclean-ex1">
+      <file name="SConstruct" printme="1">
+        env = Environment(RANLIBCOM='')
+        lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+        env.NoClean(lib)
+      </file>
+      <file name="f1.c">
+      int f1() { }
+      </file>
+      <file name="f2.c">
+      int f2() { }
+      </file>
+      <file name="f3.c">
+      int f3() { }
+      </file>
+    </scons_example>
+    
+    <para>
+    
+    Notice that the <filename>libfoo.a</filename>
+    is not listed as a removed file:
+    
+    </para>
+    
+    <scons_output example="noclean-ex1">
+        <scons_output_command>scons -Q</scons_output_command>
+        <scons_output_command>scons -c</scons_output_command>
+    </scons_output>
+
+  </section>
+
diff --git a/doc/user/file-removal.sgml b/doc/user/file-removal.sgml
new file mode 100644
index 0000000..76a2e01
--- /dev/null
+++ b/doc/user/file-removal.sgml
@@ -0,0 +1,141 @@
+<!--
+
+  __COPYRIGHT__
+
+  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>
+
+  There are two occasions when &SCons; will,
+  by default, remove target files.
+  The first is when &SCons; determines that 
+  an target file needs to be rebuilt
+  and removes the existing version of the target
+  before executing
+  The second is when &SCons; is invoked with the
+  <literal>-c</literal> option to "clean"
+  a tree of its built targets.
+
+  These behaviours can be suppressed with the
+  &Precious; and &NoClean; functions, respectively.
+
+  </para>
+
+  <section>
+  <title>Preventing target removal during build: the &Precious; Function</title>
+
+    <para>
+    
+    By default, &SCons; removes targets before building them.
+    Sometimes, however, this is not what you want.
+    For example, you may want to update a library incrementally,
+    not by having it deleted and then rebuilt from all
+    of the constituent object files.
+    In such cases, you can use the
+    &Precious; method to prevent
+    &SCons; from removing the target before it is built:
+    
+    </para>
+    
+    <programlisting>
+        env = Environment(RANLIBCOM='')
+        lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+        env.Precious(lib)
+    </programlisting>
+    
+    <para>
+    
+    Although the output doesn't look any different,
+    &SCons; does not, in fact,
+    delete the target library before rebuilding it:
+    
+    </para>
+    
+    <screen>
+        % <userinput>scons -Q</userinput>
+        cc -o f1.o -c f1.c
+        cc -o f2.o -c f2.c
+        cc -o f3.o -c f3.c
+        ar rc libfoo.a f1.o f2.o f3.o
+    </screen>
+    
+    <para>
+    
+    &SCons; will, however, still delete files marked as &Precious;
+    when the <literal>-c</literal> option is used.
+    
+    </para>
+
+  </section>
+
+
+  <section>
+  <title>Preventing target removal during clean: the &NoClean; Function</title>
+
+    <para>
+    
+    By default, &SCons; removes all built targets when invoked
+    with the <literal>-c</literal> option to clean a source tree
+    of built tragets.
+    Sometimes, however, this is not what you want.
+    For example, you may want to remove only intermediate generated files
+    (such as object files),
+    but leave the final targets
+    (the libraries)
+    untouched.
+    
+    In such cases, you can use the &NoClean; method to prevent &SCons;
+    from removing a target during a clean:
+    
+    </para>
+    
+    <programlisting>
+        env = Environment(RANLIBCOM='')
+        lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+        env.NoClean(lib)
+    </programlisting>
+    
+    <para>
+    
+    Notice that the <filename>libfoo.a</filename>
+    is not listed as a removed file:
+    
+    </para>
+    
+    <screen>
+        % <userinput>scons -Q</userinput>
+        cc -o f1.o -c f1.c
+        cc -o f2.o -c f2.c
+        cc -o f3.o -c f3.c
+        ar rc libfoo.a f1.o f2.o f3.o
+        % <userinput>scons -c</userinput>
+        scons: Reading SConscript files ...
+        scons: done reading SConscript files.
+        scons: Cleaning targets ...
+        Removed f1.o
+        Removed f2.o
+        Removed f3.o
+        scons: done cleaning targets.
+    </screen>
+
+  </section>
+
diff --git a/doc/user/main.in b/doc/user/main.in
index a720915..af3b0ee 100644
--- a/doc/user/main.in
+++ b/doc/user/main.in
@@ -59,6 +59,7 @@
     <!ENTITY errors SYSTEM "errors.sgml">
     <!ENTITY example SYSTEM "example.sgml">
     <!ENTITY factories SYSTEM "factories.sgml">
+    <!ENTITY file-removal SYSTEM "file-removal.sgml">
     <!ENTITY help SYSTEM "help.sgml">
     <!ENTITY hierarchy SYSTEM "hierarchy.sgml">
     <!ENTITY java SYSTEM "java.sgml">
@@ -68,7 +69,6 @@
     <!ENTITY make SYSTEM "make.sgml">
     <!ENTITY nodes SYSTEM "nodes.sgml">
     <!ENTITY parseconfig SYSTEM "parseconfig.sgml">
-    <!ENTITY precious SYSTEM "precious.sgml">
     <!ENTITY preface SYSTEM "preface.sgml">
     <!ENTITY python SYSTEM "python.sgml">
     <!ENTITY repositories SYSTEM "repositories.sgml">
@@ -190,9 +190,9 @@
     &factories;
   </chapter>
 
-  <chapter id="chap-precious">
-    <title>Preventing Removal of Targets:  the &Precious; Function</title>
-    &precious;
+  <chapter id="chap-file-removal">
+    <title>Preventing Removal of Targets</title>
+    &file-removal;
   </chapter>
 
   <chapter id="chap-hierarchical">
diff --git a/doc/user/main.sgml b/doc/user/main.sgml
index a720915..af3b0ee 100644
--- a/doc/user/main.sgml
+++ b/doc/user/main.sgml
@@ -59,6 +59,7 @@
     <!ENTITY errors SYSTEM "errors.sgml">
     <!ENTITY example SYSTEM "example.sgml">
     <!ENTITY factories SYSTEM "factories.sgml">
+    <!ENTITY file-removal SYSTEM "file-removal.sgml">
     <!ENTITY help SYSTEM "help.sgml">
     <!ENTITY hierarchy SYSTEM "hierarchy.sgml">
     <!ENTITY java SYSTEM "java.sgml">
@@ -68,7 +69,6 @@
     <!ENTITY make SYSTEM "make.sgml">
     <!ENTITY nodes SYSTEM "nodes.sgml">
     <!ENTITY parseconfig SYSTEM "parseconfig.sgml">
-    <!ENTITY precious SYSTEM "precious.sgml">
     <!ENTITY preface SYSTEM "preface.sgml">
     <!ENTITY python SYSTEM "python.sgml">
     <!ENTITY repositories SYSTEM "repositories.sgml">
@@ -190,9 +190,9 @@
     &factories;
   </chapter>
 
-  <chapter id="chap-precious">
-    <title>Preventing Removal of Targets:  the &Precious; Function</title>
-    &precious;
+  <chapter id="chap-file-removal">
+    <title>Preventing Removal of Targets</title>
+    &file-removal;
   </chapter>
 
   <chapter id="chap-hierarchical">
diff --git a/doc/user/precious.in b/doc/user/precious.in
deleted file mode 100644
index f5e000b..0000000
--- a/doc/user/precious.in
+++ /dev/null
@@ -1,90 +0,0 @@
-<!--
-
-  __COPYRIGHT__
-
-  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.
-
--->
-
-<!--
-
-=head2 The C<AfterBuild> method
-
-The C<AfterBuild> method evaluates the specified perl string after
-building the given file or files (or finding that they are up to date).
-The eval will happen once per specified file.  C<AfterBuild> is called
-as follows:
-
-  AfterBuild $env 'foo.o', qq(print "foo.o is up to date!\n");
-
-The perl string is evaluated in the C<script> package, and has access
-to all variables and subroutines defined in the F<Conscript> file in
-which the C<AfterBuild> method is called.
-
--->
-
- <para>
-
- By default, &SCons; removes targets before building them.
- Sometimes, however, this is not what you want.
- For example, you may want to update a library incrementally,
- not by having it deleted and then rebuilt from all
- of the constituent object files.
- In such cases, you can use the
- &Precious; method to prevent
- &SCons; from removing the target before it is built:
-
- </para>
-
- <scons_example name="ex1">
-   <file name="SConstruct" printme="1">
-    env = Environment()
-    lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
-    env.Precious(lib)
-   </file>
-   <file name="f1.c">
-   int f1() { }
-   </file>
-   <file name="f2.c">
-   int f2() { }
-   </file>
-   <file name="f3.c">
-   int f3() { }
-   </file>
- </scons_example>
-
- <para>
-
- Although the output doesn't look any different,
- &SCons; does not, in fact,
- delete the target library before rebuilding it:
-
- </para>
-
- <scons_output example="ex1">
-    <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- &SCons; will, however, still delete files marked as &Precious;
- when the <literal>-c</literal> option is used.
-
- </para>
diff --git a/doc/user/precious.sgml b/doc/user/precious.sgml
deleted file mode 100644
index 6e80c85..0000000
--- a/doc/user/precious.sgml
+++ /dev/null
@@ -1,84 +0,0 @@
-<!--
-
-  __COPYRIGHT__
-
-  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.
-
--->
-
-<!--
-
-=head2 The C<AfterBuild> method
-
-The C<AfterBuild> method evaluates the specified perl string after
-building the given file or files (or finding that they are up to date).
-The eval will happen once per specified file.  C<AfterBuild> is called
-as follows:
-
-  AfterBuild $env 'foo.o', qq(print "foo.o is up to date!\n");
-
-The perl string is evaluated in the C<script> package, and has access
-to all variables and subroutines defined in the F<Conscript> file in
-which the C<AfterBuild> method is called.
-
--->
-
- <para>
-
- By default, &SCons; removes targets before building them.
- Sometimes, however, this is not what you want.
- For example, you may want to update a library incrementally,
- not by having it deleted and then rebuilt from all
- of the constituent object files.
- In such cases, you can use the
- &Precious; method to prevent
- &SCons; from removing the target before it is built:
-
- </para>
-
- <programlisting>
-    env = Environment()
-    lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
-    env.Precious(lib)
- </programlisting>
-
- <para>
-
- Although the output doesn't look any different,
- &SCons; does not, in fact,
- delete the target library before rebuilding it:
-
- </para>
-
- <screen>
-    % <userinput>scons -Q</userinput>
-    cc -c -o f1.o f1.c
-    cc -c -o f2.o f2.c
-    cc -c -o f3.o f3.c
-    ar r libfoo.a f1.o f2.o f3.o
-    ranlib libfoo.a
- </screen>
-
- <para>
-
- &SCons; will, however, still delete files marked as &Precious;
- when the <literal>-c</literal> option is used.
-
- </para>