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

[scons.git] / doc / user / factories.xml

diff --git a/doc/user/factories.xml b/doc/user/factories.xml
index ae6e9d03f614ffadab23566d849538627e5e3e21..9599930404c9225aaa52bed2eeb1178c5ba9710e 100644 (file)
--- 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>