Imported Upstream version 2.3.1upstream/2.3.1

1 files changed, 187 insertions, 174 deletions

diff --git a/doc/user/output.xml b/doc/user/output.xml
index e33d0ad..f0d3134 100644
--- a/doc/user/output.xml
+++ b/doc/user/output.xml
@@ -1,6 +1,27 @@
+<?xml version='1.0'?>
+<!DOCTYPE sconsdoc [
+    <!ENTITY % scons SYSTEM "../scons.mod">
+    %scons;
+    
+    <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
+    %builders-mod;
+    <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
+    %functions-mod;
+    <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
+    %tools-mod;
+    <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
+    %variables-mod;
+]>
+
+<chapter id="chap-output"
+         xmlns="http://www.scons.org/dbxsd/v1.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd">
+<title>Controlling Build Output</title>
+
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -51,12 +72,14 @@
 
     </para>
 
-    <programlisting>
-       Help("""
-       Type: 'scons program' to build the production program,
-             'scons debug' to build the debug version.
-       """)
-    </programlisting>
+    <scons_example name="output_ex1">
+       <file name="SConstruct" printme="1">
+Help("""
+Type: 'scons program' to build the production program,
+      'scons debug' to build the debug version.
+""")
+       </file>
+    </scons_example>
 
     <para>
 
@@ -75,16 +98,9 @@
 
     </para>
 
-    <screen>
-       % <userinput>scons -h</userinput>
-       scons: Reading SConscript files ...
-       scons: done reading SConscript files.
-       
-       Type: 'scons program' to build the production program,
-             'scons debug' to build the debug version.
-       
-       Use scons -H for help about command-line options.
-    </screen>
+    <scons_output example="output_ex1" suffix="1">
+       <scons_output_command>scons -h</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -114,14 +130,16 @@
 
     </para>
 
-    <programlisting>
-       env = Environment()
+    <scons_example name="output_ex2">
+       <file name="SConstruct" printme="1">
+env = Environment()
 
-       Help("\nType: 'scons program' to build the production program.\n")
+Help("\nType: 'scons program' to build the production program.\n")
 
-       if env['PLATFORM'] == 'win32':
-           Help("\nType: 'scons windebug' to build the Windows debug version.\n")
-    </programlisting>
+if env['PLATFORM'] == 'win32':
+    Help("\nType: 'scons windebug' to build the Windows debug version.\n")
+       </file>
+    </scons_example>
 
     <para>
 
@@ -129,17 +147,9 @@
 
     </para>
 
-    <screen>
-       C:\><userinput>scons -h</userinput>
-       scons: Reading SConscript files ...
-       scons: done reading SConscript files.
-       
-       Type: 'scons program' to build the production program.
-       
-       Type: 'scons windebug' to build the Windows debug version.
-       
-       Use scons -H for help about command-line options.
-    </screen>
+    <scons_output example="output_ex2" os="win32" suffix="1">
+       <scons_output_command>scons -h</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -147,15 +157,9 @@
 
     </para>
 
-    <screen>
-       % <userinput>scons -h</userinput>
-       scons: Reading SConscript files ...
-       scons: done reading SConscript files.
-       
-       Type: 'scons program' to build the production program.
-       
-       Use scons -H for help about command-line options.
-    </screen>
+    <scons_output example="output_ex2" os="posix" suffix="2">
+       <scons_output_command>scons -h</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -208,11 +212,16 @@
 
     </para>
 
-    <programlisting>
-       env = Environment(CCCOMSTR = "Compiling $TARGET",
-                         LINKCOMSTR = "Linking $TARGET")
-       env.Program('foo.c')
-    </programlisting>
+    <scons_example name="output_COMSTR">
+       <file name="SConstruct" printme="1">
+env = Environment(CCCOMSTR = "Compiling $TARGET",
+                  LINKCOMSTR = "Linking $TARGET")
+env.Program('foo.c')
+       </file>
+       <file name="foo.c">
+foo.c
+       </file>
+    </scons_example>
 
     <para>
 
@@ -222,16 +231,16 @@
 
     <!--
 
-    <scons_output example="COMSTR" os="posix">
+    <scons_output example="output_COMSTR" os="posix" suffix="1">
        <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     -->
 
     <screen>
-       % <userinput>scons -Q</userinput>
-       Compiling foo.o
-       Linking foo
+% <userinput>scons -Q</userinput>
+Compiling foo.o
+Linking foo
     </screen>
 
     <para>
@@ -275,13 +284,18 @@
 
     </para>
 
