diff options
Diffstat (limited to 'doc/user/output.xml')
| -rw-r--r-- | doc/user/output.xml | 361 |
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> |