Chapter 7. Environments

Chapter 7. Environments
Prev		Next

An environment is a collection of values that can affect how a program executes. SCons distinguishes between three different types of environments that can affect the behavior of SCons itself (subject to the configuration in the SConscript files), as well as the compilers and other tools it executes:

External Environment: The External Environment is the set of variables in the user's environment at the time the user runs SCons. These variables are not automatically part of an SCons build but are available to be examined if needed. See Section 7.1, “Using Values From the External Environment”, below.
Construction Environment: A Construction Environment is a distinct object created within a SConscript file and which contains values that affect how SCons decides what action to use to build a target, and even to define which targets should be built from which sources. One of the most powerful features of SCons is the ability to create multiple construction environments, including the ability to clone a new, customized construction environment from an existing construction environment. See Section 7.2, “Construction Environments”, below.
Execution Environment: An Execution Environment is the values that SCons sets when executing an external command (such as a compiler or linker) to build one or more targets. Note that this is not the same as the external environment (see above). See Section 7.3, “Controlling the Execution Environment for Issued Commands”, below.

Unlike Make, SCons does not automatically copy or import values between different environments (with the exception of explicit clones of construction environments, which inherit the values from their parent). This is a deliberate design choice to make sure that builds are, by default, repeatable regardless of the values in the user's external environment. This avoids a whole class of problems with builds where a developer's local build works because a custom variable setting causes a different compiler or build option to be used, but the checked-in change breaks the official build because it uses different environment variable settings.

Note that the SConscript writer can easily arrange for variables to be copied or imported between environments, and this is often very useful (or even downright necessary) to make it easy for developers to customize the build in appropriate ways. The point is not that copying variables between different environments is evil and must always be avoided. Instead, it should be up to the implementer of the build system to make conscious choices about how and when to import a variable from one environment to another, making informed decisions about striking the right balance between making the build repeatable on the one hand and convenient to use on the other.

Sidebar: Python Dictionaries

If you're not familiar with the Python programming language, we need to talk a little bit about the Python dictionary data type. A dictionary (also known by terms such as mapping, associative array and key-value store) associates keys with values, such that asking the dict about a key gives you back the associated value and assigning to a key creates the association - either a new setting if the key was unknown, or replacing the previous association if the key was already in the dictionary. Values can be retrieved using item access (the key name in square brackets ([])), and dictionaries also provide a method named get which responds with a default value, either None or a value you supply as the second argument, if the key is not in the dictionary, which avoids failing in that case. The syntax for initializing a dictionary uses curly braces ({}). Here are some simple examples (inspired by those in the official Python tutorial) using syntax that indicates interacting with the Python interpreter (>>> is the interpreter prompt) - you can try these out:

>>> tel = {'jack': 4098, 'sape': 4139}
>>> tel['guido'] = 4127
>>> tel['jack']
4098
>>> del tel['sape']
>>> tel['irv'] = 4127
>>> print(tel)
{'jack': 4098, 'guido': 4127, 'irv': 4127}
>>> 'guido' in tel
True
>>> print(tel['jack'])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 'jack'
>>> print(tel.get('jack'))
None

Construction environments are written to behave like a Python dictionary, and the $ENV construction variable in a construction environment is a Python dictionary. The os.environ value that Python uses to make available the external environment is also a dictionary. We will need these concepts in this chapter and throughout the rest of this guide.

7.1. Using Values From the External Environment

The external environment variable settings that the user has in force when executing SCons are available in the Python os.environ dictionary. That syntax means the environ attribute of the os module. In Python, to access the contents of a module you must first import it - so you would include the import os statement to any SConscript file in which you want to use values from the user's external environment.

import os

print("Shell is", os.environ['SHELL'])

More usefully, you can use the os.environ dictionary in your SConscript files to initialize construction environments with values from the user's external environment. Read on to the next section for information on how to do this.

Prev		Next
6.8. The `AlwaysBuild` Function	Home	7.2. Construction Environments