SCons 4.10.1

 $ python -V Python 3.9.15 

Note to Windows users: there are a number of different ways Python can be installed or invoked on Windows, it is beyond the scope of this guide to unravel all of them. Some have an additional program called the Python launcher (described, somewhat technically, in PEP 397): try using the command name py instead of python, if that is not available drop back to trying python

 C:\>py -V Python 3.9.15 

If Python is not installed on your system, or is not findable in the current search path, you will see an error message stating something like "command not found" (on UNIX or Linux) or "'python' is not recognized as an internal or external command, operable program or batch file" (on Windows cmd). In that case, you need to either install Python or fix the search path before you can install SCons.

The link for downloading Python installers (Windows and Mac) from the project's own website is: https://www.python.org/download. There are useful system-specific entries on setup and usage to be found at: https://docs.python.org/3/using

For Linux systems, Python is almost certainly available as a supported package, probably installed by default; this is often preferred over installing by other means as the system package will be built with carefully chosen optimizations, and will be kept up to date with bug fixes and security patches. In fact, the Python project itself does not build installers for Linux for this reason. Many such systems have separate packages for Python 2 and Python 3 - make sure the Python 3 package is installed, as the latest SCons requires it. Building from source may still be a useful option if you need a specific version that is not offered by the distribution you are using.

Recent versions of the Mac no longer come with Python pre-installed; older versions came with a rather out-of-date version (based on Python 2.7) which is insufficient to run current SCons. The python.org installer can be used on the Mac, but there are also other sources such as MacPorts and Homebrew. The Anaconda installation also comes with a bundled Python.

Windows has even more choices. The Python.org installer is a traditional .exe style; the same software is also released as a Windows application through the Microsoft Store. Several alternative builds also exist such as Chocolatey and ActiveState, and, again, a version of Python comes with Anaconda.

SCons will work with Python 3.7 or later. If you need to install Python and have a choice, we recommend using the most recent Python version available. Newer Python versions have significant improvements that help speed up the performance of SCons.

The recommended way to install SCons is from the Python Package Index (PyPI):

 % python -m pip install scons 

If you prefer not to install to the Python system location, or do not have privileges to do so, you can add a flag to install to a location specific to your own account and Python version:

 % python -m pip install --user scons 

For those users using Anaconda or Miniconda, use the conda installer instead, so the scons install location will match the version of Python that system will be using. For example:

 % conda install -c conda-forge scons 

If you need a specific version of SCons that is different from the current version, pip has a version option (e.g. python -m pip install scons==3.1.2), or you can follow the instructions in the following sections.

SCons does comes pre-packaged for installation on many Linux systems. Check your package installation system to see if there is an up-to-date SCons package available. Many people prefer to install distribution-native packages if available, as they provide a central point for management and updating; however not all distributions update in a timely fashion. During the still-ongoing Python 2 to 3 transition, some distributions may still have two SCons packages available, one which uses Python 2 and one which uses Python 3. Since the latest scons only runs on Python 3, to get the current version you should choose the Python 3 package.

 $ python /path/to/unpacked/scripts/scons.py --version 

To make use of an uninstalled SCons, the first step is to download either the scons-4.10.1.tar.gz or scons-4.10.1.zip, which are available from the SCons download page at https://scons.org/pages/download.html. There is also a scons-local bundle you can make use of. It is arranged a little bit differently, with the idea that you can include it with your own project if you want people to be able to do builds without having to download or install SCons. Finally, you can also use a checkout of the git tree from GitHub at a location to point to.

Unpack the archive you downloaded, using a utility like tar on Linux or UNIX, or WinZip on Windows. This will create a directory called scons-4.10.1, usually in your local directory. The driver script will be in a subdirectory named scripts, unless you are using scons-local, in which case it will be in the top directory. Now you only need to call scons.py by giving a full or relative path to it in order to use that SCons version.

Note that instructions for older versions may have suggested running python setup.py install to "build and install" SCons. This is no longer recommended (in fact, it is not recommended by the wider Python packaging community for any end-user installations of Python software). There is a setup.py file, but it is only tested and used for the automated procedure which prepares an SCons bundle for making a release on PyPI, and even that is not guaranteed to work in the future.

