SCons.Variables package

Submodules

SCons.Variables.BoolVariable module

Variable type for true/false Variables.

Usage example:

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

SCons.Variables.BoolVariable.BoolVariable(key, help, default) → Tuple[str, str, str, Callable, Callable]

Return a tuple describing a boolean SCons Variable.

The input parameters describe a boolean option. Returns a tuple including the correct converter and validator. The help text will have (yes|no) automatically appended to show the valid values. The result is usable as input to Add().

SCons.Variables.BoolVariable._text2bool(val: str) → bool

Convert boolean-like string to boolean.

If val looks like it expresses a bool-like value, based on the TRUE_STRINGS and FALSE_STRINGS tuples, return the appropriate value.

This is usable as a converter function for SCons Variables.

Raises:

ValueError – if val cannot be converted to boolean.

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

Validate that the value of key in env is a boolean.

Parmaeter val is not used in the check.

Usable as a validator function for SCons Variables.

Raises:

• KeyError – if key is not set in env

• UserError – if the value of key is not True or False.

SCons.Variables.EnumVariable module

Variable type for enumeration Variables.

Enumeration variables allow selection of one from a specified set of values.

Usage example:

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

SCons.Variables.EnumVariable.EnumVariable(key, help, default, allowed_values, map={}, ignorecase: int = 0) → Tuple[str, str, str, Callable, Callable]

Return a tuple describing an enumaration SCons Variable.

The input parameters describe an option with only certain values allowed. Returns A tuple including an appropriate converter and validator. The result is usable as input to Add().

key and default are passed directly on to Add().

help is the descriptive part of the help text, and will have the allowed values automatically appended.

allowed_values is a list of strings, which are the allowed values for this option.

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

The value of ignorecase defines the behaviour of the validator:

• 0: the validator/converter are case-sensitive.

• 1: the validator/converter are case-insensitive.

• 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

Variable type for list Variables.

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',
        help='libraries to build as shared libraries',
        default='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={}) → Tuple[str, str, str, None, Callable]

Return a tuple describing a list SCons Variable.

The input parameters describe a ‘list’ option. Returns a tuple including the correct converter and validator. The result is usable for input to Add().

help will have text appended indicating the legal values (not including any extra names from map).

map can be used to map alternative names to the ones in names - that is, a form of alias.

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

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

SCons.Variables.PackageVariable module

Variable type for package Variables.

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

Given these options

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

Can be used as a replacement for autoconf’s --with-xxx=yyy

opts = Variables()
opts.Add(
    PackageVariable(
        key='x11',
        help='use X11 installed here (yes = search some places)',
        default='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) → Tuple[str, str, str, Callable, Callable]

Return a tuple describing a package list SCons Variable.

The input parameters describe a ‘package list’ option. Returns a tuple including the correct converter and validator appended. The result is usable as input to Add() .

A ‘package list’ option may either be ‘all’, ‘none’ or a pathname string. This information is appended to help.

SCons.Variables.PackageVariable._converter(val)

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

SCons.Variables.PathVariable module

Variable type for path Variables.

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

Arguments to PathVariable are:

• key - name of this option on the command line (e.g. “prefix”)

• help - help string for option

• default - 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). key is the name of the option, val is the path specified for the option, and env is the environment to which the Options have been added.

Usage example:

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

Module contents

Adds user-friendly customizable variables to an SCons build.

class SCons.Variables.Variables(files=None, args=None, is_global: bool = 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, *args, **kwargs) → None

Adds an option.

Parameters:

• key – the name of the variable, or a 5-tuple (or list). If a tuple, and there are no additional arguments, the tuple is unpacked into the four named kwargs from below. If a tuple and there are additional arguments, the first word of the tuple is taken as the key, and the remainder as aliases.

• *args – optional positional arguments, corresponding to the four named kwargs below.

Keyword Arguments:

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

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

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

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

• **kwargs – arbitrary keyword arguments used by the variable itself.

AddVariables(*optlist) → None

Adds 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=None) → str

GenerateHelpText(env, sort=None) → str

Generates the help text for the options.

Parameters:

• env – an environment that is used to get the current values of the options.

• sort – Either a comparison function used for sorting (must take two arguments and return -1, 0 or 1) or a boolean to indicate if it should be sorted.

Save(filename, env) → None

Save the options to a file.

Saves all the options which have non-default settings to the given file as Python expressions. This file can then be used to load the options for a subsequent run. This can be used to create an option cache file.

Parameters:

• filename – Name of the file to save into

• env – the environment get the option values from

UnknownVariables() → dict

Returns unknown variables.

Identifies options that were not known, declared options in this object.

Update(env, args=None) → None

Updates an environment with the option variables.

Parameters:

• env – the environment to update.

• args (optional) – a dictionary of keys and values to update in env. If omitted, uses the variables from the commandline.

_do_add(key, help: str = '', default=None, validator=None, converter=None, **kwargs) → None

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

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

instance = None

keys() → list

Returns the keywords for the options.