-    <programlisting>
-       env = Environment()
-       if ARGUMENTS.get('VERBOSE') != "1':
-           env['CCCOMSTR'] = "Compiling $TARGET"
-           env['LINKCOMSTR'] = "Linking $TARGET"
-       env.Program('foo.c')
-    </programlisting>
+    <scons_example name="output_COMSTR-VERBOSE">
+       <file name="SConstruct" printme="1">
+env = Environment()
+if ARGUMENTS.get('VERBOSE') != "1':
+    env['CCCOMSTR'] = "Compiling $TARGET"
+    env['LINKCOMSTR'] = "Linking $TARGET"
+env.Program('foo.c')
+       </file>
+       <file name="foo.c">
+foo.c
+       </file>
+    </scons_example>
 
     <para>
 
@@ -299,7 +313,7 @@
 
     <!--
 
-    <scons_output example="COMSTR-VERBOSE" os="posix">
+    <scons_output example="output_COMSTR-VERBOSE" os="posix" suffix="1">
        <scons_output_command>scons -Q</scons_output_command>
        <scons_output_command>scons -Q -c</scons_output_command>
        <scons_output_command>scons -Q VERBOSE=1</scons_output_command>
@@ -308,15 +322,15 @@
     -->
 
     <screen>
-       % <userinput>scons -Q</userinput>
-       Compiling foo.o
-       Linking foo
-       % <userinput>scons -Q -c</userinput>
-       Removed foo.o
-       Removed foo
-       % <userinput>scons -Q VERBOSE=1</userinput>
-       cc -o foo.o -c foo.c
-       cc -o foo foo.o
+% <userinput>scons -Q</userinput>
+Compiling foo.o
+Linking foo
+% <userinput>scons -Q -c</userinput>
+Removed foo.o
+Removed foo
+% <userinput>scons -Q VERBOSE=1</userinput>
+cc -o foo.o -c foo.c
+cc -o foo foo.o
     </screen>
 
   </section>
@@ -356,11 +370,19 @@
 
     </para>
 
-    <programlisting>
-        Progress('Evaluating $TARGET\n')
-        Program('f1.c')
-        Program('f2.c')
-    </programlisting>
+    <scons_example name="output_Progress-TARGET">
+      <file name="SConstruct" printme="1">
+Progress('Evaluating $TARGET\n')
+Program('f1.c')
+Program('f2.c')
+      </file>
+      <file name="f1.c">
+f1.c
+      </file>
+      <file name="f2.c">
+f2.c
+      </file>
+    </scons_example>
 
     <para>
 
@@ -379,21 +401,9 @@
 
     </para>
 
-    <screen>
-       % <userinput>scons -Q</userinput>
-       Evaluating SConstruct
-       Evaluating f1.c
-       Evaluating f1.o
-       cc -o f1.o -c f1.c
-       Evaluating f1
-       cc -o f1 f1.o
-       Evaluating f2.c
-       Evaluating f2.o
-       cc -o f2.o -c f2.c
-       Evaluating f2
-       cc -o f2 f2.o
-       Evaluating .
-    </screen>
+    <scons_output example="output_Progress-TARGET" os="posix" suffix="1">
+       <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -414,13 +424,13 @@
 
     </para>
 
-    <programlisting>
-        Progress('$TARGET\r',
-                 file=open('/dev/tty', 'w'),
-                 overwrite=True)
-        Program('f1.c')
-        Program('f2.c')
-    </programlisting>
+    <sconstruct>
+Progress('$TARGET\r',
+         file=open('/dev/tty', 'w'),
+         overwrite=True)
+Program('f1.c')
+Program('f2.c')
+    </sconstruct>
 
     <para>
 
@@ -471,11 +481,11 @@
 
     </para>
 
-    <programlisting>
-        Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
-        Program('f1.c')
-        Program('f2.c')
-    </programlisting>
+    <sconstruct>
+Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
+Program('f1.c')
+Program('f2.c')
+    </sconstruct>
 
     <para>
 
@@ -510,15 +520,17 @@
 
     </para>
 
-    <programlisting>
-        screen = open('/dev/tty', 'w')
-        count = 0
-        def progress_function(node)
-            count += 1
-            screen.write('Node %4d: %s\r' % (count, node))
+    <scons_example name="output_Progress-callable">
+      <file name="SConstruct" printme="1">
+screen = open('/dev/tty', 'w')
+count = 0
+def progress_function(node)
+    count += 1
+    screen.write('Node %4d: %s\r' % (count, node))
 
-        Progress(progress_function)
-    </programlisting>
+Progress(progress_function)
+      </file>
+    </scons_example>
 
     <para>
 
@@ -581,15 +593,17 @@
 
     </para>
 
-    <programlisting>
-        import atexit
+    <scons_example name="output_gbf1">
+      <file name="SConstruct" printme="1">
+import atexit
 
