SCons.Variables package

Submodules

SCons.Variables.BoolVariable module

Option type for true/false Variables.

Usage example:

opts = Variables()
opts.Add(BoolVariable('embedded', 'build for an embedded system', 0))
...
if env['embedded'] == 1:
...

SCons.Variables.BoolVariable.BoolVariable(key, help, default)

The input parameters describe a boolean option, thus they are returned with the correct converter and validator appended. The ‘help’ text will by appended by ‘(yes|no) to show the valid valued. The result is usable for input to opts.Add().

SCons.Variables.BoolVariable._text2bool(val)

Converts strings to True/False depending on the ‘truth’ expressed by the string. If the string can’t be converted, the original value will be returned.

See ‘__true_strings’ and ‘__false_strings’ for values considered ‘true’ or ‘false respectively.

This is usable as ‘converter’ for SCons’ Variables.

SCons.Variables.BoolVariable._validator(key, val, env)

Validates the given value to be either ‘0’ or ‘1’.

This is usable as ‘validator’ for SCons’ Variables.

SCons.Variables.EnumVariable module

Option type for enumeration Variables.

This file defines the option type for SCons allowing only specified input-values.

Usage example:

opts = Variables()
opts.Add(
    EnumVariable(
        'debug',
        'debug output and symbols',
        'no',
        allowed_values=('yes', 'no', 'full'),
        map={},
        ignorecase=2,
    )
)
...
if env['debug'] == 'full':
...

SCons.Variables.EnumVariable.EnumVariable(key, help, default, allowed_values, map={}, ignorecase=0)

The input parameters describe an option with only certain values allowed. They are returned with an appropriate converter and validator appended. The result is usable for input to Variables.Add().

‘key’ and ‘default’ are the values to be passed on to Variables.Add().

‘help’ will be appended by the allowed values automatically

‘allowed_values’ is a list of strings, which are allowed as values for this option.

The ‘map’-dictionary may be used for converting the input value into canonical values (e.g. for aliases).

‘ignorecase’ defines the behaviour of the validator:

If ignorecase == 0, the validator/converter are case-sensitive. If ignorecase == 1, the validator/converter are case-insensitive. If ignorecase == 2, the validator/converter is case-insensitive and the converted value will always be lower-case.

The ‘validator’ tests whether the value is in the list of allowed values. The ‘converter’ converts input values according to the given ‘map’-dictionary (unmapped input values are returned unchanged).

SCons.Variables.ListVariable module

Option type for list Variables.

This file defines the option type for SCons implementing ‘lists’.

A ‘list’ option may either be ‘all’, ‘none’ or a list of names separated by comma. After the option has been processed, the option value holds either the named list elements, all list elements or no list elements at all.

Usage example:

list_of_libs = Split('x11 gl qt ical')

opts = Variables()
opts.Add(
    ListVariable(
        'shared',
        'libraries to build as shared libraries',
        'all',
        elems=list_of_libs,
    )
)
...
for lib in list_of_libs:
    if lib in env['shared']:
        env.SharedObject(...)
    else:
        env.Object(...)

SCons.Variables.ListVariable.ListVariable(key, help, default, names, map={})

The input parameters describe a ‘package list’ option, thus they are returned with the correct converter and validator appended. The result is usable for input to opts.Add() .

A ‘package list’ option may either be ‘all’, ‘none’ or a list of package names (separated by space).

SCons.Variables.ListVariable._converter(val, allowedElems, mapdict)

SCons.Variables.PackageVariable module

Option type for package Variables.

This file defines the option type for SCons implementing ‘package activation’.

To be used whenever a ‘package’ may be enabled/disabled and the package path may be specified.

Usage example:

Examples:

x11=no (disables X11 support) x11=yes (will search for the package installation dir) x11=/usr/local/X11 (will check this path for existence)

To replace autoconf’s –with-xxx=yyy

opts = Variables()
opts.Add(PackageVariable('x11',
                       'use X11 installed here (yes = search some places',
                       'yes'))
