It is often handy to be able to specify a variable that controls a simple Boolean variable with a true or false value. It would be even more handy to accomodate different preferences for how to represent true or false values. The BoolVariable function makes it easy to accomodate these common representations of true or false.

The BoolVariable function takes three arguments: the name of the build variable, the default value of the build variable, and the help string for the variable. It then returns appropriate information for passing to the Add method of a Variables object, like so:

vars = Variables('custom.py')
vars.Add(BoolVariable('RELEASE', help='Set to build for release', default=False))
env = Environment(variables=vars, CPPDEFINES={'RELEASE_BUILD': '${RELEASE}'})
env.Program('foo.c')
          

With this build variable in place, the RELEASE variable can now be enabled by setting it to the value yes or t:

% scons -Q RELEASE=yes foo.o
cc -o foo.o -c -DRELEASE_BUILD=True foo.c

% scons -Q RELEASE=t foo.o
cc -o foo.o -c -DRELEASE_BUILD=True foo.c

Other values that equate to true include y, 1, on and all.

Conversely, RELEASE may now be given a false value by setting it to no or f:

% scons -Q RELEASE=no foo.o
cc -o foo.o -c -DRELEASE_BUILD=False foo.c

% scons -Q RELEASE=f foo.o
cc -o foo.o -c -DRELEASE_BUILD=False foo.c

Other values that equate to false include n, 0, off and none.

Lastly, if you try to specify any other value, SCons supplies an appropriate error message:

% scons -Q RELEASE=bad_value foo.o

scons: *** Error converting option: RELEASE
Invalid value for boolean option: bad_value
File "/home/my/project/SConstruct", line 3, in <module>

Suppose that you want to allow setting a COLOR variable that selects a background color to be displayed by an application, but that you want to restrict the choices to a specific set of allowed colors. You can set this up quite easily using the EnumVariable function, which takes a list of allowed_values in addition to the variable name, default value, and help text arguments:

vars = Variables('custom.py')
vars.Add(
    EnumVariable(
        'COLOR',
        help='Set background color',
        default='red',
        allowed_values=('red', 'green', 'blue'),
    )
)
env = Environment(variables=vars, CPPDEFINES={'COLOR': '"${COLOR}"'})
env.Program('foo.c')
Help(vars.GenerateHelpText(env))
          

You can now explicitly set the COLOR build variable to any of the specified allowed values:

% scons -Q COLOR=red foo.o
cc -o foo.o -c -DCOLOR="red" foo.c
% scons -Q COLOR=blue foo.o
cc -o foo.o -c -DCOLOR="blue" foo.c
% scons -Q COLOR=green foo.o
cc -o foo.o -c -DCOLOR="green" foo.c

But, importantly, an attempt to set COLOR to a value that's not in the list generates an error message:

% scons -Q COLOR=magenta foo.o

scons: *** Invalid value for option COLOR: magenta.  Valid values are: ('red', 'green', 'blue')
File "/home/my/project/SConstruct", line 10, in <module>

This example can also serve to further illustrate help generation: the help message here picks up not only the help text, but augments it with information gathered from allowed_values and default:

% scons -Q -h

COLOR: Set background color (red|green|blue)
    default: red
    actual: red

Use scons -H for help about command-line options.

The EnumVariable function also provides a way to map alternate names to allowed values. Suppose, for example, you want to allow the word navy to be used as a synonym for blue. You do this by adding a map dictionary that maps its key values to the desired allowed value:

vars = Variables('custom.py')
vars.Add(
    EnumVariable(
        'COLOR',
        help='Set background color',
        default='red',
        allowed_values=('red', 'green', 'blue'),
        map={'navy': 'blue'},
    )
)
env = Environment(variables=vars, CPPDEFINES={'COLOR': '"${COLOR}"'})
env.Program('foo.c')
          

Now you can supply navy on the command line, and SCons translates that into blue when it comes time to use the COLOR variable to build a target:

% scons -Q COLOR=navy foo.o
cc -o foo.o -c -DCOLOR="blue" foo.c

By default, when using the EnumVariable function, the allowed values are case-sensitive:

% scons -Q COLOR=Red foo.o

scons: *** Invalid value for option COLOR: Red.  Valid values are: ('red', 'green', 'blue')
File "/home/my/project/SConstruct", line 10, in <module>
% scons -Q COLOR=BLUE foo.o