-        def print_build_failures():
-            from SCons.Script import GetBuildFailures
-            for bf in GetBuildFailures():
-                print "%s failed: %s" % (bf.node, bf.errstr)
-        atexit.register(print_build_failures)
-    </programlisting>
+def print_build_failures():
+    from SCons.Script import GetBuildFailures
+    for bf in GetBuildFailures():
+        print "%s failed: %s" % (bf.node, bf.errstr)
+atexit.register(print_build_failures)
+      </file>
+    </scons_example>
 
     <para>
 
@@ -623,54 +637,56 @@
 
     </para>
 
-    <programlisting>
-        # Make the build fail if we pass fail=1 on the command line
-        if ARGUMENTS.get('fail', 0):
-            Command('target', 'source', ['/bin/false'])
-
-        def bf_to_str(bf):
-            """Convert an element of GetBuildFailures() to a string
-            in a useful way."""
-            import SCons.Errors
-            if bf is None: # unknown targets product None in list
-                return '(unknown tgt)'
-            elif isinstance(bf, SCons.Errors.StopError):
-                return str(bf)
-            elif bf.node:
-                return str(bf.node) + ': ' + bf.errstr
-            elif bf.filename:
-                return bf.filename + ': ' + bf.errstr
-            return 'unknown failure: ' + bf.errstr
-        import atexit
-
-        def build_status():
-            """Convert the build status to a 2-tuple, (status, msg)."""
-            from SCons.Script import GetBuildFailures
-            bf = GetBuildFailures()
-            if bf:
-                # bf is normally a list of build failures; if an element is None,
-                # it's because of a target that scons doesn't know anything about.
-                status = 'failed'
-                failures_message = "\n".join(["Failed building %s" % bf_to_str(x)
-                                   for x in bf if x is not None])
-            else:
-                # if bf is None, the build completed successfully.
-                status = 'ok'
-                failures_message = ''
-            return (status, failures_message)
-
-        def display_build_status():
-            """Display the build status.  Called by atexit.
-            Here you could do all kinds of complicated things."""
-            status, failures_message = build_status()
-            if status == 'failed':
-               print "FAILED!!!!"  # could display alert, ring bell, etc.
-            elif status == 'ok':
-               print "Build succeeded."
-            print failures_message
-
-        atexit.register(display_build_status)
-    </programlisting>
+    <scons_example name="output_gbf2">
+      <file name="SConstruct" printme="1">
+# Make the build fail if we pass fail=1 on the command line
+if ARGUMENTS.get('fail', 0):
+    Command('target', 'source', ['/bin/false'])
+
+def bf_to_str(bf):
+    """Convert an element of GetBuildFailures() to a string
+    in a useful way."""
+    import SCons.Errors
+    if bf is None: # unknown targets product None in list
+        return '(unknown tgt)'
+    elif isinstance(bf, SCons.Errors.StopError):
+        return str(bf)
+    elif bf.node:
+        return str(bf.node) + ': ' + bf.errstr
+    elif bf.filename:
+        return bf.filename + ': ' + bf.errstr
+    return 'unknown failure: ' + bf.errstr
+import atexit
+
+def build_status():
+    """Convert the build status to a 2-tuple, (status, msg)."""
+    from SCons.Script import GetBuildFailures
+    bf = GetBuildFailures()
+    if bf:
+        # bf is normally a list of build failures; if an element is None,
+        # it's because of a target that scons doesn't know anything about.
+        status = 'failed'
+        failures_message = "\n".join(["Failed building %s" % bf_to_str(x)
+                           for x in bf if x is not None])
+    else:
+        # if bf is None, the build completed successfully.
+        status = 'ok'
+        failures_message = ''
+    return (status, failures_message)
+
+def display_build_status():
+    """Display the build status.  Called by atexit.
+    Here you could do all kinds of complicated things."""
+    status, failures_message = build_status()
+    if status == 'failed':
+       print "FAILED!!!!"  # could display alert, ring bell, etc.
+    elif status == 'ok':
+       print "Build succeeded."
+    print failures_message
+
+atexit.register(display_build_status)
+      </file>
+    </scons_example>
 
     <para>
     
@@ -678,14 +694,11 @@
 
     </para>
 
-    <screen>
-          % <userinput>scons -Q</userinput>
-          scons: `.' is up to date.
-          Build succeeded.
-          % <userinput>scons -Q fail=1</userinput>
-          scons: *** [target] Source `source' not found, needed by target `target'.
-          FAILED!!!!
-          Failed building target: Source `source' not found, needed by target `target'.
-    </screen>
+    <scons_output example="output_gbf2" suffix="1">
+          <scons_output_command>scons -Q</scons_output_command>
+          <scons_output_command>scons -Q fail=1</scons_output_command>
+    </scons_output>
 
   </section>
+
+</chapter>