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.

3 files changed, 68 insertions, 55 deletions

diff --git a/doc/scons.mod b/doc/scons.mod
index d8689098..f8d1fe05 100644
--- 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 50669737..8ba05048 100644
--- 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 8715a36a..cfff07b6 100644
--- 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>