Fix the Requires() examples by adding a sleep command to the

infrastructure and using it to force the SConstruct file(s) to generate
version.c files with new timestamps each run.  Fix the description of
the example, since the verson.o file does get recompiled each run, but
the use of Requires() means the downstream hello executable doesn't get
relinked because of it.

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

diff --git a/bin/scons-doc.py b/bin/scons-doc.py
index 6ea429be4241e5e1b614fa16969cf37c905f00c4..e385b08118f3a37c2416bd20b5d6951467e577f3 100644 (file)
--- a/bin/scons-doc.py
+++ b/bin/scons-doc.py
@@ -490,11 +490,15 @@ def command_ls(args, c, test, dict):
     else:
         return ls(test.workpath('WORK'))
 
+def command_sleep(args, c, test, dict):
+    time.sleep(int(args[0]))
+
 CommandDict = {
     'scons' : command_scons,
     'touch' : command_touch,
     'edit'  : command_edit,
     'ls'    : command_ls,
+    'sleep' : command_sleep,
 }
 
 def ExecuteCommand(args, c, t, dict):

diff --git a/doc/scons.mod b/doc/scons.mod
index d8689098ef2b7f9fbb2205ea4b8e0c6ec0a1db1d..f8d1fe05e8dfb8baa6d7ba831c0e201e739eec16 100644 (file)
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -50,6 +50,7 @@
 <!ENTITY rmic           "<application>rmic</application>">
 <!ENTITY SCons          "<application>SCons</application>">
 <!ENTITY ScCons         "<application>ScCons</application>">
+<!ENTITY sleep          "<application>sleep</application>">
 <!ENTITY swig           "<application>swig</application>">
 <!ENTITY tar            "<application>tar</application>">
 <!ENTITY tex            "<application>tex</application>">

diff --git a/doc/user/depends.in b/doc/user/depends.in
index 50669737ee3d0800c37ba0096c07d9912015c2ee..8ba05048affde3b379e687eb68d4d7bda9606bb1 100644 (file)
--- a/doc/user/depends.in
+++ b/doc/user/depends.in
@@ -1613,7 +1613,7 @@
     <para>
 
     If we list <filename>version.c</filename> as an actual source file,
-    though, then <filename>version.o</filename>
+    though, then the <filename>version.o</filename> file
     will get rebuilt every time we run &SCons;
     (because the &SConstruct; file itself changes
     the contents of <filename>version.c</filename>)
@@ -1623,27 +1623,23 @@
 
     </para>
 
-    <!--
-
     <scons_output example="no-Requires">
-      <scons_output_command>scons -Q</scons_output_command>
-      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q hello</scons_output_command>
+      <scons_output_command>sleep 1</scons_output_command>
+      <scons_output_command>scons -Q hello</scons_output_command>
+      <scons_output_command>sleep 1</scons_output_command>
+      <scons_output_command>scons -Q hello</scons_output_command>
     </scons_output>
 
-    -->
+    <para>
 
