# Miscellaneous Functionality

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

## 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 &f-link-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 &f-link-Glob; function for an alternative way of searching for entries in a directory.)

# one directory print("%s"%FindFile('missing', '.')) t = FindFile('exists', '.') print("%s %s"%(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.

## Virtual environments (virtualenvs)

Virtualenv is a tool to create isolated Python environments. A python application (such as SCons) may be executed within an activated virtualenv. The activation of virtualenv modifies current environment by defining some virtualenv-specific variables and modifying search PATH, such that executables installed within virtualenv's home directory are preferred over the ones installed outside of it.

Normally, SCons uses hard-coded PATH when searching for external executables, so it always picks-up executables from these pre-defined locations. This applies also to python interpreter, which is invoked by some custom SCons tools or test suites. This means, when running SCons in a virtualenv, an eventual invocation of python interpreter from SCons script will most probably jump out of virtualenv and execute python executable found in hard-coded SCons PATH, not the one which is executing SCons. Some users may consider this as an inconsistency.

This issue may be overcome by using the `--enable-virtualenv` option. The option automatically imports virtualenv-related environment variables to all created construction environment `env['ENV']`, and modifies SCons PATH appropriately to prefer virtualenv's executables. Setting environment variable `SCONS_ENABLE_VIRTUALENV=1` will have same effect. If virtualenv support is enabled system-vide by the environment variable, it may be suppressed with the `--ignore-virtualenv` option.

Inside of &SConscript;, a global function `Virtualenv` is available. It returns a path to virtualenv's home directory, or `None` if &scons; is not running from virtualenv. Note that this function returns a path even if &scons; is run from an unactivated virtualenv.