Another approach to multiple versions is to create Python virtualenvs, and install different SCons versions in each. A Python virtual environment is a directory with an isolated set of Python packages, where packages you install/upgrade/remove inside the environment do not affect anything outside it, and those you install/upgrade/remove outside of it do not affect anything inside it. In other words, anything you do with pip in the environment stays in that environment. The Python standard library provides a module called venv for creating these (https://docs.python.org/e/library/venv.html), although there are also other tools which provide more precise control of the setup.

Using a virtualenv can be useful even for a single version of SCons, to gain the advantages of having an isolated environment. It also gets around the problem of not having administrative privileges on a particular system to install a distribution package or use pip to install to a system location, as the virtualenv is completely under your control.

The following outline shows how this could be set up on a Linux/POSIX system (the syntax will be a bit different on Windows):

 $ create virtualenv named scons3 $ create virtualenv named scons4 $ source scons3/bin/activate $ pip install scons==3.1.2 $ deactivate $ source scons4/bin/activate $ pip install scons $ deactivate $ activate a virtualenv and run 'scons' to use that version 

Here's the ubiquitous "Hello, World!" program in C:

 #include <stdio.h> int main() { printf("Hello, world!\n"); } 

And here's how to build it using SCons. Save the code above into hello.c, and enter the following into a file named SConstruct:

 Program('hello.c') 

This minimal build file gives SCons three key pieces of information: what you want to build (a program); what you want to call that program (its base name will be hello), and the source file you want it built from (the hello.c file). Program is a Builder, an SCons function that you use to instruct SCons about the "what" of your build.

That's it. Now run the scons command to build the program. On a POSIX-compliant system like Linux or UNIX, you'll see something like:

% scons scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... cc -o hello.o -c hello.c cc -o hello hello.o scons: done building targets. 

On a Windows system with the Microsoft Visual C++ compiler, you'll see something like:

C:\>scons scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... cl /Fohello.obj /c hello.c /nologo link /nologo /OUT:hello.exe hello.obj embedManifestExeCheck(target, source, env) scons: done building targets. 

Notice that SCons deduced quite a bit here: it figured out the name of the program to build, including operating system specific suffixes (hello or hello.exe), based off the basename of the source file; it knows an intermediate object file should be built (hello.o or hello.obj); and it knows how to build those things using the compiler that is appropriate on the system you're using. It was not necessary to instruct SCons about any of those details. This is an example of how SCons makes it easy to write portable software builds.

For the programming languages SCons already knows about, it will mostly just figure it out. Here's the "Hello, World!" example in Fortran:

 program hello print *, 'Hello, World!' end program hello 

 Program('hello', 'hello.f90') 

 $ scons scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... gfortran -o hello.o -c hello.f90 gfortran -o hello hello.o scons: done building targets. 

The Program builder is only one of many builders (also called a builder method) that SCons provides to build different types of files. Another is the Object builder method, which tells SCons to build an object file from the specified source file:

 Object('hello.c') 

Now when you run the scons command to build the program, it will build just the hello.o object file on a POSIX system:

% scons scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... cc -o hello.o -c hello.c scons: done building targets. 

And just the hello.obj object file on a Windows system (with the Microsoft Visual C++ compiler):

C:\>scons scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... cl /Fohello.obj /c hello.c /nologo scons: done building targets. 

(Note that this guide will not continue to provide duplicate side-by-side POSIX and Windows output for all of the examples. Just keep in mind that, unless otherwise specified, any of the examples should work equally well on both types of systems.)

SCons also makes building with Java extremely easy. Unlike the Program and Object builder methods, however, the Java builder method requires that you specify the name of a destination directory in which you want the class files placed, followed by the source directory in which the .java files live:

 Java('classes', 'src') 

If the src directory contains a single hello.java file, then the output from running the scons command would look something like this (on a POSIX system):

% scons scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... javac -d classes -sourcepath src src/hello.java scons: done building targets. 

Java builds will be covered in much more detail, including building a Java archive (.jar) and other types of files, in Chapter 24, Java Builds.

You've seen that when you call the Program builder method, it builds the resulting program with the same base name as the source file. That is, the following call to build an executable program from the hello.c source file will build an executable program named hello on POSIX systems, and an executable program named hello.exe on Windows systems:

 Program('hello.c') 

If you want to build a program with a different base name than the base of the source file name (or even the same name), you simply put the target file name to the left of the source file name:

 Program('new_hello', 'hello.c') 

SCons requires the target file name first, followed by the source file name, so that the order mimics that of an assignment statement in most programming languages, including Python: "target = source files". For an alternative way to supply this information, see Section 3.6, “Keyword Arguments”.

Now SCons will build an executable program named new_hello when run on a POSIX system:

% scons -Q cc -o hello.o -c hello.c cc -o new_hello hello.o 

And SCons will build an executable program named new_hello.exe when run on a Windows system:

C:\>scons -Q cl /Fohello.obj /c hello.c /nologo link /nologo /OUT:new_hello.exe hello.obj embedManifestExeCheck(target, source, env) 

You can also use the Glob function to find all files matching a certain template, using the standard shell pattern matching characters * (to match everything), ? (to match a single character) and [abc] to match any of a, b or c. [!abc] is also supported, to match any character except a, b or c. This makes many multi-source-file builds quite easy:

 Program('program', Glob('*.c')) 

Glob has powerful capabilities - it matches even if the file does not currently exist, but SCons can determine that it would exist after a build. You will meet it again reading about variant directories (see Chapter 15, Separating Source and Build Trees: Variant Directories) and repositories (see Chapter 16, Building From Code Repositories).

To make long lists of file names easier to deal with, SCons provides a Split function that takes a quoted list of file names, with the names separated by spaces or other white-space characters, and turns it into a list of separate file names. Using the Split function turns the previous example into:

 Program('program', Split('main.c file1.c file2.c')) 

(If you're already familiar with Python, you'll have realized that this is similar to the split() method of Python string objects. Unlike the split() method, however, the Split function does not require a string as input and will wrap up a single non-string object in a list, or return its argument untouched if it's already a list. This comes in handy as a way to make sure arbitrary values can be passed to SCons functions without having to check the type of the variable by hand.)

Putting the call to the Split function inside the Program call can also be a little unwieldy. A more readable alternative is to assign the output from the Split call to a variable name, and then use the variable when calling the Program function:

 src_files = Split('main.c file1.c file2.c') Program('program', src_files) 

Lastly, the Split function doesn't care how much white space separates the file names in the quoted string. This allows you to create lists of file names that span multiple lines, which often makes for easier editing:

 src_files = Split(""" main.c file1.c file2.c """) Program('program', src_files) 

(Note this example uses the Python "triple-quote" syntax, which allows a string to span multiple lines. The three quotes can be either single or double quotes as long as they match.)

 Program('foo.c') Program('bar', ['bar1.c', 'bar2.c']) 

% scons -Q cc -o bar1.o -c bar1.c cc -o bar2.o -c bar2.c cc -o bar bar1.o bar2.o cc -o foo.o -c foo.c cc -o foo foo.o 

Notice that SCons does not necessarily build the programs in the same order in which you specify them in the SConstruct file. SCons does, however, recognize that the individual object files must be built before the resulting program can be built. (This will be covered in greater detail in Chapter 6, Dependencies, below.)

It's common to re-use code by sharing source files between multiple programs. One way to do this is to create a library from the common source files, which can then be linked into resulting programs. (Creating libraries is discussed in Chapter 4, Building and Linking with Libraries, below.)

A more straightforward, but perhaps less convenient, way to share source files between multiple programs is simply to include the common files in the lists of source files for each program:

 Program(Split('foo.c common1.c common2.c')) Program('bar', Split('bar1.c bar2.c common1.c common2.c')) 

SCons recognizes that the object files for the common1.c and common2.c source files each need to be built only once, even though the resulting object files are each linked in to both of the resulting executable programs:

% scons -Q cc -o bar1.o -c bar1.c cc -o bar2.o -c bar2.c cc -o common1.o -c common1.c cc -o common2.o -c common2.c cc -o bar bar1.o bar2.o common1.o common2.o cc -o foo.o -c foo.c cc -o foo foo.o common1.o common2.o 

If two or more programs share a lot of common source files, repeating the common files in the list for each program can be a maintenance problem when you need to change the list of common files. You can simplify this by creating a separate Python list to hold the common file names, and concatenating it with other lists using the Python + operator:

 common = ['common1.c', 'common2.c'] foo_files = ['foo.c'] + common bar_files = ['bar1.c', 'bar2.c'] + common Program('foo', foo_files) Program('bar', bar_files) 

This is functionally equivalent to the previous example.

You build your own libraries by specifying Library instead of Program:

 Library('foo', ['f1.c', 'f2.c', 'f3.c']) 

SCons uses the appropriate library prefix and suffix for your system. So on POSIX or Linux systems, the above example would build as follows (although ranlib may not be called on all systems):

% scons -Q cc -o f1.o -c f1.c cc -o f2.o -c f2.c cc -o f3.o -c f3.c ar rc libfoo.a f1.o f2.o f3.o ranlib libfoo.a 

On a Windows system, a build of the above example would look like:

C:\>scons -Q cl /Fof1.obj /c f1.c /nologo cl /Fof2.obj /c f2.c /nologo cl /Fof3.obj /c f3.c /nologo lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj 

The rules for the target name of the library are similar to those for programs: if you don't explicitly specify a target library name, SCons will deduce one from the name of the first source file specified, and SCons will add an appropriate file prefix and suffix if you leave them off.

 Library('foo', ['f1.c', 'f2.o', 'f3.c', 'f4.o']) 

% scons -Q cc -o f1.o -c f1.c cc -o f3.o -c f3.c ar rc libfoo.a f1.o f2.o f3.o f4.o ranlib libfoo.a 

 StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) 

 SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) 

% scons -Q cc -o f1.os -c f1.c cc -o f2.os -c f2.c cc -o f3.os -c f3.c cc -o libfoo.so -shared f1.os f2.os f3.os 

C:\>scons -Q cl /Fof1.obj /c f1.c /nologo cl /Fof2.obj /c f2.c /nologo cl /Fof3.obj /c f3.c /nologo link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj RegServerFunc(target, source, env) embedManifestDllCheck(target, source, env) 

Usually, you build a library because you want to link it with one or more programs. You link libraries with a program by specifying the libraries in the $LIBS construction variable, and by specifying the directory in which the library will be found in the $LIBPATH construction variable:

 Library('foo', ['f1.c', 'f2.c', 'f3.c']) Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.') 

Notice, of course, that you don't need to specify a library prefix (like lib) or suffix (like .a or .lib). SCons uses the correct prefix or suffix for the current system.

On a POSIX or Linux system, a build of the above example would look like:

% scons -Q cc -o f1.o -c f1.c cc -o f2.o -c f2.c cc -o f3.o -c f3.c ar rc libfoo.a f1.o f2.o f3.o ranlib libfoo.a cc -o prog.o -c prog.c cc -o prog prog.o -L. -lfoo -lbar 

On a Windows system, a build of the above example would look like:

C:\>scons -Q cl /Fof1.obj /c f1.c /nologo cl /Fof2.obj /c f2.c /nologo cl /Fof3.obj /c f3.c /nologo lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj cl /Foprog.obj /c prog.c /nologo link /nologo /OUT:prog.exe /LIBPATH:. foo.lib bar.lib prog.obj embedManifestExeCheck(target, source, env) 

As usual, notice that SCons has taken care of constructing the correct command lines to link with the specified library on each system.

Note also that, if you only have a single library to link with, you can specify the library name in single string, instead of a Python list, so that:

 Program('prog.c', LIBS='foo', LIBPATH='.') 

is equivalent to:

 Program('prog.c', LIBS=['foo'], LIBPATH='.') 

This is similar to the way that SCons handles either a string or a list to specify a single source file.

