%scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]> &SCons; supports a lot of additional functionality that doesn't readily fit into the other chapters.

Although the &SCons; code itself will run on any 2.x Python version 2.7 or later, you are perfectly free to make use of Python syntax and modules from later versions 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

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

&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.

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

&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

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.