Issue 2099: have Execute() print an error message if an action

fails.  Better document the behavior of returning the exit status,
and that exit-on-failure is the SConscript writer's responsibility.

1 files changed, 24 insertions, 2 deletions

diff --git a/doc/user/factories.xml b/doc/user/factories.xml
index ae6e9d0..9599930 100644
--- a/doc/user/factories.xml
+++ b/doc/user/factories.xml
@@ -395,11 +395,10 @@
     You can also execute an &Action; returned by a factory
     (or actually, any &Action;)
     at the time the &SConscript; file is read
-    by wrapping it up in the &Execute; function.
+    by using the &Execute; function.
     For example, if we need to make sure that
     a directory exists before we build any targets,
 
-
     </para>
 
     <programlisting>
@@ -441,4 +440,27 @@
 
     </para>
 
+    <para>
+
+    The &Execute; function returns the exit status
+    or return value of the underlying action being executed.
+    It will also print an error message if the action
+    fails and returns a non-zero value.
+    &SCons; will <emphasis>not</emphasis>, however,
+    actually stop the build if the action fails.
+    If you want the build to stop
+    in response to a failure in an action called by &Execute;,
+    you must do so by explicitly
+    checking the return value
+    and calling the &Exit; function
+    (or a Python equivalent):
+
+    </para>
+
+    <programlisting>
+    if Execute(Mkdir('/tmp/my_temp_directory')):
+        # A problem occurred while making the temp directory.
+        Exit(1)
+    </programlisting>
+
   </section>