By default, the linker will only look in certain system-defined directories for libraries. SCons knows how to look for libraries in directories that you specify with the $LIBPATH construction variable. $LIBPATH consists of a list of directory names, like so:

 Program('prog.c', LIBS = 'm', LIBPATH = ['/usr/lib', '/usr/local/lib']) 

Using a Python list is preferred because it's portable across systems. Alternatively, you could put all of the directory names in a single string, separated by the system-specific path separator character: a colon on POSIX systems:

 LIBPATH = '/usr/lib:/usr/local/lib' 

or a semi-colon on Windows systems:

 LIBPATH = 'C:\\lib;D:\\lib' 

(Note that Python requires that the backslash separators in a Windows path name be escaped within strings.)

When the linker is executed, SCons will create appropriate flags so that the linker will look for libraries in the same directories as SCons. So on a POSIX or Linux system, a build of the above example would look like:

% scons -Q cc -o prog.o -c prog.c cc -o prog prog.o -L/usr/lib -L/usr/local/lib -lm 

On a Windows system, a build of the above example would look like:

C:\>scons -Q cl /Foprog.obj /c prog.c /nologo link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj embedManifestExeCheck(target, source, env) 

Note again that SCons has taken care of the system-specific details of creating the right command-line options.

For example, suppose that we want to build the two object files that make up a program with different options. This would mean calling the Object builder once for each object file, specifying the desired options:

 Object('hello.c', CCFLAGS='-DHELLO') Object('goodbye.c', CCFLAGS='-DGOODBYE') 

One way to combine these object files into the resulting program would be to call the Program builder with the names of the object files listed as sources:

 Object('hello.c', CCFLAGS='-DHELLO') Object('goodbye.c', CCFLAGS='-DGOODBYE') Program(['hello.o', 'goodbye.o']) 

The problem with specifying the names as strings is that our SConstruct file is no longer portable across operating systems. It won't, for example, work on Windows because the object files there would be named hello.obj and goodbye.obj, not hello.o and goodbye.o.

A better solution is to assign the lists of targets returned by the calls to the Object builder to variables, which we can then concatenate in our call to the Program builder:

 hello_list = Object('hello.c', CCFLAGS='-DHELLO') goodbye_list = Object('goodbye.c', CCFLAGS='-DGOODBYE') Program(hello_list + goodbye_list) 

This makes our SConstruct file portable again, the build output on Linux looking like:

% scons -Q cc -o goodbye.o -c -DGOODBYE goodbye.c cc -o hello.o -c -DHELLO hello.c cc -o hello hello.o goodbye.o 

And on Windows:

C:\>scons -Q cl /Fogoodbye.obj /c goodbye.c -DGOODBYE cl /Fohello.obj /c hello.c -DHELLO link /nologo /OUT:hello.exe hello.obj goodbye.obj embedManifestExeCheck(target, source, env) 

We'll see examples of using the list of nodes returned by builder methods throughout the rest of this guide.

 #include <hello.h> int main() { printf("Hello, %s!\n", string); } 

 #define string "world" 

 Program('hello.c', CPPPATH='.') 

The $CPPPATH value tells SCons to look in the current directory ('.') for any files included by C source files (.c or .h files). With this assignment in the SConstruct file:

% scons -Q hello cc -o hello.o -c -I. hello.c cc -o hello hello.o % scons -Q hello scons: `hello' is up to date. % [CHANGE THE CONTENTS OF hello.h] % scons -Q hello cc -o hello.o -c -I. hello.c cc -o hello hello.o 

First, notice that SCons constructed the -I. argument from the '.' in the $CPPPATH variable so that the compilation would find the hello.h file in the local directory.

Second, realize that SCons knows that the hello program must be rebuilt because it scans the contents of the hello.c file for the #include lines that indicate another file is being included in the compilation. SCons records these as implicit dependencies of the target file, Consequently, when the hello.h file changes, SCons realizes that the hello.c file includes it, and rebuilds the resulting hello program that depends on both the hello.c and hello.h files.

Like the $LIBPATH variable, the $CPPPATH variable may be a list of directories, or a string separated by the system-specific path separation character (':' on POSIX/Linux, ';' on Windows). Either way, SCons creates the right command-line options so that the following example:

 Program('hello.c', CPPPATH = ['include', '/home/project/inc']) 

Will look like this on POSIX or Linux:

% scons -Q hello cc -o hello.o -c -Iinclude -I/home/project/inc hello.c cc -o hello hello.o 

And like this on Windows:

C:\>scons -Q hello.exe cl /Fohello.obj /c hello.c /nologo /Iinclude /I\home\project\inc link /nologo /OUT:hello.exe hello.obj embedManifestExeCheck(target, source, env) 

Sometimes a file depends on another file that is not detected by an SCons scanner. For this situation, SCons allows you to specific explicitly that one file depends on another file, and must be rebuilt whenever that file changes. This is specified using the Depends method:

 hello = Program('hello.c') Depends(hello, 'other_file') 

 % scons -Q hello cc -c hello.c -o hello.o cc -o hello hello.o % scons -Q hello scons: `hello' is up to date. % edit other_file [CHANGE THE CONTENTS OF other_file] % scons -Q hello cc -c hello.c -o hello.o cc -o hello hello.o 

Note that the dependency (the second argument to Depends) may also be a list of Node objects (for example, as returned by a call to a Builder):

 hello = Program('hello.c') goodbye = Program('goodbye.c') Depends(hello, goodbye) 

in which case the dependency or dependencies will be built before the target(s):

 % scons -Q hello cc -c goodbye.c -o goodbye.o cc -o goodbye goodbye.o cc -c hello.c -o hello.o cc -o hello hello.o 

 #define FOO_HEADER <foo.h> #include FOO_HEADER int main() { return FOO; } 

% scons -Q cc -o hello.o -c -I. hello.c cc -o hello hello.o % [CHANGE CONTENTS OF foo.h] % scons -Q scons: `.' is up to date. 

In these cases, you may also use the compiler to extract the implicit dependencies. ParseDepends can parse the contents of the compiler output in the style of Make, and explicitly establish all of the listed dependencies.

The following example uses ParseDepends to process a compiler generated dependency file which is generated as a side effect during compilation of the object file:

 obj = Object('hello.c', CCFLAGS='-MD -MF hello.d', CPPPATH='.') SideEffect('hello.d', obj) ParseDepends('hello.d') Program('hello', obj) 

% scons -Q cc -o hello.o -c -MD -MF hello.d -I. hello.c cc -o hello hello.o % [CHANGE CONTENTS OF foo.h] % scons -Q cc -o hello.o -c -MD -MF hello.d -I. hello.c 

Parsing dependencies from a compiler-generated .d file has a chicken-and-egg problem, that causes unnecessary rebuilds:

 % scons -Q cc -o hello.o -c -MD -MF hello.d -I. hello.c cc -o hello hello.o % scons -Q --debug=explain scons: rebuilding `hello.o' because `foo.h' is a new dependency cc -o hello.o -c -MD -MF hello.d -I. hello.c % scons -Q scons: `.' is up to date. 

In the first pass, the dependency file is generated while the object file is compiled. At that time, SCons does not know about the dependency on foo.h. In the second pass, the object file is regenerated because foo.h is detected as a new dependency.

ParseDepends immediately reads the specified file at invocation time and just returns if the file does not exist. A dependency file generated during the build process is not automatically parsed again. Hence, the compiler-extracted dependencies are not stored in the signature database during the same build pass. This limitation of ParseDepends leads to unnecessary recompilations. Therefore, ParseDepends should only be used if scanners are not available for the employed language or not powerful enough for the specific task.

Sometimes it makes sense to not rebuild a program, even if a dependency file changes. In this case, you would tell SCons specifically to ignore a dependency using the Ignore function as follows:

 hello_obj=Object('hello.c') hello = Program(hello_obj) Ignore(hello_obj, 'hello.h') 

 % scons -Q hello cc -c -o hello.o hello.c cc -o hello hello.o % scons -Q hello scons: `hello' is up to date. % edit hello.h [CHANGE THE CONTENTS OF hello.h] % scons -Q hello scons: `hello' is up to date. 

