From: bdbaddog <bdbaddog@fdb21ef1-2011-0410-befe-b5e4ea1792b1>
Date: Sun, 24 Aug 2008 22:37:45 +0000 (+0000)
Subject: Fix for bug #243 - document how to use Ignore() to remove a target from
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=11983445c53bddbeef249929a316bba40ce1652c;p=scons.git

Fix for bug #243 - document how to use Ignore() to remove a target from
being built as default.


git-svn-id: http://scons.tigris.org/svn/scons/trunk@3304 fdb21ef1-2011-0410-befe-b5e4ea1792b1
---

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 4cdf4ea7..b605c8bc 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -4211,11 +4211,25 @@ The specified dependency file(s)
 will be ignored when deciding if
 the target file(s) need to be rebuilt.
 
+You can also use 
+.B Ignore
+ to remove a target from the default build.
+In order to do this you must specify the directory the target will
+be built in as the target, and the file you want to skip building
+as the dependency.
+
+Note that this will only remove the dependencies listed from 
+the files built by default.  It will still be built if that 
+dependency is needed by another object being built. 
+See the third and forth examples below.
+
 Examples:
 
 .ES
 env.Ignore('foo', 'foo.c')
 env.Ignore('bar', ['bar1.h', 'bar2.h'])
+env.Ignore('.','foobar.obj')
+env.Ignore('bar','bar/foobar.obj')
 .EE
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
diff --git a/doc/user/depends.in b/doc/user/depends.in
index 13098079..8cd99703 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 61d2579b..39866e2b 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>