From 72c578fd4b0b4a5a43e18594339ac4ff26c376dc Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 2 Jan 2010 20:56:27 +0100 Subject: Imported Upstream version 1.2.0.d20091224 --- doc/user/misc.in | 606 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 606 insertions(+) create mode 100644 doc/user/misc.in (limited to 'doc/user/misc.in') diff --git a/doc/user/misc.in b/doc/user/misc.in new file mode 100644 index 0000000..6679134 --- /dev/null +++ b/doc/user/misc.in @@ -0,0 +1,606 @@ + + + + + &SCons; supports a lot of additional functionality + that doesn't readily fit into the other chapters. + + + +
+ Verifying the Python Version: the &EnsurePythonVersion; Function + + + + Although the &SCons; code itself will run + on any Python version 1.5.2 or later, + you are perfectly free to make use of + Python syntax and modules from more modern versions + (for example, Python 2.4 or 2.5) + when writing your &SConscript; files + or your own local modules. + If you do this, it's usually helpful to + configure &SCons; to exit gracefully with an error message + if it's being run with a version of Python + that simply won't work with your code. + This is especially true if you're going to use &SCons; + to build source code that you plan to distribute publicly, + where you can't be sure of the Python version + that an anonymous remote user might use + to try to build your software. + + + + + + &SCons; provides an &EnsurePythonVersion; function for this. + You simply pass it the major and minor versions + numbers of the version of Python you require: + + + + + + + EnsurePythonVersion(2, 5) + + + + + And then &SCons will exit with the following error + message when a user runs it with an unsupported + earlier version of Python: + + + + + + + % scons -Q + Python 2.5 or greater required, but you have Python 2.3.6 + + +
+ +
+ Verifying the SCons Version: the &EnsureSConsVersion; Function + + + + You may, of course, write your &SConscript; files + to use features that were only added in + recent versions of &SCons;. + When you publicly distribute software that is built using &SCons;, + it's helpful to have &SCons; + verify the version being used and + exit gracefully with an error message + if the user's version of &SCons; won't work + with your &SConscript; files. + &SCons; provides an &EnsureSConsVersion; function + that verifies the version of &SCons; + in the same + the &EnsurePythonVersion; function + verifies the version of Python, + by passing in the major and minor versions + numbers of the version of SCons you require: + + + + + + + EnsureSConsVersion(1, 0) + + + + + And then &SCons will exit with the following error + message when a user runs it with an unsupported + earlier version of &SCons;: + + + + + + + % scons -Q + SCons 1.0 or greater required, but you have SCons 0.98.5 + + +
+ +
+ Explicitly Terminating &SCons; While Reading &SConscript; Files: the &Exit; Function + + + + &SCons; supports an &Exit; function + which can be used to terminate &SCons; + while reading the &SConscript; files, + usually because you've detected a condition + under which it doesn't make sense to proceed: + + + + + + if ARGUMENTS.get('FUTURE'): + print "The FUTURE option is not supported yet!" + Exit(2) + env = Environment() + env.Program('hello.c') + + + hello.c + + + + + scons -Q FUTURE=1 + scons -Q + + + + + The &Exit; function takes as an argument + the (numeric) exit status that you want &SCons; to exit with. + If you don't specify a value, + the default is to exit with 0, + which indicates successful execution. + + + + + + Note that the &Exit; function + is equivalent to calling the Python + sys.exit function + (which the it actually calls), + but because &Exit; is a &SCons; function, + you don't have to import the Python + sys module to use it. + + + +
+ +
+ Searching for Files: the &FindFile; Function + + + + The &FindFile; function searches for a file in a list of directories. + If there is only one directory, it can be given as a simple string. + The function returns a File node if a matching file exists, + or None if no file is found. + (See the documentation for the &Glob; function for an alternative way + of searching for entries in a directory.) + + + + + + # one directory + print FindFile('missing', '.') + t = FindFile('exists', '.') + print t.__class__, t + + + exists + + + + + scons -Q + + + + + # 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) + + + exists + + + + + + exists + + + + exists + + + + scons -Q + + + + + + + If the file exists in more than one directory, + only the first occurrence is returned. + + + + + + print FindFile('multiple', ['sub1', 'sub2', 'sub3']) + print FindFile('multiple', ['sub2', 'sub3', 'sub1']) + print FindFile('multiple', ['sub3', 'sub1', 'sub2']) + + + + exists + + + + exists + + + + exists + + + + + scons -Q + + + + + + + In addition to existing files, &FindFile; will also find derived files + (that is, non-leaf files) that haven't been built yet. + (Leaf files should already exist, or the build will fail!) + + + + + + # Neither file exists, so build will fail + Command('derived', 'leaf', 'cat >$TARGET $SOURCE') + print FindFile('leaf', '.') + print FindFile('derived', '.') + + + + + scons -Q + + + + + # Only 'leaf' exists + Command('derived', 'leaf', 'cat >$TARGET $SOURCE') + print FindFile('leaf', '.') + print FindFile('derived', '.') + + + leaf + + + + + scons -Q + + + + + If a source file exists, &FindFile; will correctly return the name + in the build directory. + + + + + + # Only 'src/leaf' exists + VariantDir('build', 'src') + print FindFile('leaf', 'build') + + + + leaf + + + + + scons -Q + + +
+ +
+ Handling Nested Lists: the &Flatten; Function + + + + &SCons; supports a &Flatten; function + which takes an input Python sequence + (list or tuple) + and returns a flattened list + containing just the individual elements of + the sequence. + This can be handy when trying to examine + a list composed of the lists + returned by calls to various Builders. + For example, you might collect + object files built in different ways + into one call to the &Program; Builder + by just enclosing them in a list, as follows: + + + + + + objects = [ + Object('prog1.c'), + Object('prog2.c', CCFLAGS='-DFOO'), + ] + Program(objects) + + + prog1.c + + + prog2.c + + + + + + Because the Builder calls in &SCons; + flatten their input lists, + this works just fine to build the program: + + + + + scons -Q + + + + + But if you were debugging your build + and wanted to print the absolute path + of each object file in the + objects list, + you might try the following simple approach, + trying to print each Node's + abspath + attribute: + + + + + + objects = [ + Object('prog1.c'), + Object('prog2.c', CCFLAGS='-DFOO'), + ] + Program(objects) + + for object_file in objects: + print object_file.abspath + + + prog1.c + + + prog2.c + + + + + + This does not work as expected + because each call to str + is operating an embedded list returned by + each &Object; call, + not on the underlying Nodes within those lists: + + + + + scons -Q + + + + + The solution is to use the &Flatten; function + so that you can pass each Node to + the str separately: + + + + + + objects = [ + Object('prog1.c'), + Object('prog2.c', CCFLAGS='-DFOO'), + ] + Program(objects) + + for object_file in Flatten(objects): + print object_file.abspath + + + prog1.c + + + prog2.c + + + + + + + % scons -Q + /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 + + +
+ +
+ Finding the Invocation Directory: the &GetLaunchDir; Function + + + + If you need to find the directory from + which the user invoked the &scons; command, + you can use the &GetLaunchDir; function: + + + + + env = Environment( + LAUNCHDIR = GetLaunchDir(), + ) + env.Command('directory_build_info', + '$LAUNCHDIR/build_info' + Copy('$TARGET', '$SOURCE')) + + + + + Because &SCons; is usually invoked from the top-level + directory in which the &SConstruct; file lives, + the Python os.getcwd() + is often equivalent. + However, the &SCons; + -u, + -U + and + -D + command-line options, + when invoked from a subdirectory, + will cause &SCons; to change to the directory + in which the &SConstruct; file is found. + When those options are used, + &GetLaunchDir; will still return the path to the + user's invoking subdirectory, + allowing the &SConscript; configuration + to still get at configuration (or other) files + from the originating directory. + + + +
-- cgit v1.2.3