scons: *** Invalid value for option COLOR: BLUE.  Valid values are: ('red', 'green', 'blue')
File "/home/my/project/SConstruct", line 10, in <module>
% scons -Q COLOR=nAvY foo.o

scons: *** Invalid value for option COLOR: nAvY.  Valid values are: ('red', 'green', 'blue')
File "/home/my/project/SConstruct", line 10, in <module>

The EnumVariable function can take an additional ignorecase keyword argument that, when set to 1, tells SCons to allow case differences when the values are specified:

vars = Variables('custom.py')
vars.Add(
    EnumVariable(
        'COLOR',
        help='Set background color',
        default='red',
        allowed_values=('red', 'green', 'blue'),
        map={'navy': 'blue'},
        ignorecase=1,
    )
)
env = Environment(variables=vars, CPPDEFINES={'COLOR': '"${COLOR}"'})
env.Program('foo.c')
          

Which yields the output:

% scons -Q COLOR=Red foo.o
cc -o foo.o -c -DCOLOR="Red" foo.c
% scons -Q COLOR=BLUE foo.o
cc -o foo.o -c -DCOLOR="BLUE" foo.c
% scons -Q COLOR=nAvY foo.o
cc -o foo.o -c -DCOLOR="blue" foo.c
% scons -Q COLOR=green foo.o
cc -o foo.o -c -DCOLOR="green" foo.c

Notice that an ignorecase value of 1 preserves the case-spelling supplied, only ignoring the case for matching. If you want SCons to translate the names into lower-case, regardless of the case used by the user, specify an ignorecase value of 2:

vars = Variables('custom.py')
vars.Add(
    EnumVariable(
        'COLOR',
        help='Set background color',
        default='red',
        allowed_values=('red', 'green', 'blue'),
        map={'navy': 'blue'},
        ignorecase=2,
    )
)
env = Environment(variables=vars, CPPDEFINES={'COLOR': '"${COLOR}"'})
env.Program('foo.c')
          

Now SCons uses values of red, green or blue regardless of how those values are spelled on the command line:

% scons -Q COLOR=Red foo.o
cc -o foo.o -c -DCOLOR="red" foo.c
% scons -Q COLOR=nAvY foo.o
cc -o foo.o -c -DCOLOR="blue" foo.c
% scons -Q COLOR=GREEN foo.o
cc -o foo.o -c -DCOLOR="green" foo.c

Another way in which you might want to control a build variable is to specify a list of allowed values, of which one or more can be chosen (where EnumVariable allows exactly one value to be chosen). SCons provides this through the ListVariable function. If, for example, you want to be able to set a COLORS variable to one or more of the allowed values:

vars = Variables('custom.py')
vars.Add(
    ListVariable(
        'COLORS', help='List of colors', default=0, names=['red', 'green', 'blue']
    )
)
env = Environment(variables=vars, CPPDEFINES={'COLORS': '"${COLORS}"'})
env.Program('foo.c')
          

You can now specify a comma-separated list of allowed values, which get translated into a space-separated list for passing to the build commands:

% scons -Q COLORS=red,blue foo.o
cc -o foo.o -c -DCOLORS="red -Dblue" foo.c
% scons -Q COLORS=blue,green,red foo.o
cc -o foo.o -c -DCOLORS="blue -Dgreen -Dred" foo.c

In addition, the ListVariable function lets you specify explicit keywords of all or none to select all of the allowed values, or none of them, respectively:

% scons -Q COLORS=all foo.o
cc -o foo.o -c -DCOLORS="red -Dgreen -Dblue" foo.c
% scons -Q COLORS=none foo.o
cc -o foo.o -c -DCOLORS="" foo.c

And, of course, an illegal value still generates an error message:

% scons -Q COLORS=magenta foo.o

scons: *** Error converting option: COLORS
Invalid value(s) for option: magenta
File "/home/my/project/SConstruct", line 7, in <module>

You can use this last characteristic as a way to enforce at least one of your valid options being chosen by specifying the valid values with the names parameter and then giving a value not in that list as the default parameter - that way if no value is given on the command line, the default is chosen, SCons errors out as this is invalid. The example is, in fact, set up that way by using 0 as the default:

% scons -Q foo.o