Now, the above example is a little contrived, because it's hard to imagine a real-world situation where you wouldn't want to rebuild hello if the hello.h file changed. A more realistic example might be if the hello program is being built in a directory that is shared between multiple systems that have different copies of the stdio.h include file. In that case, SCons would notice the differences between the different systems' copies of stdio.h and would rebuild hello each time you change systems. You could avoid these rebuilds as follows:

 hello = Program('hello.c', CPPPATH=['/usr/include']) Ignore(hello, '/usr/include/stdio.h') 

Ignore can also be used to prevent a generated file from being built by default. This is due to the fact that directories depend on their contents. So to ignore a generated file from the default build, you specify that the directory should ignore the generated file. Note that the file will still be built if the user specifically requests the target on scons command line, or if the file is a dependency of another file which is requested and/or is built by default.

 hello_obj=Object('hello.c') hello = Program(hello_obj) Ignore('.',[hello,hello_obj]) 

% scons -Q scons: `.' is up to date. % scons -Q hello cc -o hello.o -c hello.c cc -o hello hello.o % scons -Q hello scons: `hello' is up to date. 

 import time version_c_text = """ char *date = "%s"; """ % time.ctime(time.time()) open('version.c', 'w').write(version_c_text) hello = Program(['hello.c', 'version.c']) 

% scons -Q hello cc -o hello.o -c hello.c cc -o version.o -c version.c cc -o hello hello.o version.o % sleep 1 % scons -Q hello cc -o version.o -c version.c cc -o hello hello.o version.o % sleep 1 % scons -Q hello cc -o version.o -c version.c cc -o hello hello.o version.o 

One solution is to use the Requires function to specify that the version.o must be rebuilt before it is used by the link step, but that changes to version.o should not actually cause the hello executable to be re-linked:

 import time version_c_text = """ char *date = "%s"; """ % time.ctime(time.time()) open('version.c', 'w').write(version_c_text) version_obj = Object('version.c') hello = Program('hello.c', LINKFLAGS = str(version_obj[0])) Requires(hello, version_obj) 

Notice that because we can no longer list version.c as one of the sources for the hello program, we have to find some other way to get it into the link command line. For this example, we're cheating a bit and stuffing the object file name (extracted from version_obj list returned by the Object builder call) into the $LINKFLAGS variable, because $LINKFLAGS is already included in the $LINKCOM command line.

With these changes, we get the desired behavior of only re-linking the hello executable when the hello.c has changed, even though the version.o is rebuilt (because the SConstruct file still changes the version.c contents directly each run):

% scons -Q hello cc -o version.o -c version.c cc -o hello.o -c hello.c cc -o hello version.o hello.o % sleep 1 % scons -Q hello cc -o version.o -c version.c scons: `hello' is up to date. % sleep 1 % [CHANGE THE CONTENTS OF hello.c] % scons -Q hello cc -o version.o -c version.c cc -o hello.o -c hello.c cc -o hello version.o hello.o % sleep 1 % scons -Q hello cc -o version.o -c version.c scons: `hello' is up to date. 

How SCons handles dependencies can also be affected by the AlwaysBuild method. When a file is passed to the AlwaysBuild method, like so:

 hello = Program('hello.c') AlwaysBuild(hello) 

Then the specified target file (hello in our example) will always be considered out-of-date and rebuilt whenever that target file is evaluated while walking the dependency graph:

% scons -Q cc -o hello.o -c hello.c cc -o hello hello.o % scons -Q cc -o hello hello.o 

The AlwaysBuild function has a somewhat misleading name, because it does not actually mean the target file will be rebuilt every single time SCons is invoked. Instead, it means that the target will, in fact, be rebuilt whenever the target file is encountered while evaluating the targets specified on the command line (and their dependencies). So specifying some other target on the command line, a target that does not itself depend on the AlwaysBuild target, will still be rebuilt only if it's out-of-date with respect to its dependencies:

% scons -Q cc -o hello.o -c hello.c cc -o hello hello.o % scons -Q hello.o scons: `hello.o' is up to date. 

When SCons builds a target file, it does not execute the commands with the external environment that you used to execute SCons. Instead, it builds an execution environment from the values stored in the $ENV construction variable and uses that for executing commands.

The most important ramification of this behavior is that the PATH environment variable, which controls where the operating system will look for commands and utilities, will almost certainly not be the same as in the external environment from which you called SCons. This means that SCons might not necessarily find all of the tools that you can successfully execute from the command line.

The default value of the PATH environment variable on a POSIX system is /usr/local/bin:/opt/bin:/bin:/usr/bin:/snap/bin. The default value of the PATH environment variable on a Windows system comes from the Windows registry value for the command interpreter. If you want to execute any commands--compilers, linkers, etc.--that are not in these default locations, you need to set the PATH value in the $ENV dictionary in your construction environment.

The simplest way to do this is to initialize explicitly the value when you create the construction environment; this is one way to do that:

 path = ['/usr/local/bin', '/bin', '/usr/bin'] env = Environment(ENV={'PATH': path}) 

Assigning a dictionary to the $ENV construction variable in this way completely resets the execution environment, so that the only variable that will be set when external commands are executed will be the PATH value. If you want to use the rest of the values in $ENV and only set the value of PATH, you can assign a value only to that variable:

 env['ENV']['PATH'] = ['/usr/local/bin', '/bin', '/usr/bin'] 

Note that SCons does allow you to define the directories in the PATH in a string with paths separated by the pathname separator character for your system (':' on POSIX systems, ';' on Windows).

 env['ENV']['PATH'] = '/usr/local/bin:/bin:/usr/bin' 

But doing so makes your SConscript file less portable, since it will be correct only for the system type that matches the separator. You can use the Python os.pathsep for for greater portability - don't worry too much if this Python syntax doesn't make sense since there are other ways available:

 import os env['ENV']['PATH'] = os.pathsep.join(['/usr/local/bin', '/bin', '/usr/bin']) 

 import os env = Environment(ENV={'PATH': os.environ['PATH']}) 

 import os env = Environment(ENV=os.environ.copy()) 

 env = Environment(ENV=os.environ.copy()) env.PrependENVPath('PATH', '/usr/local/bin') env.AppendENVPath('LIB', '/usr/local/lib') 

SCons construction environments have a MergeFlags method that merges values from a passed-in argument into the construction environment. If the argument is a dictionary, MergeFlags treats each value in the dictionary as a list of options you would pass to a command (such as a compiler or linker). MergeFlags will not duplicate an option if it already exists in the construction variable. If the argument is a string, MergeFlags calls the ParseFlags method to burst it out into a dictionary first, then acts on the result.

MergeFlags tries to be intelligent about merging options, knowing that different construction variables may have different needs. When merging options to any variable whose name ends in PATH, MergeFlags keeps the leftmost occurrence of the option, because in typical lists of directory paths, the first occurrence "wins." When merging options to any other variable name, MergeFlags keeps the rightmost occurrence of the option, because in a list of typical command-line options, the last occurrence "wins."

 env = Environment() env.Append(CCFLAGS='-option -O3 -O1') flags = {'CCFLAGS': '-whatever -O3'} env.MergeFlags(flags) print("CCFLAGS:", env['CCFLAGS']) 

% scons -Q CCFLAGS: ['-option', '-O1', '-whatever', '-O3'] scons: `.' is up to date. 

Note that the default value for $CCFLAGS is an internal SCons object which automatically converts the options you specify as a string into a list.

 env = Environment() env.Append(CPPPATH=['/include', '/usr/local/include', '/usr/include']) flags = {'CPPPATH': ['/usr/opt/include', '/usr/local/include']} env.MergeFlags(flags) print("CPPPATH:", env['CPPPATH']) 

