A construction environment is created by the Environment method:

env = Environment()
       

By default, SCons initializes every new construction environment with a set of construction variables based on the tools that it finds on your system, plus the default set of builder methods necessary for using those tools. The construction variables are initialized with values describing the C compiler, the Fortran compiler, the linker, etc., as well as the command lines to invoke them.

When you initialize a construction environment you can set the values of the environment's construction variables to control how a program is built. For example:

 env = Environment(CC = 'gcc',
                   CCFLAGS = '-O2')

 env.Program('foo.c')
         

The construction environment in this example is still initialized with the same default construction variable values, except that the user has explicitly specified use of the GNU C compiler gcc, and further specifies that the -O2 (optimization level two) flag should be used when compiling the object file. In other words, the explicit initializations of $CC and $CCFLAGS override the default values in the newly-created construction environment. So a run from this example would look like:

% scons -Q
gcc -o foo.o -c -O2 foo.c
gcc -o foo foo.o

You can fetch individual construction variables using the normal syntax for accessing individual named items in a Python dictionary:

env = Environment()
print("CC is:", env['CC'])
        

This example SConstruct file doesn't build anything, but because it's actually a Python script, it will print the value of $CC for us:

% scons -Q
CC is: cc
scons: `.' is up to date.

A construction environment, however, is actually an object with associated methods, etc. If you want to have direct access to only the dictionary of construction variables, you can fetch this using the Dictionary method:

env = Environment(FOO = 'foo', BAR = 'bar')
dict = env.Dictionary()
for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
    print("key = %s, value = %s" % (key, dict[key]))
         

This SConstruct file will print the specified dictionary items for us on POSIX systems as follows:

% scons -Q
key = OBJSUFFIX, value = .o
key = LIBSUFFIX, value = .a
key = PROGSUFFIX, value = 
scons: `.' is up to date.

And on Windows:

C:\>scons -Q
key = OBJSUFFIX, value = .obj
key = LIBSUFFIX, value = .lib
key = PROGSUFFIX, value = .exe
scons: `.' is up to date.

If you want to loop and print the values of all of the construction variables in a construction environment, the Python code to do that in sorted order might look something like:

env = Environment()
for item in sorted(env.Dictionary().items()):
    print("construction variable = '%s', value = '%s'" % item)
      

Another way to get information from a construction environment is to use the subst method on a string containing $ expansions of construction variable names. As a simple example, the example from the previous section that used env['CC'] to fetch the value of $CC could also be written as:

env = Environment()
print("CC is:", env.subst('$CC'))
      

One advantage of using subst to expand strings is that construction variables in the result get re-expanded until there are no expansions left in the string. So a simple fetch of a value like $CCCOM:

env = Environment(CCFLAGS = '-DFOO')
print("CCCOM is:", env['CCCOM'])
      

Will print the unexpanded value of $CCCOM, showing us the construction variables that still need to be expanded:

% scons -Q
CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
scons: `.' is up to date.
      

Calling the subst method on $CCOM, however:

env = Environment(CCFLAGS = '-DFOO')
print("CCCOM is:", env.subst('$CCCOM'))
      

Will recursively expand all of the construction variables prefixed with $ (dollar signs), showing us the final output:

% scons -Q
CCCOM is: gcc -DFOO -c -o
scons: `.' is up to date.
      

Note that because we're not expanding this in the context of building something there are no target or source files for $TARGET and $SOURCES to expand.

If a problem occurs when expanding a construction variable, by default it is expanded to '' (a null string), and will not cause scons to fail.

env = Environment()
print("value is:", env.subst( '->$MISSING<-' ))
        

% scons -Q
value is: -><-
scons: `.' is up to date.

This default behaviour can be changed using the AllowSubstExceptions function. When a problem occurs with a variable expansion it generates an exception, and the AllowSubstExceptions function controls which of these exceptions are actually fatal and which are allowed to occur safely. By default, NameError and IndexError are the two exceptions that are allowed to occur: so instead of causing scons to fail, these are caught, the variable expanded to '' and scons execution continues. To require that all construction variable names exist, and that indexes out of range are not allowed, call AllowSubstExceptions with no extra arguments.