scons: *** Error converting option: COLORS
Invalid value(s) for option: 0
File "/home/my/project/SConstruct", line 7, in <module>

This technique works for EnumVariable as well.

SCons provides a PathVariable function to make it easy to create a build variable to control an expected path name. If, for example, you need to define a preprocessor macro that controls the location of a configuration file:

vars = Variables('custom.py')
vars.Add(
    PathVariable(
        'CONFIG', help='Path to configuration file', default='/etc/my_config'
    )
)
env = Environment(variables=vars, CPPDEFINES={'CONFIG_FILE': '"$CONFIG"'})
env.Program('foo.c')
          

This allows you to override the CONFIG build variable on the command line as necessary:

% scons -Q foo.o
cc -o foo.o -c -DCONFIG_FILE="/etc/my_config" foo.c
% scons -Q CONFIG=/usr/local/etc/other_config foo.o
scons: `foo.o' is up to date.

By default, PathVariable checks to make sure that the specified path exists and generates an error if it doesn't:

% scons -Q CONFIG=/does/not/exist foo.o

scons: *** Path for option CONFIG does not exist: /does/not/exist
File "/home/my/project/SConstruct", line 7, in <module>

PathVariable provides a number of methods that you can use to change this behavior. If you want to ensure that any specified paths are, in fact, files and not directories, use the PathVariable.PathIsFile method as the validation function:

vars = Variables('custom.py')
vars.Add(
    PathVariable(
        'CONFIG',
        help='Path to configuration file',
        default='/etc/my_config',
        validator=PathVariable.PathIsFile,
    )
)
env = Environment(variables=vars, CPPDEFINES={'CONFIG_FILE': '"$CONFIG"'})
env.Program('foo.c')
          

Conversely, to ensure that any specified paths are directories and not files, use the PathVariable.PathIsDir method as the validation function:

vars = Variables('custom.py')
vars.Add(
    PathVariable(
        'DBDIR',
        help='Path to database directory',
        default='/var/my_dbdir',
        validator=PathVariable.PathIsDir,
    )
)
env = Environment(variables=vars, CPPDEFINES={'DBDIR': '"$DBDIR"'})
env.Program('foo.c')
          

If you want to make sure that any specified paths are directories, and you would like the directory created if it doesn't already exist, use the PathVariable.PathIsDirCreate method as the validation function:

vars = Variables('custom.py')
vars.Add(
    PathVariable(
        'DBDIR',
        help='Path to database directory',
        default='/var/my_dbdir',
        validator=PathVariable.PathIsDirCreate,
    )
)
env = Environment(variables=vars, CPPDEFINES={'DBDIR': '"$DBDIR"'})
env.Program('foo.c')
          

Lastly, if you don't care whether the path exists, is a file, or a directory, use the PathVariable.PathAccept method to accept any path you supply:

vars = Variables('custom.py')
vars.Add(
    PathVariable(
        'OUTPUT',
        help='Path to output file or directory',
        default=None,
        validator=PathVariable.PathAccept,
    )
)
env = Environment(variables=vars, CPPDEFINES={'OUTPUT': '"$OUTPUT"'})
env.Program('foo.c')
          

Sometimes you want to give even more control over a path name variable, allowing them to be explicitly enabled or disabled by using yes or no keywords, in addition to allowing supplying an explicit path name. SCons provides the PackageVariable function to support this:

vars = Variables("custom.py")
vars.Add(
    PackageVariable("PACKAGE", help="Location package", default="/opt/location")
)
env = Environment(variables=vars, CPPDEFINES={"PACKAGE": '"$PACKAGE"'})
env.Program("foo.c")
          

When the SConscript file uses the PackageVariable function, you can still use the default or supply an overriding path name, but you can now explicitly set the specified variable to a value that indicates the package should be enabled (in which case the default should be used) or disabled:

% scons -Q foo.o
cc -o foo.o -c -DPACKAGE="/opt/location" foo.c
% scons -Q PACKAGE=/usr/local/location foo.o
cc -o foo.o -c -DPACKAGE="/usr/local/location" foo.c
% scons -Q PACKAGE=yes foo.o
cc -o foo.o -c -DPACKAGE="True" foo.c
% scons -Q PACKAGE=no foo.o
cc -o foo.o -c -DPACKAGE="False" foo.c