% scons -Q CPPPATH: ['/include', '/usr/local/include', '/usr/include', '/usr/opt/include'] scons: `.' is up to date. 

Note that the default value for $CPPPATH is a normal Python list, so you should give its values as a list in the dictionary you pass to the MergeFlags function.

If MergeFlags is passed anything other than a dictionary, it calls the ParseFlags method to convert it into a dictionary.

 env = Environment() env.Append(CCFLAGS='-option -O3 -O1') env.Append(CPPPATH=['/include', '/usr/local/include', '/usr/include']) env.MergeFlags('-whatever -I/usr/opt/include -O3 -I/usr/local/include') print("CCFLAGS:", env['CCFLAGS']) print("CPPPATH:", env['CPPPATH']) 

% scons -Q CCFLAGS: ['-option', '-O1', '-whatever', '-O3'] CPPPATH: ['/include', '/usr/local/include', '/usr/include', '/usr/opt/include'] scons: `.' is up to date. 

In the combined example above, ParseFlags has sorted the options into their corresponding variables and returned a dictionary for MergeFlags to apply to the construction variables in the specified construction environment.

It is also possible to merge construction variable values from arguments given to the Environment call itself. If the parse_flags keyword argument is given, its value is distributed to construction variables in the new environment in the same way as described for the MergeFlags method. This also works when calling env.Clone, as well as in overrides to builder methods (see Section 7.2.14, “Overriding Construction Variable Settings”).

 env = Environment(parse_flags="-I/opt/include -L/opt/lib -lfoo") for k in ('CPPPATH', 'LIBPATH', 'LIBS'): print("%s:" % k, env.get(k)) env.Program("f1.c") 

% scons -Q CPPPATH: ['/opt/include'] LIBPATH: ['/opt/lib'] LIBS: ['foo'] cc -o f1.o -c -I/opt/include f1.c cc -o f1 f1.o -L/opt/lib -lfoo 

SCons construction environments have a ParseFlags method that takes a set of typical command-line options and distributes them into the appropriate construction variables Historically, it was created to support the ParseConfig method, so it focuses on options used by the GNU Compiler Collection (GCC) for the C and C++ toolchains.

ParseFlags returns a dictionary containing the options distributed into their respective construction variables. Normally, this dictionary would then be passed to MergeFlags to merge the options into a construction environment, but the dictionary can be edited if desired to provide additional functionality. (Note that if the flags are not going to be edited, calling MergeFlags with the options directly will avoid an additional step.)

 env = Environment() d = env.ParseFlags("-I/opt/include -L/opt/lib -lfoo") for k, v in sorted(d.items()): if v: print(k, v) env.MergeFlags(d) env.Program("f1.c") 

% scons -Q CPPPATH ['/opt/include'] LIBPATH ['/opt/lib'] LIBS ['foo'] cc -o f1.o -c -I/opt/include f1.c cc -o f1 f1.o -L/opt/lib -lfoo 

Note that if the options are limited to generic types like those above, they will be correctly translated for other platform types:

C:\>scons -Q CPPPATH ['/opt/include'] LIBPATH ['/opt/lib'] LIBS ['foo'] cl /Fof1.obj /c f1.c /nologo /I\opt\include link /nologo /OUT:f1.exe /LIBPATH:\opt\lib foo.lib f1.obj embedManifestExeCheck(target, source, env) 

Since the assumption is that the flags are used for the GCC toolchain, unrecognized flags are placed in $CCFLAGS so they will be used for both C and C++ compiles:

 env = Environment() d = env.ParseFlags("-whatever") for k, v in sorted(d.items()): if v: print(k, v) env.MergeFlags(d) env.Program("f1.c") 

% scons -Q CCFLAGS -whatever cc -o f1.o -c -whatever f1.c cc -o f1 f1.o 

ParseFlags will also accept a (recursive) list of strings as input; the list is flattened before the strings are processed:

 env = Environment() d = env.ParseFlags(["-I/opt/include", ["-L/opt/lib", "-lfoo"]]) for k, v in sorted(d.items()): if v: print(k, v) env.MergeFlags(d) env.Program("f1.c") 

% scons -Q CPPPATH ['/opt/include'] LIBPATH ['/opt/lib'] LIBS ['foo'] cc -o f1.o -c -I/opt/include f1.c cc -o f1 f1.o -L/opt/lib -lfoo 

If a string begins with an exclamation mark (!), the string is passed to the shell for execution. The output of the command is then parsed:

 env = Environment() d = env.ParseFlags(["!echo -I/opt/include", "!echo -L/opt/lib", "-lfoo"]) for k, v in sorted(d.items()): if v: print(k, v) env.MergeFlags(d) env.Program("f1.c") 

% scons -Q CPPPATH ['/opt/include'] LIBPATH ['/opt/lib'] LIBS ['foo'] cc -o f1.o -c -I/opt/include f1.c cc -o f1 f1.o -L/opt/lib -lfoo 

ParseFlags is regularly updated for new options; consult the man page for details about those currently recognized.

SCons construction environments have a ParseConfig method that asks the host system to execute a command and then configures the appropriate construction variables based on the output of that command. This lets you run a program like pkg-config or a more specific utility to help set up your build.

 env = Environment() env['CPPPATH'] = ['/lib/compat'] env.ParseConfig("pkg-config x11 --cflags --libs") print("CPPPATH:", env['CPPPATH']) 

SCons will execute the specified command string, parse the resultant flags, and add the flags to the appropriate environment variables.

 % scons -Q CPPPATH: ['/lib/compat', '/usr/X11/include'] scons: `.' is up to date. 

In the example above, SCons has added the include directory to $CPPPATH (depending on what other flags are emitted by the pkg-config command, other variables may have been extended as well.)

Note that the options are merged with existing options using the MergeFlags method, so that each option only occurs once in the construction variable.

 env = Environment() env.ParseConfig("pkg-config x11 --cflags --libs") env.ParseConfig("pkg-config x11 --cflags --libs") print("CPPPATH:", "CPPPATH:", env['CPPPATH']) 

 % scons -Q CPPPATH: ['/usr/X11/include'] scons: `.' is up to date. 

It's often very useful to be able to give users some help that describes the specific targets, build options, etc., that can be used for your build. SCons provides the Help function to allow you to specify this help text:

 Help(""" Type: 'scons program' to build the production program, 'scons debug' to build the debug version. """) 

Optionally, you can specify the append flag:

 Help(""" Type: 'scons program' to build the production program, 'scons debug' to build the debug version. """, append=True) 

(Note the above use of the Python triple-quote syntax, which comes in very handy for specifying multi-line strings like help text.)

When the SConstruct or SConscript files contain a call to the Help function, the specified help text will be displayed in response to the SCons -h option:

% scons -h scons: Reading SConscript files ... scons: done reading SConscript files. Type: 'scons program' to build the production program, 'scons debug' to build the debug version. Use scons -H for help about SCons built-in command-line options. 

The SConscript files may contain multiple calls to the Help function, in which case the specified text(s) will be concatenated when displayed. This allows you to define fragments of help text together with the corresponding feature, even if spread across multiple SConscript files. In this situation, the order in which the SConscript files are called will determine the order in which the Help functions are called, which will determine the order in which the various bits of text will get concatenated.

Calling Help("text") overwrites the help text that otherwise would be collected from any command-line options defined in AddOption calls. To preserve the AddOption help text, add the append=True keyword argument when calling Help. This also preserves the option help for the scons command itself. To preserve only the AddOption help, also add the local_only=True keyword argument. (This only matters the first time you call Append, on any subsequent calls the text you passed is added to the existing help text).

Another use would be to make the help text conditional on some variable. For example, suppose you only want to display a line about building a Windows-only version of a program when actually run on Windows. The following SConstruct file:

 env = Environment() Help("\nType: 'scons program' to build the production program.\n") if env['PLATFORM'] == 'win32': Help("\nType: 'scons windebug' to build the Windows debug version.\n") 

Will display the complete help text on Windows:

C:\>scons -h scons: Reading SConscript files ... scons: done reading SConscript files. Type: 'scons program' to build the production program. Type: 'scons windebug' to build the Windows debug version. Use scons -H for help about SCons built-in command-line options. 

But only show the relevant option on a Linux or UNIX system:

% scons -h scons: Reading SConscript files ... scons: done reading SConscript files. Type: 'scons program' to build the production program. Use scons -H for help about SCons built-in command-line options. 

If there is no Help text in the SConstruct or SConscript files, SCons will revert to displaying its standard list that describes the SCons command-line options. This list is also always displayed whenever the -H option is used.

SCons has many command-line options that control its behavior. A command-line option always begins with one or two hyphen (-) characters. The SCons manual page contains the description of the current options (see https://scons.org/doc/production/HTML/scons-man.html).

% scons scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... ... [build output] ... scons: done building targets. % export SCONSFLAGS="-Q" % scons ... [build output] ... 

 $ setenv SCONSFLAGS "-Q" 

 C:\Users\foo> set SCONSFLAGS="-Q" 

 if not GetOption('help'): SConscript('src/SConscript', export='env') 

 import os num_cpu = int(os.environ.get('NUM_CPU', 2)) SetOption('num_jobs', num_cpu) print("running with -j %s" % GetOption('num_jobs')) 

% scons -Q running with -j 2 scons: `.' is up to date. 

% export NUM_CPU="4" % scons -Q running with -j 4 scons: `.' is up to date. 

% scons -Q -j 7 running with -j 7 scons: `.' is up to date. % export NUM_CPU="4" % scons -Q -j 3 running with -j 3 scons: `.' is up to date. 

 AddOption( '--prefix', dest='prefix', type='string', nargs=1, action='store', metavar='DIR', help='installation prefix', ) env = Environment(PREFIX=GetOption('prefix')) installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in') Default(installed_foo) 

% scons -Q -n Install file: "foo.in" as "/usr/bin/foo.in" 

% scons -Q -n --prefix=/tmp/install Install file: "foo.in" as "/tmp/install/usr/bin/foo.in" 

 % scons -Q debug=1 

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

 env = Environment() debug = ARGUMENTS.get('debug', 0) if int(debug): env.Append(CCFLAGS='-g') env.Program('prog.c') 

This results in the -g compiler option being used when debug=1 is used on the command line:

% scons -Q debug=0 cc -o prog.o -c prog.c cc -o prog prog.o % scons -Q debug=0 scons: `.' is up to date. % scons -Q debug=1 cc -o prog.o -c -g prog.c cc -o prog prog.o % scons -Q debug=1 scons: `.' is up to date. 

SCons keeps track of the precise build command used to build each object file, and as a result can determine that the object and executable files need rebuilding 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 map each keyword to one value, and thus only "remembers" the last setting for each keyword on the command line. This makes the ARGUMENTS dictionary less than ideal if you want to allow specifying 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 (Python versions since 3.6 now maintain dictionaries in insertion order, so this problem is mitigated).

To accommodate these requirements, SCons also provides an ARGLIST variable that gives you direct access to build variable settings from 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 lets you add to the CPPDEFINES construction variable by specifying multiple define= settings on the command line:

 cppdefines = [] for key, value in ARGLIST: if key == 'define': cppdefines.append(value) env = Environment(CPPDEFINES=cppdefines) env.Object('prog.c') 

Yields the following output:

% scons -Q define=FOO cc -o prog.o -c -DFOO prog.c % scons -Q define=FOO define=BAR cc -o prog.o -c -DFOO -DBAR prog.c 

Note that the ARGLIST and ARGUMENTS variables do not interfere with each other, but rather provide slightly different views into how you 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 Python dictionary access), and the ARGLIST list is more flexible (since you can examine the specific order in which the command-line variable settings were given).

 vars = Variables(None, ARGUMENTS) vars.Add('RELEASE', default=0) env = Environment(variables=vars, CPPDEFINES={'RELEASE_BUILD': '${RELEASE}'}) env.Program(['foo.c', 'bar.c']) 

% scons -Q RELEASE=1 cc -o bar.o -c -DRELEASE_BUILD=1 bar.c cc -o foo.o -c -DRELEASE_BUILD=1 foo.c cc -o foo foo.o bar.o 

 vars = Variables() vars.Add('RELEASE', help='Set to 1 to build for release', default=0) env = Environment(variables=vars) Help(vars.GenerateHelpText(env)) 

% scons -Q -h RELEASE: Set to 1 to build for release default: 0 actual: 0 Use scons -H for help about SCons built-in command-line options. 

 vars = Variables('custom.py') vars.Add('RELEASE', help='Set to 1 to build for release', default=0) env = Environment(variables=vars, CPPDEFINES={'RELEASE_BUILD': '${RELEASE}'}) env.Program(['foo.c', 'bar.c']) Help(vars.GenerateHelpText(env)) 

 RELEASE = 1 

% scons -Q cc -o bar.o -c -DRELEASE_BUILD=1 bar.c cc -o foo.o -c -DRELEASE_BUILD=1 foo.c cc -o foo foo.o bar.o 

 RELEASE = 0 

% scons -Q cc -o bar.o -c -DRELEASE_BUILD=0 bar.c cc -o foo.o -c -DRELEASE_BUILD=0 foo.c cc -o foo foo.o bar.o 

 vars = Variables('custom.py', ARGUMENTS) 

 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') 

% 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 

% 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 

% scons -Q RELEASE=bad_value foo.o scons: *** Error converting option: 'RELEASE' Invalid value for boolean variable: 'bad_value' File "/home/my/project/SConstruct", line 3, in <module> 

 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)) 

% 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 

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

% scons -Q -h COLOR: Set background color (red|green|blue) default: red actual: red Use scons -H for help about SCons built-in command-line options. 

 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') 

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

% scons -Q COLOR=Red foo.o scons: *** Invalid value for enum variable '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 enum variable '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 enum variable 'COLOR': 'nAvY'. Valid values are: ('red', 'green', 'blue') File "/home/my/project/SConstruct", line 10, in <module> 

 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') 

% 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 

 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') 

% 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 

 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') 

% 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 

% 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 

% scons -Q COLORS=magenta foo.o scons: *** Invalid value(s) for variable 'COLORS': 'magenta'. Valid values are: blue,green,red,all,none File "/home/my/project/SConstruct", line 7, in <module> 

% scons -Q foo.o scons: *** Invalid value(s) for variable 'COLORS': '0'. Valid values are: blue,green,red,all,none File "/home/my/project/SConstruct", line 7, in <module> 

 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') 

% 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. 

% scons -Q CONFIG=/does/not/exist foo.o scons: *** Path for variable 'CONFIG' does not exist: /does/not/exist File "/home/my/project/SConstruct", line 7, in <module> 

 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') 

 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') 

 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') 

 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') 

 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") 

% 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="/opt/location" foo.c % scons -Q PACKAGE=no foo.o cc -o foo.o -c -DPACKAGE="False" foo.c 

 vars = Variables() vars.AddVariables( ('RELEASE', 'Set to 1 to build for release', 0), ('CONFIG', 'Configuration file', '/etc/my_config'), BoolVariable('warnings', help='compilation with -Wall and similar', default=True), EnumVariable( 'debug', help='debug output and symbols', default='no', allowed_values=('yes', 'no', 'full'), map={}, ignorecase=0, ), ListVariable( 'shared', help='libraries to build as shared libraries', default='all', names=list_of_libs, ), PackageVariable( 'x11', help='use X11 installed here (yes = search some places)', default='yes' ), PathVariable('qtdir', help='where the root of Qt is installed', default=qtdir), ) 

 vars = Variables(None) vars.Add('RELEASE', help='Set to 1 to build for release', default=0) env = Environment(variables=vars, CPPDEFINES={'RELEASE_BUILD': '${RELEASE}'}) unknown = vars.UnknownVariables() if unknown: print("Unknown variables: %s" % " ".join(unknown.keys())) Exit(1) env.Program('foo.c') 

% scons -Q NOT_KNOWN=foo Unknown variables: NOT_KNOWN 

If a shared library is created with the $SHLIBVERSION variable set, scons will create symbolic links as needed based on that variable. To properly install such a library including the symbolic links, use the InstallVersionedLib function.