AllowSubstExceptions()
env = Environment()
print("value is:", env.subst( '->$MISSING<-' ))
        

% scons -Q

scons: *** NameError `MISSING' trying to evaluate `$MISSING'
File "/home/my/project/SConstruct", line 3, in <module>

This can also be used to allow other exceptions that might occur, most usefully with the ${...} construction variable syntax. For example, this would allow zero-division to occur in a variable expansion in addition to the default exceptions allowed

AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
env = Environment()
print("value is:", env.subst( '->${1 / 0}<-' ))
        

% scons -Q
value is: -><-
scons: `.' is up to date.

If AllowSubstExceptions is called multiple times, each call completely overwrites the previous list of allowed exceptions.

All of the Builder functions that we've introduced so far, like Program and Library, actually use a default construction environment that contains settings for the various compilers and other tools that SCons configures by default, or otherwise knows about and has discovered on your system. The goal of the default construction environment is to make many configurations to "just work" to build software using readily available tools with a minimum of configuration changes.

You can, however, control the settings in the default construction environment by using the DefaultEnvironment function to initialize various settings:

DefaultEnvironment(CC = '/usr/local/bin/gcc')
      

When configured as above, all calls to the Program or Object Builder will build object files with the /usr/local/bin/gcc compiler.

Note that the DefaultEnvironment function returns the initialized default construction environment object, which can then be manipulated like any other construction environment. So the following would be equivalent to the previous example, setting the $CC variable to /usr/local/bin/gcc but as a separate step after the default construction environment has been initialized:

env = DefaultEnvironment()
env['CC'] = '/usr/local/bin/gcc'
      

One very common use of the DefaultEnvironment function is to speed up SCons initialization. As part of trying to make most default configurations "just work," SCons will actually search the local system for installed compilers and other utilities. This search can take time, especially on systems with slow or networked file systems. If you know which compiler(s) and/or other utilities you want to configure, you can control the search that SCons performs by specifying some specific tool modules with which to initialize the default construction environment:

env = DefaultEnvironment(tools = ['gcc', 'gnulink'],
                         CC = '/usr/local/bin/gcc')
      

So the above example would tell SCons to explicitly configure the default environment to use its normal GNU Compiler and GNU Linker settings (without having to search for them, or any other utilities for that matter), and specifically to use the compiler found at /usr/local/bin/gcc.

The real advantage of construction environments is that you can create as many different construction environments as you need, each tailored to a different way to build some piece of software or other file. If, for example, we need to build one program with the -O2 flag and another with the -g (debug) flag, we would do this like so:

opt = Environment(CCFLAGS = '-O2')
dbg = Environment(CCFLAGS = '-g')

opt.Program('foo', 'foo.c')

dbg.Program('bar', 'bar.c')
        

% scons -Q
cc -o bar.o -c -g bar.c
cc -o bar bar.o
cc -o foo.o -c -O2 foo.c
cc -o foo foo.o

We can even use multiple construction environments to build multiple versions of a single program. If you do this by simply trying to use the Program builder with both environments, though, like this:

opt = Environment(CCFLAGS = '-O2')
dbg = Environment(CCFLAGS = '-g')

opt.Program('foo', 'foo.c')

dbg.Program('foo', 'foo.c')
        

Then SCons generates the following error:

% scons -Q
UnicodeDecodeError: 'utf8' codec can't decode byte 0xc2 in position 547: invalid continuation byte:
  File "/home/my/project/SConstruct", line 6:
    dbg.Program('foo', 'foo.c')
  File "bootstrap/src/engine/SCons/Environment.py", line 260:
    return MethodWrapper.__call__(self, target, source, *args, **kw)
  File "bootstrap/src/engine/SCons/Environment.py", line 224:
    return self.method(*nargs, **kwargs)
  File "bootstrap/src/engine/SCons/Builder.py", line 635:
    return self._execute(env, target, source, OverrideWarner(kw), ekw)
  File "bootstrap/src/engine/SCons/Builder.py", line 541:
    source = self.src_builder_sources(env, source, overwarn)
  File "bootstrap/src/engine/SCons/Builder.py", line 748:
    tlist = bld._execute(env, None, [s], overwarn)
  File "bootstrap/src/engine/SCons/Builder.py", line 557:
    _node_errors(self, env, tlist, slist)
  File "bootstrap/src/engine/SCons/Builder.py", line 303:
    msg = "Two environments with different actions were specified for the same target: %s\n(action 1: %s)\n(action 2: %s)" % (t,t_contents.decode('utf-8'),contents.decode('utf-8'))
  File "/usr/lib/python2.7/encodings/utf_8.py", line 16:
    return codecs.utf_8_decode(input, errors, True)

This is because the two Program calls have each implicitly told SCons to generate an object file named foo.o, one with a $CCFLAGS value of -O2 and one with a $CCFLAGS value of -g. SCons can't just decide that one of them should take precedence over the other, so it generates the error. To avoid this problem, we must explicitly specify that each environment compile foo.c to a separately-named object file using the Object builder, like so:

opt = Environment(CCFLAGS = '-O2')
dbg = Environment(CCFLAGS = '-g')

o = opt.Object('foo-opt', 'foo.c')
opt.Program(o)

d = dbg.Object('foo-dbg', 'foo.c')
dbg.Program(d)
        

Notice that each call to the Object builder returns a value, an internal SCons object that represents the object file that will be built. We then use that object as input to the Program builder. This avoids having to specify explicitly the object file name in multiple places, and makes for a compact, readable SConstruct file. Our SCons output then looks like:

% scons -Q
cc -o foo-dbg.o -c -g foo.c
cc -o foo-dbg foo-dbg.o
cc -o foo-opt.o -c -O2 foo.c
cc -o foo-opt foo-opt.o

Sometimes you want more than one construction environment to share the same values for one or more variables. Rather than always having to repeat all of the common variables when you create each construction environment, you can use the Clone method to create a copy of a construction environment.

Like the Environment call that creates a construction environment, the Clone method takes construction variable assignments, which will override the values in the copied construction environment. For example, suppose we want to use gcc to create three versions of a program, one optimized, one debug, and one with neither. We could do this by creating a "base" construction environment that sets $CC to gcc, and then creating two copies, one which sets $CCFLAGS for optimization and the other which sets $CCFLAGS for debugging:

env = Environment(CC = 'gcc')
opt = env.Clone(CCFLAGS = '-O2')
dbg = env.Clone(CCFLAGS = '-g')

env.Program('foo', 'foo.c')

o = opt.Object('foo-opt', 'foo.c')
opt.Program(o)

d = dbg.Object('foo-dbg', 'foo.c')
dbg.Program(d)
        

Then our output would look like:

% scons -Q
gcc -o foo.o -c foo.c
gcc -o foo foo.o
gcc -o foo-dbg.o -c -g foo.c
gcc -o foo-dbg foo-dbg.o
gcc -o foo-opt.o -c -O2 foo.c
gcc -o foo-opt foo-opt.o

You can replace existing construction variable values using the Replace method:

env = Environment(CCFLAGS = '-DDEFINE1')
env.Replace(CCFLAGS = '-DDEFINE2')
env.Program('foo.c')
        

The replacing value (-DDEFINE2 in the above example) completely replaces the value in the construction environment:

% scons -Q
cc -o foo.o -c -DDEFINE2 foo.c
cc -o foo foo.o

You can safely call Replace for construction variables that don't exist in the construction environment:

env = Environment()
env.Replace(NEW_VARIABLE = 'xyzzy')
print("NEW_VARIABLE =", env['NEW_VARIABLE'])
        

In this case, the construction variable simply gets added to the construction environment:

% scons -Q
NEW_VARIABLE = xyzzy
scons: `.' is up to date.