-    <screen>
-      % <userinput>scons -Q</userinput>
-      gcc -o hello.o -c hello.c
-      gcc -o version.o -c version.c
-      gcc -o hello hello.o version.o
-      % <userinput>scons -Q</userinput>
-      gcc -o version.o -c version.c
-      gcc -o hello hello.o version.o
-      % <userinput>scons -Q</userinput>
-      gcc -o version.o -c version.c
-      gcc -o hello hello.o version.o
-    </screen>
+    (Note that for the above example to work,
+    we &sleep; for one second in between each run,
+    so that the &SConstruct; file will create a
+    <filename>version.c</filename> file with a time string
+    that's one second later than the previous run.)
+
+    </para>
 
     <para>
 
@@ -1695,19 +1691,24 @@
     <para>
 
     With these changes,
-    we get the desired behavior of
-    re-building the <filename>version.o</filename> file,
-    and therefore re-linking the <filename>hello</filename> executable,
-    only when the <filename>hello.c</filename> has changed:
+    we get the desired behavior of only
+    re-linking the <filename>hello</filename> executable
+    when the <filename>hello.c</filename> has changed,
+    even though the <filename>version.o</filename> is rebuilt
+    (because the &SConstruct; file still changes the
+    <filename>version.c</filename> contents directly each run):
 
     </para>
 
     <scons_output example="Requires">
-      <scons_output_command>scons -Q</scons_output_command>
-      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q hello</scons_output_command>
+      <scons_output_command>sleep 1</scons_output_command>
+      <scons_output_command>scons -Q hello</scons_output_command>
+      <scons_output_command>sleep 1</scons_output_command>
       <scons_output_command output="    [CHANGE THE CONTENTS OF hello.c]">edit hello.c</scons_output_command>
-      <scons_output_command>scons -Q</scons_output_command>
-      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q hello</scons_output_command>
+      <scons_output_command>sleep 1</scons_output_command>
+      <scons_output_command>scons -Q hello</scons_output_command>
     </scons_output>
 
   </section>

diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index 8715a36ac63ecb6ed660b6c250277ab35802432f..cfff07b6f8a114c6bc6ed4b2b82e617c4d5d76f3 100644 (file)
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -1563,7 +1563,7 @@
     <para>
 
     If we list <filename>version.c</filename> as an actual source file,
-    though, then <filename>version.o</filename>
+    though, then the <filename>version.o</filename> file
     will get rebuilt every time we run &SCons;
     (because the &SConstruct; file itself changes
     the contents of <filename>version.c</filename>)
@@ -1573,27 +1573,30 @@
 
     </para>
 
-    <!--
+    <screen>
+      % <userinput>scons -Q hello</userinput>
+      cc -o hello.o -c hello.c
+      cc -o version.o -c version.c
+      cc -o hello hello.o version.o
+      % <userinput>sleep 1</userinput>
+      % <userinput>scons -Q hello</userinput>
+      cc -o version.o -c version.c
+      cc -o hello hello.o version.o
+      % <userinput>sleep 1</userinput>
+      % <userinput>scons -Q hello</userinput>
+      cc -o version.o -c version.c
+      cc -o hello hello.o version.o
+    </screen>
 
-    <scons_output example="no-Requires">
-      <scons_output_command>scons -Q</scons_output_command>
-      <scons_output_command>scons -Q</scons_output_command>
-    </scons_output>
+    <para>
 
-    -->
+    (Note that for the above example to work,
+    we &sleep; for one second in between each run,
+    so that the &SConstruct; file will create a
+    <filename>version.c</filename> file with a time string
+    that's one second later than the previous run.)
 
-    <screen>
-      % <userinput>scons -Q</userinput>
-      gcc -o hello.o -c hello.c
-      gcc -o version.o -c version.c
-      gcc -o hello hello.o version.o
-      % <userinput>scons -Q</userinput>
-      gcc -o version.o -c version.c
-      gcc -o hello hello.o version.o
-      % <userinput>scons -Q</userinput>
-      gcc -o version.o -c version.c
-      gcc -o hello hello.o version.o
-    </screen>
+    </para>
 
     <para>
 
@@ -1639,27 +1642,35 @@
     <para>
 
     With these changes,
-    we get the desired behavior of
-    re-building the <filename>version.o</filename> file,
-    and therefore re-linking the <filename>hello</filename> executable,
-    only when the <filename>hello.c</filename> has changed:
+    we get the desired behavior of only
+    re-linking the <filename>hello</filename> executable
+    when the <filename>hello.c</filename> has changed,
+    even though the <filename>version.o</filename> is rebuilt
+    (because the &SConstruct; file still changes the
+    <filename>version.c</filename> contents directly each run):
 
     </para>
 
     <screen>
-      % <userinput>scons -Q</userinput>
+      % <userinput>scons -Q hello</userinput>
       cc -o version.o -c version.c
       cc -o hello.o -c hello.c
       cc -o hello version.o hello.o
-      % <userinput>scons -Q</userinput>
-      scons: `.' is up to date.
+      % <userinput>sleep 1</userinput>
+      % <userinput>scons -Q hello</userinput>
+      cc -o version.o -c version.c
+      scons: `hello' is up to date.
+      % <userinput>sleep 1</userinput>
       % <userinput>edit hello.c</userinput>
           [CHANGE THE CONTENTS OF hello.c]
-      % <userinput>scons -Q</userinput>
+      % <userinput>scons -Q hello</userinput>
+      cc -o version.o -c version.c
       cc -o hello.o -c hello.c
       cc -o hello version.o hello.o
-      % <userinput>scons -Q</userinput>
-      scons: `.' is up to date.
+      % <userinput>sleep 1</userinput>
+      % <userinput>scons -Q hello</userinput>
+      cc -o version.o -c version.c
+      scons: `hello' is up to date.
     </screen>
 
   </section>