For example, on a Linux system, this instruction:

 foo = env.SharedLibrary(target="foo", source="foo.c", SHLIBVERSION="1.2.3") 

Will produce a shared library libfoo.so.1.2.3 and symbolic links libfoo.so and libfoo.so.1 which point to libfoo.so.1.2.3. You can use the Node returned by the SharedLibrary builder in order to install the library and its symbolic links in one go without having to list them individually:

 env.InstallVersionedLib(target="lib", source=foo) 

On systems which expect a shared library to be installed both with a name that indicates the version, for run-time resolution, and as a plain name, for link-time resolution, the InstallVersionedLib function can be used. Symbolic links appropriate to the type of system will be generated based on symlinks of the source library.

Suppose you want to arrange to make a copy of a file, and don't have a suitable pre-existing builder. ^[3] One way would be to use the Copy action factory in conjunction with the Command builder:

 Command("file.out", "file.in", Copy("$TARGET", "$SOURCE")) 

Notice that the action returned by the Copy factory will expand the $TARGET and $SOURCE strings at the time file.out is built, and that the order of the arguments is the same as that of a builder itself--that is, target first, followed by source:

% scons -Q Copy("file.out", "file.in") 

You can, of course, name a file explicitly instead of using $TARGET or $SOURCE:

 Command("file.out", [], Copy("$TARGET", "file.in")) 

Which executes as:

% scons -Q Copy("file.out", "file.in") 

The usefulness of the Copy factory becomes more apparent when you use it in a list of actions passed to the Command builder. For example, suppose you needed to run a file through a utility that only modifies files in-place, and can't "pipe" input to output. One solution is to copy the source file to a temporary file name, run the utility, and then copy the modified temporary file to the target, which the Copy factory makes extremely easy:

 Command( "file.out", "file.in", action=[ Copy("tempfile", "$SOURCE"), "modify tempfile", Copy("$TARGET", "tempfile"), ], ) 

The output then looks like:

% scons -Q Copy("tempfile", "file.in") modify tempfile Copy("file.out", "tempfile") 

The Copy factory has a third optional argument which controls how symlinks are copied.

 # Symbolic link shallow copied as a new symbolic link: Command("LinkIn", "LinkOut", Copy("$TARGET", "$SOURCE", symlinks=True)) # Symbolic link target copied as a file or directory: Command("LinkIn", "FileOrDirectoryOut", Copy("$TARGET", "$SOURCE", symlinks=False)) 

 Command( "file.out", "file.in", action=[ Delete("tempfile"), Copy("tempfile", "$SOURCE"), "modify tempfile", Copy("$TARGET", "tempfile"), ], ) 

% scons -Q Delete("tempfile") Copy("tempfile", "file.in") modify tempfile Copy("file.out", "tempfile") 

Of course, like all of these Action factories, the Delete factory also expands $TARGET and $SOURCE variables appropriately. For example:

 Command( "file.out", "file.in", action=[ Delete("$TARGET"), Copy("$TARGET", "$SOURCE"), ], ) 

Executes as:

% scons -Q Delete("file.out") Copy("file.out", "file.in") 

Note, however, that you typically don't need to call the Delete factory explicitly in this way; by default, SCons deletes its target(s) for you before executing any action.

One word of caution about using the Delete factory: it has the same variable expansions available as any other factory, including the $SOURCE variable. Specifying Delete("$SOURCE") is not something you usually want to do!

 env = Environment() env.Program('prog', ['main.c', '#lib/foo1.c', 'foo2.c']) 

% scons -Q cc -o lib/foo1.o -c lib/foo1.c cc -o src/prog/foo2.o -c src/prog/foo2.c cc -o src/prog/main.o -c src/prog/main.c cc -o src/prog/prog src/prog/main.o lib/foo1.o src/prog/foo2.o 

(Notice that the lib/foo1.o object file is built in the same directory as its source file. See Chapter 15, Separating Source and Build Trees: Variant Directories, below, for information about how to build the object file in a different subdirectory.)

A couple of notes on top-relative paths:

 path = "#/include" print("path =", path) print("force-interpreted path =", Entry(path)) 

Which shows:

% scons -Q path = #/include force-interpreted path = include scons: `.' is up to date. 

 env = Environment() env.Program('prog', ['main.c', '/usr/joe/lib/foo1.c', 'foo2.c']) 

% scons -Q cc -o src/prog/foo2.o -c src/prog/foo2.c cc -o src/prog/main.o -c src/prog/main.c cc -o /usr/joe/lib/foo1.o -c /usr/joe/lib/foo1.c cc -o src/prog/prog src/prog/main.o /usr/joe/lib/foo1.o src/prog/foo2.o 

(As was the case with top-relative path names, notice that the /usr/joe/lib/foo1.o object file is built in the same directory as its source file. See Chapter 15, Separating Source and Build Trees: Variant Directories, below, for information about how to build the object file in a different subdirectory.)

In the previous example, each of the subsidiary SConscript files created its own construction environment by calling Environment separately. This obviously works fine, but if each program must be built with the same construction variables, it's cumbersome and error-prone to initialize separate construction environments in the same way over and over in each subsidiary SConscript file.

SCons supports the ability to export variables from an SConscript file so they can be imported by other SConscript files, thus allowing you to share common initialized values throughout your build hierarchy.

 env = Environment() Export('env') 

 env = Environment() debug = ARGUMENTS['debug'] Export('env', 'debug') 

 env = Environment() debug = ARGUMENTS['debug'] Export('env debug') 

 env = Environment() foo = "FOO" args = {"env": env, "bar": foo} Export(args) 

 Export(MODE="DEBUG", TARGET="arm") 

 SConscript('src/SConscript', 'env') 

 SConscript('src/SConscript', exports='env') 

 SConscript(['src1/SConscript', 'src2/SConscript'], exports='env') 

 Import('env') env.Program('prog', ['prog.c']) 

 Import('env', 'debug') env = env.Clone(DEBUG=debug) env.Program('prog', ['prog.c']) 

 Import('env debug') env = env.Clone(DEBUG=debug) env.Program('prog', ['prog.c']) 

 Import('*') env = env.Clone(DEBUG=debug) env.Program('prog', ['prog.c']) 

 env = Environment() Export('env') objs = [] for subdir in ['foo', 'bar']: o = SConscript('%s/SConscript' % subdir) objs.append(o) env.Library('prog', objs) 

 Import('env') obj = env.Object('foo.c') Return('obj') 

% scons -Q cc -o bar/bar.o -c bar/bar.c cc -o foo/foo.o -c foo/foo.c ar rc libprog.a foo/foo.o bar/bar.o ranlib libprog.a 

The most straightforward way to establish a variant directory tree relies on the fact that the usual way to set up a build hierarchy is to have an SConscript file in the source directory. If you pass a variant_dir argument to the SConscript function call:

 SConscript('src/SConscript', variant_dir='build') 

SCons will then build all of the files in the build directory:

% ls src SConscript hello.c % scons -Q cc -o build/hello.o -c build/hello.c cc -o build/hello build/hello.o % ls src SConscript hello.c % ls build SConscript hello hello.c hello.o 

No files were built in src: the object file build/hello.o and the executable file build/hello were built in the build directory, as expected. But notice that even though our hello.c file actually lives in the src directory, SCons has compiled a build/hello.c file to create the object file, and that file is now seen in build.

You can ask SCons to show the dependency tree to illustrate a bit more:

% scons -Q --tree=prune cc -o build/hello.o -c build/hello.c cc -o build/hello build/hello.o +-. +-SConstruct +-build | +-build/SConscript | +-build/hello | | +-build/hello.o | | +-build/hello.c | +-build/hello.c | +-[build/hello.o] +-src +-src/SConscript +-src/hello.c 

What's happened is that SCons has duplicated the hello.c file from the src directory to the build directory, and built the program from there (it also duplicated SConscript). The next section explains why SCons does this.

The nice thing about the SConscript approach is it is almost invisible to you: this build looks just like an ordinary in-place build except for the extra variant_dir argument in the SConscript call. SCons handles all the path adjustments for the out-of-tree build directory while it processes that SConscript file.