Because the variables aren't expanded until the construction environment is actually used to build the targets, and because SCons function and method calls are order-independent, the last replacement "wins" and is used to build all targets, regardless of the order in which the calls to Replace() are interspersed with calls to builder methods:

env = Environment(CCFLAGS = '-DDEFINE1')
print("CCFLAGS =", env['CCFLAGS'])
env.Program('foo.c')

env.Replace(CCFLAGS = '-DDEFINE2')
print("CCFLAGS =", env['CCFLAGS'])
env.Program('bar.c')
        

The timing of when the replacement actually occurs relative to when the targets get built becomes apparent if we run scons without the -Q option:

% scons
scons: Reading SConscript files ...
CCFLAGS = -DDEFINE1
CCFLAGS = -DDEFINE2
scons: done reading SConscript files.
scons: Building targets ...
cc -o bar.o -c -DDEFINE2 bar.c
cc -o bar bar.o
cc -o foo.o -c -DDEFINE2 foo.c
cc -o foo foo.o
scons: done building targets.

Because the replacement occurs while the SConscript files are being read, the $CCFLAGS variable has already been set to -DDEFINE2 by the time the foo.o target is built, even though the call to the Replace method does not occur until later in the SConscript file.

Sometimes it's useful to be able to specify that a construction variable should be set to a value only if the construction environment does not already have that variable defined You can do this with the SetDefault method, which behaves similarly to the set_default method of Python dictionary objects:

env.SetDefault(SPECIAL_FLAG = '-extra-option')
      

This is especially useful when writing your own Tool modules to apply variables to construction environments.

You can append a value to an existing construction variable using the Append method:

env = Environment(CCFLAGS = ['-DMY_VALUE'])
env.Append(CCFLAGS = ['-DLAST'])
env.Program('foo.c')
        

SCons then supplies both the -DMY_VALUE and -DLAST flags when compiling the object file:

% scons -Q
cc -o foo.o -c -DMY_VALUE -DLAST foo.c
cc -o foo foo.o

If the construction variable doesn't already exist, the Append method will create it:

env = Environment()
env.Append(NEW_VARIABLE = 'added')
print("NEW_VARIABLE =", env['NEW_VARIABLE'])
        

Which yields:

% scons -Q
NEW_VARIABLE = added
scons: `.' is up to date.

Note that the Append function tries to be "smart" about how the new value is appended to the old value. If both are strings, the previous and new strings are simply concatenated. Similarly, if both are lists, the lists are concatenated. If, however, one is a string and the other is a list, the string is added as a new element to the list.

Some times it's useful to add a new value only if the existing construction variable doesn't already contain the value. This can be done using the AppendUnique method:

env.AppendUnique(CCFLAGS=['-g'])
      

In the above example, the -g would be added only if the $CCFLAGS variable does not already contain a -g value.

You can append a value to the beginning of an existing construction variable using the Prepend method:

env = Environment(CCFLAGS = ['-DMY_VALUE'])
env.Prepend(CCFLAGS = ['-DFIRST'])
env.Program('foo.c')
        

SCons then supplies both the -DFIRST and -DMY_VALUE flags when compiling the object file:

% scons -Q
cc -o foo.o -c -DFIRST -DMY_VALUE foo.c
cc -o foo foo.o

If the construction variable doesn't already exist, the Prepend method will create it:

env = Environment()
env.Prepend(NEW_VARIABLE = 'added')
print("NEW_VARIABLE =", env['NEW_VARIABLE'])
        

Which yields:

% scons -Q
NEW_VARIABLE = added
scons: `.' is up to date.

Like the Append function, the Prepend function tries to be "smart" about how the new value is appended to the old value. If both are strings, the previous and new strings are simply concatenated. Similarly, if both are lists, the lists are concatenated. If, however, one is a string and the other is a list, the string is added as a new element to the list.

Some times it's useful to add a new value to the beginning of a construction variable only if the existing value doesn't already contain the to-be-added value. This can be done using the PrependUnique method:

env.PrependUnique(CCFLAGS=['-g'])
      

In the above example, the -g would be added only if the $CCFLAGS variable does not already contain a -g value.