summaryrefslogtreecommitdiff
path: root/doc/user/output.xml
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2014-04-26 15:11:58 +0200
committerLuca Falavigna <dktrkranz@debian.org>2014-04-26 15:11:58 +0200
commit140d836e9cd54fb67b969fd82ef7ed19ba574d40 (patch)
tree0df3e32ee39603d43f9b90fd2f2e1f7cce4249d4 /doc/user/output.xml
parentcb3425abe0bc2d05caf401ca24b82a25a81f009d (diff)
Imported Upstream version 2.3.1upstream/2.3.1
Diffstat (limited to 'doc/user/output.xml')
-rw-r--r--doc/user/output.xml361
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>