diff options
Diffstat (limited to 'doc/user/misc.xml')
| -rw-r--r-- | doc/user/misc.xml | 408 |
1 files changed, 236 insertions, 172 deletions
diff --git a/doc/user/misc.xml b/doc/user/misc.xml index 524bca3..1d892a4 100644 --- a/doc/user/misc.xml +++ b/doc/user/misc.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-misc" + 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>Miscellaneous Functionality</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 @@ -68,17 +89,17 @@ regardless of executing Python version by faking out the infrastructure in some way. - <scons_example name="EnsurePythonVersion"> + <scons_example name="misc_EnsurePythonVersion"> <file name="SConstruct" printme="1"> - EnsurePythonVersion(2, 5) +EnsurePythonVersion(2, 5) </file> </scons_example> --> - <programlisting> - EnsurePythonVersion(2, 5) - </programlisting> + <sconstruct> +EnsurePythonVersion(2, 5) + </sconstruct> <para> @@ -94,15 +115,15 @@ regardless of executing Python version by faking out the infrastructure in some way. - <scons_output example="EnsurePythonVersion"> + <scons_output example="misc_EnsurePythonVersion" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> <screen> - % <userinput>scons -Q</userinput> - Python 2.5 or greater required, but you have Python 2.3.6 +% <userinput>scons -Q</userinput> +Python 2.5 or greater required, but you have Python 2.3.6 </screen> </section> @@ -137,17 +158,17 @@ regardless of executing SCons version by faking out the infrastructure in some way. - <scons_example name="EnsureSConsVersion"> + <scons_example name="misc_EnsureSConsVersion"> <file name="SConstruct" printme="1"> - EnsureSConsVersion(1, 0) +EnsureSConsVersion(1, 0) </file> </scons_example> --> - <programlisting> - EnsureSConsVersion(1, 0) - </programlisting> + <sconstruct> +EnsureSConsVersion(1, 0) + </sconstruct> <para> @@ -163,15 +184,15 @@ regardless of executing SCons version by faking out the infrastructure in some way. - <scons_output example="EnsureSConsVersion"> + <scons_output example="misc_EnsureSConsVersion" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> <screen> - % <userinput>scons -Q</userinput> - SCons 1.0 or greater required, but you have SCons 0.98.5 +% <userinput>scons -Q</userinput> +SCons 1.0 or greater required, but you have SCons 0.98.5 </screen> </section> @@ -189,21 +210,23 @@ </para> - <programlisting> - if ARGUMENTS.get('FUTURE'): - print "The FUTURE option is not supported yet!" - Exit(2) - env = Environment() - env.Program('hello.c') - </programlisting> + <scons_example name="misc_Exit"> + <file name="SConstruct" printme="1"> +if ARGUMENTS.get('FUTURE'): + print "The FUTURE option is not supported yet!" + Exit(2) +env = Environment() +env.Program('hello.c') + </file> + <file name="hello.c"> +hello.c + </file> + </scons_example> - <screen> - % <userinput>scons -Q FUTURE=1</userinput> - The FUTURE option is not supported yet! - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="misc_Exit" suffix="1"> + <scons_output_command>scons -Q FUTURE=1</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -243,36 +266,47 @@ </para> - <programlisting> - # one directory - print FindFile('missing', '.') - t = FindFile('exists', '.') - print t.__class__, t - </programlisting> + <scons_example name="misc_FindFile1a"> + <file name="SConstruct" printme="1"> +# one directory +print FindFile('missing', '.') +t = FindFile('exists', '.') +print t.__class__, t + </file> + <file name="exists"> + exists + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - None - <class 'SCons.Node.FS.File'> exists - scons: `.' is up to date. - </screen> + <scons_output example="misc_FindFile1a" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> - <programlisting> - # several directories - includes = [ '.', 'include', 'src/include'] - headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] - for hdr in headers: - print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes) - </programlisting> + <scons_example name="misc_FindFile1b"> + <file name="SConstruct" printme="1"> +# several directories +includes = [ '.', 'include', 'src/include'] +headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] +for hdr in headers: + print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes) + </file> + <file name="config.h"> +exists + </file> + <directory name="src"></directory> + <directory name="src/include"></directory> + <file name="src/include/private.h"> +exists + </file> + <directory name="include"></directory> + <file name="include/dist.h"> +exists + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - nonesuch.h: None - config.h: config.h - private.h: src/include/private.h - dist.h: include/dist.h - scons: `.' is up to date. - </screen> + <scons_output example="misc_FindFile1b" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <!-- The man page says this should work, but it fails. <para> @@ -282,28 +316,28 @@ </para> - <scons_example name="FindFile1c"> + <scons_example name="misc_FindFile1c"> <file name="SConstruct" printme="1"> - # several directories - includes = [ '.', 'include', 'src/include'] - headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] - print FindFile(headers, includes) +# several directories +includes = [ '.', 'include', 'src/include'] +headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] +print FindFile(headers, includes) </file> <file name="config.h"> - exists +exists </file> <directory name="src"></directory> <directory name="src/include"></directory> </file> <file name="src/include/private.h"> - exists +exists <directory name="include"></directory> </file> <file name="include/dist.h"> - exists +exists </scons_example> - <scons_output example="FindFile1c" os="posix"> + <scons_output example="misc_FindFile1c" os="posix" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> @@ -315,19 +349,29 @@ </para> - <programlisting> - print FindFile('multiple', ['sub1', 'sub2', 'sub3']) - print FindFile('multiple', ['sub2', 'sub3', 'sub1']) - print FindFile('multiple', ['sub3', 'sub1', 'sub2']) - </programlisting> + <scons_example name="misc_FindFile1d"> + <file name="SConstruct" printme="1"> +print FindFile('multiple', ['sub1', 'sub2', 'sub3']) +print FindFile('multiple', ['sub2', 'sub3', 'sub1']) +print FindFile('multiple', ['sub3', 'sub1', 'sub2']) + </file> + <directory name="sub1"></directory> + <file name="sub1/multiple"> +exists + </file> + <directory name="sub2"></directory> + <file name="sub2/multiple"> +exists + </file> + <directory name="sub3"></directory> + <file name="sub3/multiple"> +exists + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - sub1/multiple - sub2/multiple - sub3/multiple - scons: `.' is up to date. - </screen> + <scons_output example="misc_FindFile1d" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <!-- file may be a list of file names or a single file name. --> @@ -339,38 +383,34 @@ </para> - <programlisting> - # Neither file exists, so build will fail - Command('derived', 'leaf', 'cat >$TARGET $SOURCE') - print FindFile('leaf', '.') - print FindFile('derived', '.') - </programlisting> - - <screen> - % <userinput>scons -Q</userinput> - None - derived - scons: *** [derived] Source `leaf' not found, needed by target `derived'. - </screen> + <scons_example name="misc_FindFile2"> + <file name="SConstruct" printme="1"> +# Neither file exists, so build will fail +Command('derived', 'leaf', 'cat >$TARGET $SOURCE') +print FindFile('leaf', '.') +print FindFile('derived', '.') + </file> + </scons_example> - <programlisting> - # Neither file exists, so build will fail - Command('derived', 'leaf', 'cat >$TARGET $SOURCE') - print FindFile('leaf', '.') - print FindFile('derived', '.') + <scons_output example="misc_FindFile2" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> - # Only 'leaf' exists - Command('derived', 'leaf', 'cat >$TARGET $SOURCE') - print FindFile('leaf', '.') - print FindFile('derived', '.') - </programlisting> + <scons_example name="misc_FindFile2"> + <file name="SConstruct" printme="1"> +# Only 'leaf' exists +Command('derived', 'leaf', 'cat >$TARGET $SOURCE') +print FindFile('leaf', '.') +print FindFile('derived', '.') + </file> + <file name="leaf"> +leaf + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - leaf - derived - cat > derived leaf - </screen> + <scons_output example="misc_FindFile2" os="posix" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -379,17 +419,21 @@ </para> - <programlisting> - # Only 'src/leaf' exists - VariantDir('build', 'src') - print FindFile('leaf', 'build') - </programlisting> + <scons_example name="misc_FindFile3"> + <file name="SConstruct" printme="1"> +# Only 'src/leaf' exists +VariantDir('build', 'src') +print FindFile('leaf', 'build') + </file> + <directory name="src"></directory> + <file name="src/leaf"> +leaf + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - build/leaf - scons: `.' is up to date. - </screen> + <scons_output example="misc_FindFile3" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -414,13 +458,21 @@ </para> - <programlisting> - objects = [ - Object('prog1.c'), - Object('prog2.c', CCFLAGS='-DFOO'), - ] - Program(objects) - </programlisting> + <scons_example name="misc_Flatten1"> + <file name="SConstruct" printme="1"> +objects = [ + Object('prog1.c'), + Object('prog2.c', CCFLAGS='-DFOO'), +] +Program(objects) + </file> + <file name="prog1.c"> +prog1.c + </file> + <file name="prog2.c"> +prog2.c + </file> + </scons_example> <para> @@ -430,12 +482,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o prog1.o -c prog1.c - cc -o prog2.o -c -DFOO prog2.c - cc -o prog1 prog1.o prog2.o - </screen> + <scons_output example="misc_Flatten1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -450,16 +499,24 @@ </para> - <programlisting> - objects = [ - Object('prog1.c'), - Object('prog2.c', CCFLAGS='-DFOO'), - ] - Program(objects) - - for object_file in objects: - print object_file.abspath - </programlisting> + <scons_example name="misc_Flatten2"> + <file name="SConstruct" printme="1"> +objects = [ + Object('prog1.c'), + Object('prog2.c', CCFLAGS='-DFOO'), +] +Program(objects) + +for object_file in objects: + print object_file.abspath + </file> + <file name="prog1.c"> +prog1.c + </file> + <file name="prog2.c"> +prog2.c + </file> + </scons_example> <para> @@ -471,12 +528,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - AttributeError: 'NodeList' object has no attribute 'abspath': - File "/home/my/project/SConstruct", line 8: - print object_file.abspath - </screen> + <scons_output example="misc_Flatten2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -486,34 +540,42 @@ </para> - <programlisting> - objects = [ - Object('prog1.c'), - Object('prog2.c', CCFLAGS='-DFOO'), - ] - Program(objects) - - for object_file in Flatten(objects): - print object_file.abspath - </programlisting> + <scons_example name="misc_Flatten3"> + <file name="SConstruct" printme="1"> +objects = [ + Object('prog1.c'), + Object('prog2.c', CCFLAGS='-DFOO'), +] +Program(objects) + +for object_file in Flatten(objects): + print object_file.abspath + </file> + <file name="prog1.c"> +prog1.c + </file> + <file name="prog2.c"> +prog2.c + </file> + </scons_example> <!-- TODO: can't use this now because it displays the temporary path name - <scons_output example="Flatten3"> + <scons_output example="misc_Flatten3" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> <screen> - % <userinput>scons -Q</userinput> - /home/me/project/prog1.o - /home/me/project/prog2.o - cc -o prog1.o -c prog1.c - cc -o prog2.o -c -DFOO prog2.c - cc -o prog1 prog1.o prog2.o +% <userinput>scons -Q</userinput> +/home/me/project/prog1.o +/home/me/project/prog2.o +cc -o prog1.o -c prog1.c +cc -o prog2.o -c -DFOO prog2.c +cc -o prog1 prog1.o prog2.o </screen> </section> @@ -529,14 +591,14 @@ </para> - <programlisting> - env = Environment( - LAUNCHDIR = GetLaunchDir(), - ) - env.Command('directory_build_info', - '$LAUNCHDIR/build_info' - Copy('$TARGET', '$SOURCE')) - </programlisting> + <sconstruct> +env = Environment( + LAUNCHDIR = GetLaunchDir(), +) +env.Command('directory_build_info', + '$LAUNCHDIR/build_info' + Copy('$TARGET', '$SOURCE')) + </sconstruct> <para> @@ -563,3 +625,5 @@ </para> </section> + +</chapter> |