You may want to control various aspects
of your build by allowing the user
to specify variable=value
values on the command line.
For example, suppose you
want users to be able to
build a debug version of a program
by running SCons as follows:

% scons -Q debug=1

SCons provides an ARGUMENTS dictionary
that stores all of the
variable=value
assignments from the command line.
This allows you to modify
aspects of your build in response
to specifications on the command line.
(Note that unless you want to require
that users always
specify a variable,
you probably want to use
the Python
ARGUMENTS.get() function,
which allows you to specify a default value
to be used if there is no specification
on the command line.)

The following code sets the $CCFLAGS construction
variable in response to the debug
flag being set in the ARGUMENTS dictionary:

Notice that SCons keeps track of
the last values used to build the object files,
and as a result correctly rebuilds
the object and executable files
only when the value of the debug
argument has changed.

The ARGUMENTS dictionary has two minor drawbacks.
First, because it is a dictionary,
it can only store one value for each specified keyword,
and thus only "remembers" the last setting
for each keyword on the command line.
This makes the ARGUMENTS dictionary
inappropriate if users should be able to
specify multiple values
on the command line for a given keyword.
Second, it does not preserve
the order in which the variable settings
were specified,
which is a problem if
you want the configuration to
behave differently in response
to the order in which the build
variable settings were specified on the command line.

To accomodate these requirements,
SCons provides an ARGLIST variable
that gives you direct access to
variable=value
settings on the command line,
in the exact order they were specified,
and without removing any duplicate settings.
Each element in the ARGLIST variable
is itself a two-element list
containing the keyword and the value
of the setting,
and you must loop through,
or otherwise select from,
the elements of ARGLIST to
process the specific settings you want
in whatever way is appropriate for your configuration.
For example,
the following code to let the user
add to the CPPDEFINES construction variable
by specifying multiple
define=
settings on the command line:

Note that the ARGLIST and ARGUMENTS
variables do not interfere with each other,
but merely provide slightly different views
into how the user specified
variable=value
settings on the command line.
You can use both variables in the same
SCons configuration.
In general, the ARGUMENTS dictionary
is more convenient to use,
(since you can just fetch variable
settings through a dictionary access),
and the ARGLIST list
is more flexible
(since you can examine the
specific order in which
the user's command-line variabe settings).

Being able to use a command-line build variable like
debug=1 is handy,
but it can be a chore to write specific Python code
to recognize each such variable,
check for errors and provide appropriate messages,
and apply the values to a construction variable.
To help with this,
SCons supports a class to
define such build variables easily,
and a mechanism to apply the
build variables to a construction environment.
This allows you to control how the build variables affect
construction environments.

For example, suppose that you want users to set
a RELEASE construction variable on the
command line whenever the time comes to build
a program for release,
and that the value of this variable
should be added to the command line
with the appropriate -D option
(or other command line option)
to pass the value to the C compiler.
Here's how you might do that by setting
the appropriate value in a dictionary for the
$CPPDEFINES construction variable:

This SConstruct file first creates a Variables object
(the vars = Variables() call),
and then uses the object's Add
method to indicate that the RELEASE
variable can be set on the command line,
and that its default value will be 0
(the third argument to the Add method).
The second argument is a line of help text;
we'll learn how to use it in the next section.

We then pass the created Variables
object as a variables keyword argument
to the Environment call
used to create the construction environment.
This then allows a user to set the
RELEASE build variable on the command line
and have the variable show up in
the command line used to build each object from
a C source file:

NOTE: Before SCons release 0.98.1, these build variables
were known as "command-line build options."
The class was actually named the Options class,
and in the sections below,
the various functions were named
BoolOption, EnumOption, ListOption,
PathOption, PackageOption and AddOptions.
These older names still work,
and you may encounter them in older
SConscript fles,
but their use is discouraged
and will be officially deprecated some day.

To make command-line build variables most useful,
you ideally want to provide
some help text that will describe
the available variables
when the user runs scons -h.
You could write this text by hand,
but SCons provides an easier way.
Variables objects support a
GenerateHelpText method
that will, as its name suggests,
generate text that describes
the various variables that
have been added to it.
You then pass the output from this method to
the Help function:

Giving the user a way to specify the
value of a build variable on the command line
is useful,
but can still be tedious
if users must specify the variable
every time they run SCons.
We can let users provide customized build variable settings
in a local file by providing a
file name when we create the
Variables object:

It's 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
users who have 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:

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

The EnumVariable function also supports a way
to map alternate names to allowed values.
Suppose, for example,
that we want to allow the user
to use the word navy as a synonym for
blue.
We do this by adding a map dictionary
that will map its key values
to the desired legal value:

Notice that an ignorecase value of 1
preserves the case-spelling that the user supplied.
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:

Another way in which you might want to allow users
to control a build variable is to
specify a list of one or more legal values.
SCons supports this through the ListVariable function.
If, for example, we want a user to be able to set a
COLORS variable to one or more of the legal list of values:

SCons supports 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 variable in the preprocessor
that controls the location of a
configuration file:

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:

Sometimes you want to give users
even more control over a path name variable,
allowing them to explicitly enable or
disable the path name
by using yes or no keywords,
in addition to allow them
to supply an explicit path name.
SCons supports the PackageVariable
function to support this:

When the SConscript file uses the PackageVariable funciton,
user can now still use the default
or supply an overriding path name,
but 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:

Lastly, SCons provides a way to add
multiple build variables to a Variables object at once.
Instead of having to call the Add method
multiple times,
you can call the AddVariables
method with a list of build variables
to be added to the object.
Each build variable is specified
as either a tuple of arguments,
just like you'd pass to the Add method itself,
or as a call to one of the pre-defined
functions for pre-packaged command-line build variables.
in any order:

Users may, of course,
occasionally misspell variable names in their command-line settings.
SCons does not generate an error or warning
for any unknown variables the users specifies on the command line.
(This is in no small part because you may be
processing the arguments directly using the ARGUMENTS dictionary,
and therefore SCons can't know in the general case
whether a given "misspelled" variable is
really unknown and a potential problem,
or something that your SConscript file
will handle directly with some Python code.)

If, however, you're using a Variables object to
define a specific set of command-line build variables
that you expect users to be able to set,
you may want to provide an error
message or warning of your own
if the user supplies a variable setting
that is not among
the defined list of variable names known to the Variables object.
You can do this by calling the UnknownVariables
method of the Variables object:

The UnknownVariables method returns a dictionary
containing the keywords and values
of any variables the user specified on the command line
that are not
among the variables known to the Variables object
(from having been specified using
the Variables object'sAdd method).
In the examble above,
we check for whether the dictionary
returned by the UnknownVariables is non-empty,
and if so print the Python list
containing the names of the unknwown variables
and then call the Exit function
to terminate SCons:

% scons -Q NOT_KNOWN=foo
Unknown variables: ['NOT_KNOWN']

Of course, you can process the items in the
dictionary returned by the UnknownVariables function
in any way appropriate to your build configuration,
including just printing a warning message
but not exiting,
logging an error somewhere,
etc.

Note that you must delay the call of UnknownVariables
until after you have applied the Variables object
to a construction environment
with the variables=
keyword argument of an Environment call.