From 140d836e9cd54fb67b969fd82ef7ed19ba574d40 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 26 Apr 2014 15:11:58 +0200 Subject: Imported Upstream version 2.3.1 --- doc/user/misc.in | 606 ------------------------------------------------------- 1 file changed, 606 deletions(-) delete mode 100644 doc/user/misc.in (limited to 'doc/user/misc.in') diff --git a/doc/user/misc.in b/doc/user/misc.in deleted file mode 100644 index 19d123f..0000000 --- a/doc/user/misc.in +++ /dev/null @@ -1,606 +0,0 @@ - - - - - &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 2.x Python version 2.4 or later, - you are perfectly free to make use of - Python syntax and modules from more modern versions - (for example, Python 2.5 or 2.6) - 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