Fix for bug #243 - document how to use Ignore() to remove a target from

being built as default.

2 files changed, 55 insertions, 1 deletions

diff --git a/doc/user/depends.in b/doc/user/depends.in
index 1309807..8cd9970 100644
--- a/doc/user/depends.in
+++ b/doc/user/depends.in
@@ -1520,6 +1520,34 @@
        Ignore(hello, '/usr/include/stdio.h')
     </programlisting>
 
+    <para>
+    &Ignore; can also be used to prevent a generated file from being built 
+    by default. This is due to the fact that directories depend on 
+    their contents.  So to ignore a generated file from the default build, 
+    you specify that the directory should ignore the generated file.
+    Note that the file will still be built if the user specifically 
+    requests the target on scons command line, or if the file is
+    a dependency of another file which is requested and/or is built
+    by default.
+    </para>
+
+    <scons_example name="ignore_explicit">
+      <file name="SConstruct" printme="1">
+      hello_obj=Object('hello.c')
+      hello = Program(hello_obj)
+      Ignore('.',[hello,hello_obj])
+      </file>
+      <file name="hello.c">
+      #include "stdio.h"
+      int main() { printf("Hello!\n"); }
+      </file>
+    </scons_example>
+
+    <scons_output example="ignore_explicit" os="posix">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q hello</scons_output_command>
+      <scons_output_command>scons -Q hello</scons_output_command>
+    </scons_output>
   </section>
 
   <section>
diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index 61d2579..39866e2 100644
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -1478,6 +1478,32 @@
        Ignore(hello, '/usr/include/stdio.h')
     </programlisting>
 
+    <para>
+    &Ignore; can also be used to prevent a generated file from being built 
+    by default. This is due to the fact that directories depend on 
+    their contents.  So to ignore a generated file from the default build, 
+    you specify that the directory should ignore the generated file.
+    Note that the file will still be built if the user specifically 
+    requests the target on scons command line, or if the file is
+    a dependency of another file which is requested and/or is built
+    by default.
+    </para>
+
+    <programlisting>
+      hello_obj=Object('hello.c')
+      hello = Program(hello_obj)
+      Ignore('.',[hello,hello_obj])
+    </programlisting>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      scons: `.' is up to date.
+      % <userinput>scons -Q hello</userinput>
+      cc -o hello.o -c hello.c
+      cc -o hello hello.o
+      % <userinput>scons -Q hello</userinput>
+      scons: `hello' is up to date.
+    </screen>
   </section>
 
   <section>
@@ -1632,7 +1658,7 @@
       cc -o hello.o -c hello.c
       cc -o hello version.o hello.o
       % <userinput>scons -Q</userinput>
-      cc -o version.o -c version.c
+      scons: `.' is up to date.
     </screen>
 
   </section>