From 83f47c96cc4ef4659c2a1221abe04cbaeda1c1bb Mon Sep 17 00:00:00 2001
From: stevenknight <stevenknight@fdb21ef1-2011-0410-befe-b5e4ea1792b1>
Date: Sat, 16 Jan 2010 15:27:15 +0000
Subject: [PATCH] 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
---
 bin/scons-doc.py     |  4 +++
 doc/scons.mod        |  1 +
 doc/user/depends.in  | 53 +++++++++++++++++-----------------
 doc/user/depends.xml | 69 +++++++++++++++++++++++++-------------------
 4 files changed, 72 insertions(+), 55 deletions(-)

diff --git a/bin/scons-doc.py b/bin/scons-doc.py
index 6ea429be..e385b081 100644
--- 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 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>
-- 
2.26.2