...
if env['x11'] == True:
    dir = ... search X11 in some standard places ...
    env['x11'] = dir
if env['x11']:
    ... build with x11 ...

SCons.Variables.PackageVariable.PackageVariable(key, help, default, searchfunc=None)

The input parameters describe a ‘package list’ option, thus they are returned with the correct converter and validator appended. The result is usable for input to opts.Add() .

A ‘package list’ option may either be ‘all’, ‘none’ or a list of package names (separated by space).

SCons.Variables.PackageVariable._converter(val)

SCons.Variables.PackageVariable._validator(key, val, env, searchfunc)

SCons.Variables.PathVariable module

Option type for path Variables.

This file defines an option type for SCons implementing path settings.

To be used whenever a user-specified path override should be allowed.

Arguments to PathVariable are:

option-name = name of this option on the command line (e.g. “prefix”) option-help = help string for option option-dflt = default value for this option validator = [optional] validator for option value. Predefined are:

PathAccept – accepts any path setting; no validation PathIsDir – path must be an existing directory PathIsDirCreate – path must be a dir; will create PathIsFile – path must be a file PathExists – path must exist (any type) [default]

The validator is a function that is called and which should return True or False to indicate if the path is valid. The arguments to the validator function are: (key, val, env). The key is the name of the option, the val is the path specified for the option, and the env is the env to which the Options have been added.

Usage example:

Examples:
    prefix=/usr/local

opts = Variables()

opts = Variables()
opts.Add(PathVariable('qtdir',
                      'where the root of Qt is installed',
                      qtdir, PathIsDir))
opts.Add(PathVariable('qt_includes',
                    'where the Qt includes are installed',
                    '$qtdir/includes', PathIsDirCreate))
opts.Add(PathVariable('qt_libraries',
                    'where the Qt library is installed',
                    '$qtdir/lib'))

Module contents

Add user-friendly customizable variables to an SCons build.

class SCons.Variables.Variables(files=None, args=None, is_global=True)

Bases: object

Holds all the options, updates the environment with the variables, and renders the help text.

If is_global is True, this is a singleton, create only once.

Parameters

• files (optional) – List of option configuration files to load (backward compatibility). If a single string is passed it is automatically placed in a file list (Default value = None)

• args (optional) – dictionary to override values set from files. (Default value = None)

• is_global (optional) – global instance? (Default value = True)

Add(key, help='', default=None, validator=None, converter=None, **kw)

Add an option.

Parameters

• key – the name of the variable, or a list or tuple of arguments

• help – optional help text for the options (Default value = “”)

• default – optional default value for option (Default value = None)

• validator – optional function called to validate the option’s value (Default value = None)

• converter – optional function to be called to convert the option’s value before putting it in the environment. (Default value = None)

• **kw – keyword args, unused.

AddVariables(*optlist)

Add a list of options.

Each list element is a tuple/list of arguments to be passed on to the underlying method for adding options.

Example:

opt.AddVariables(
    ('debug', '', 0),
    ('CC', 'The C compiler'),
    ('VALIDATE', 'An option for testing validation', 'notset', validator, None),
)

FormatVariableHelpText(env, key, help, default, actual, aliases=[])

GenerateHelpText(env, sort=None)

Generate the help text for the options.

env - an environment that is used to get the current values

of the options.

cmp - Either a function as follows: The specific sort function should take two arguments and return -1, 0 or 1

or a boolean to indicate if it should be sorted.

Save(filename, env)

Saves all the options in the given file. This file can then be used to load the options next run. This can be used to create an option cache file.

filename - Name of the file to save into env - the environment get the option values from

UnknownVariables()

Returns any options in the specified arguments lists that were not known, declared options in this object.

Update(env, args=None)

Update an environment with the option variables.

env - the environment to update.

_do_add(key, help='', default=None, validator=None, converter=None)

format = '\n%s: %s\n default: %s\n actual: %s\n'

format_ = '\n%s: %s\n default: %s\n actual: %s\n aliases: %s\n'

instance = None

keys()

Returns the keywords for the options