In most cases and with most tool sets, SCons can use sources directly from the source directory without duplicating them into the variant directory before building, and everything will work just fine. You can disable the default SCons duplication behavior by specifying duplicate=False when you call the SConscript function:

 SConscript('src/SConscript', variant_dir='build', duplicate=False) 

When this flag is specified, the results of a build look more like the mental model people may have from other build systems - that is, the output files end up in the variant directory while the source files do not.

 % ls src SConscript hello.c % scons -Q cc -c src/hello.c -o build/hello.o cc -o build/hello build/hello.o % ls build hello hello.o 

If disabling duplication causes any problems, just return to the more cautious approach by letting SCons go back to duplicating files.

You can also use the VariantDir function to establish that target files should be built in a separate directory tree from the source files:

 VariantDir('build', 'src') env = Environment() env.Program('build/hello.c') 

When using this form, you have to tell SCons that sources and targets are in the variant directory, and those references will trigger the remapping, necessary file copying, etc. for an already established variant directory. Here is the same example in a more spelled out form to show this more clearly:

 VariantDir('build', 'src') env = Environment() env.Program(target='build/hello', source=['build/hello.c']) 

When using the VariantDir function directly, SCons still duplicates the source files in the variant directory by default:

% ls src hello.c % scons -Q cc -o build/hello.o -c build/hello.c cc -o build/hello build/hello.o % ls build hello hello.c hello.o 

You can specify the same duplicate=False argument that you can specify for an SConscript call:

 VariantDir('build', 'src', duplicate=False) env = Environment() env.Program('build/hello.c') 

In which case SCons will disable duplication of the source files:

% ls src hello.c % scons -Q cc -o build/hello.o -c src/hello.c cc -o build/hello build/hello.o % ls build hello hello.o 

Even when using the VariantDir function, it is more natural to use it with a subsidiary SConscript file, because then you don't have to adjust your individual build instructions to use the variant directory path. For example, if the src/SConscript looks like this:

 env = Environment() env.Program('hello.c') 

Then our SConstruct file could look like:

 VariantDir('build', 'src') SConscript('build/SConscript') 

Yielding the following output:

% ls src SConscript hello.c % scons -Q cc -o build/hello.o -c build/hello.c cc -o build/hello build/hello.o % ls build SConscript hello hello.c hello.o 

This is completely equivalent to the use of SConscript with the variant_dir argument from earlier in this chapter, but did require calling the SConscript using the already established variant directory path to trigger that behavior. If you call SConscript('src/SConscript') you would get a normal in-place build in src.

The Glob file name pattern matching function works just as usual when using VariantDir. For example, if the src/SConscript looks like this:

 env = Environment() env.Program('hello', Glob('*.c')) 

Then with the same SConstruct file as in the previous section, and source files f1.c and f2.c in src, we would see the following output:

% ls src SConscript f1.c f2.c f2.h % scons -Q cc -o build/f1.o -c build/f1.c cc -o build/f2.o -c build/f2.c cc -o build/hello build/f1.o build/f2.o % ls build SConscript f1.c f1.o f2.c f2.h f2.o hello 

The Glob function returns Nodes in the build/ tree, as you'd expect.

 platform = ARGUMENTS.get('OS', Platform()) include = "#export/$PLATFORM/include" lib = "#export/$PLATFORM/lib" bin = "#export/$PLATFORM/bin" env = Environment( PLATFORM=platform, BINDIR=bin, INCDIR=include, LIBDIR=lib, CPPPATH=[include], LIBPATH=[lib], LIBS='world', ) Export('env') env.SConscript('src/SConscript', variant_dir='build/$PLATFORM') 

% scons -Q OS=linux Install file: "build/linux/world/world.h" as "export/linux/include/world.h" cc -o build/linux/hello/hello.o -c -Iexport/linux/include build/linux/hello/hello.c cc -o build/linux/world/world.o -c -Iexport/linux/include build/linux/world/world.c ar rc build/linux/world/libworld.a build/linux/world/world.o ranlib build/linux/world/libworld.a Install file: "build/linux/world/libworld.a" as "export/linux/lib/libworld.a" cc -o build/linux/hello/hello build/linux/hello/hello.o -Lexport/linux/lib -lworld Install file: "build/linux/hello/hello" as "export/linux/bin/hello" 

C:\>scons -Q OS=windows Install file: "build/windows/world/world.h" as "export/windows/include/world.h" cl /Fobuild\windows\hello\hello.obj /c build\windows\hello\hello.c /nologo /Iexport\windows\include cl /Fobuild\windows\world\world.obj /c build\windows\world\world.c /nologo /Iexport\windows\include lib /nologo /OUT:build\windows\world\world.lib build\windows\world\world.obj Install file: "build/windows/world/world.lib" as "export/windows/lib/world.lib" link /nologo /OUT:build\windows\hello\hello.exe /LIBPATH:export\windows\lib world.lib build\windows\hello\hello.obj embedManifestExeCheck(target, source, env) Install file: "build/windows/hello/hello.exe" as "export/windows/bin/hello.exe" 

In order to build several variants at once when using the variant_dir argument to SConscript, you can call the function repeatedly - this example does so in a loop. Note that the SConscript trick of passing a list of script files, or a list of source directories, does not work with variant_dir, SCons allows only a single SConscript to be given if variant_dir is used.

 env = Environment(OS=ARGUMENTS.get('OS')) for os in ['newell', 'post']: SConscript('src/SConscript', variant_dir='build/' + os) 

% scons -Q cc -o hello.o -c hello.c cc -o hello hello.o 

% scons -Q cc -o hello.o -c /usr/repository1/hello.c cc -o hello hello.o 

% scons -Q cc -o hello.o -c /usr/repository2/hello.c cc -o hello hello.o 

The Glob function understands about repositories, and will use the same matching algorithm as described for explicitly-listed sources.

You've already seen that SCons will scan the contents of a source file for #include file names and realize that targets built from that source file also depend on the #include file(s). For each directory in the $CPPPATH list, SCons will actually search the corresponding directories in any repository trees and establish the correct dependencies on any #include files that it finds in repository directory.

Unless the C compiler also knows about these directories in the repository trees, though, it will be unable to find the #include files. If, for example, the hello.c file in our previous example includes the hello.h in its current directory, and the hello.h only exists in the repository:

 % scons -Q cc -o hello.o -c hello.c hello.c:1: hello.h: No such file or directory 

In order to inform the C compiler about the repositories, SCons will add appropriate source file inclusion directives (-I or /I flags) to the compilation commands for each directory in the $CPPPATH list. So if you add the current directory to the construction environment $CPPPATH:

 env = Environment(CPPPATH=['.']) env.Program('hello.c') Repository('/usr/repository1') 

Then re-executing SCons yields:

% scons -Q cc -o hello.o -c -I. -I/usr/repository1 hello.c cc -o hello hello.o 

The order of the -I options replicates, for the C preprocessor, the same repository-directory search path that SCons uses for its own dependency analysis. If there are multiple repositories and multiple $CPPPATH directories, SCons will add the repository directories to the beginning of each $CPPPATH directory, rapidly multiplying the number of -I flags. If, for example, the $CPPPATH contains three directories (and shorter repository path names!):

 env = Environment(CPPPATH=['dir1', 'dir2', 'dir3']) env.Program('hello.c') Repository('/r1', '/r2') 

Then you'll end up with nine -I options on the command line, three (for each of the $CPPPATH directories) times three (for the local directory plus the two repositories):

% scons -Q cc -o hello.o -c -Idir1 -I/r1/dir1 -I/r2/dir1 -Idir2 -I/r1/dir2 -I/r2/dir2 -Idir3 -I/r1/dir3 -I/r2/dir3 hello.c cc -o hello hello.o 

 #include "hello.h" int main(int argc, char *argv[]) { printf(HELLO_MESSAGE); return (0); } 

% scons -Q cc -o hello.o -c -I. -I/usr/repository1 /usr/repository1/hello.c cc -o hello hello.o