Frequently Asked Questions

This FAQ contains information about the SCons software construction tool.

The most frequently-asked frequently asked questions:

Why doesn't SCons find my compiler/linker/etc.? I can execute it just fine from the command line.
How do I install files? The Install() method doesn't do anything. In general, how do I build anything outside my current directory?

Contents

Frequently Asked Questions

General Information

What is SCons?

SCons is a software construction tool—that is, a superior alternative to the classic "Make" build tool that we all know and love.

SCons is implemented as a Python script and set of modules, and SCons "configuration files" are actually executed as Python scripts. This gives SCons many powerful capabilities not found in other software build tools.

Where do I get SCons?

The SCons download page is http://scons.org/pages/download.html

If you're interested in the [b]leading edge, you can take a look at what the developers are up to in the latest code checked in to the Git (git) tree. You can browse the tree on-line at https://github.com/SConsProject/scons or follow the instructions on that page to download the sources to your own machine. The master branch is the primary development branch.

What's the difference between the scons, scons-local, and scons-src packages?

We make SCons available in three distinct packages, for different purposes.

The scons package is the basic one for installing SCons on your system and using it or experimenting with it. You don't need any other package if you just want to try out SCons.

The scons-local package is one that you can execute standalone, out of a local directory. It's intended to be dropped in to and shipped with packages of other software that want to build with SCons, but which don't want to have to require that their users install SCons.

The scons-src package is the complete source tree, including everything we use to package SCons and all of the regression tests. You might want this one if you had concerns about whether SCons was working correctly on your operating system and wanted to run the regression tests.

What version of Python do I need?

SCons is written to work with any Python version >= 3.5 Extensive tests are used to ensure that SCons works on all supported versions.

Do I need to know how to program in Python to use SCons?

No, you can use SCons very successfully even if you don't know how to program in Python.

With SCons, you use Python functions to tell a central build engine about your input and output files. You can look at these simply as different commands that you use to specify what software (or other files) you want built. SCons takes care of the rest, including figuring out most of your dependencies.

Of course, if you do know Python, you can use its scripting capabilities to do more sophisticated things in your build: construct lists of files, manipulate file names dynamically, handle flow control (loops and conditionals) in your build process, etc.

Are there any SCons mailing lists or IRC Channels? Are they archived anywhere?

There are several SCons mailing lists, and they are archived. Information about the lists and archives is available at https://scons.org/lists.html .

There is a SCons Discord server at Discord Server.

There is a SCons IRC channel at libera. For a complete overview of how to best contact us, visit https://scons.org/contact.html .

Is SCons released under an Open Source license?

Yes. SCons is distributed under the MIT license, an OSI-approved Open Source license. This means you can use it, modify it, or even redistribute it without charge, so long as you maintain the license.

Can I help with SCons development?

Definitely. We're looking for any help possible:

Python programmers
documentation writers
web designers and/or administrators
testers (especially if you use a non-usual operating system or tool chain)

If you have time and/or resources to contribute, contact the SCons developers <scons-dev AT scons DOT org> and tell us what you're interested in doing. You may also want to check out http://scons.org/wiki/HowToContribute , for some ideas about how you can help us.

SCons Questions

Why doesn't SCons find my compiler/linker/etc.? I can execute it just fine from the command line.

For maximum consistency across build systems (various developer machines, CI build setups, containers, etc). SCons uses a restricted set of environment variables (called the Execution Environment in documentation) to launch external commands like compilers. It does not import environment variables rather it requires environment variables for called commands to be set explicitly, either by SCons itself, or by the build confifgration (or, often, a combination). That includes PATH, which is why you can have a program found just fine from your shell environment that SCons doesn't find (more prevalent on Windows, where most programs install into a unique directory).

The execution environment lives in the variable ENV in the construction environment used to launch a particular command. This variable is initialized as part of creating a new construction environment (Environment() call), which also causes the specified or default set of tools to be initialized. If you need to add to ENV, you can defer the tool initialization using this recipe (use the relevant set of tools, of course, if default isn't correct).

env = Environment(tools=[])
env.AppendENVPath('PATH', ['my', 'extra', 'paths'])
env.Tool('default')

You can also defer initialization for a single non-default tool in a similar way:

env = Environment()
env.AppendENVPath('PATH', mytool_path)
env.Tool("mytool")

There's an obsolete recipe that is still mentioned in various places on the Internet, that you are encouraged to AVOID. It is some variant of this:

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

The second line does a direct assignment to the ENV variable, which means any default values are lost, some of which may be important (see this question for an example). Instead, you should add to ENV. The Environment() call can't currently append, only assign, so it needs to be done after the environment is created, as above.

How do I get SCons to find my `#include` files?

If your program has #include files in various directories, SCons must somehow be told in which directories it should look for the #include files. You do this by setting the CPPPATH variable to the list of directories that contain .h files that you want to search for:

env = Environment(CPPPATH='inc')
env.Program('foo', 'foo.c')

SCons will add to the compilation command line(s) the right -I options, or whatever similar options are appropriate for the C or C++ compiler you're using. This makes your SCons-based build configuration portable.

Note specifically that you should not set the include directories directly in the CCFLAGS variable, as you might initially expect:

env = Environment(CCFLAGS='-Iinc')    # THIS IS INCORRECT!
env.Program('foo', 'foo.c')

This will make the program compile correctly, but SCons will not find the dependencies in the inc subdirectory and the program will not be rebuilt if any of those #include files change.

How do I install files? The Install() method doesn't do anything. In general, how do I build anything outside my current directory?

By default, SCons only builds what you tell it to, and anything that these files depend on (no matter where they live). If you don't specify differently, SCons builds "." (i.e., all the targets in and under the current directory). If you want SCons to build/install targets outside the current directory, you have to tell it to do so somehow. There are four ways you might do this:

Specify the full path name of the external target(s) on the command line. This will build the the target(s) and anything they need.
```
% scons /full/path/to/target
```
Specify a directory on the command line that is above the target(s) to be built. One example of this is to specify the root directory, which tells SCons to build everything it knows about.
```
% scons /
```
Use Default(). Any argument you pass to Default() will be built when the user just runs "scons" without explicitly specifying any targets to build. So, you'd say something like:
```
Default(env.Install(directory='my_install_dir', source='foo'))
```
Use Alias(). Alias allows you to attach a "pseudo target" to one or more files. Say you want a user to type "scons install" in order to install all your targets, just like a user might type "make install" for traditional make. Here is how you do that:
```
Alias("install", env.Install(dir="install_dir", source="foo"))
```
Note that you can call Alias() with a target of "install" as many times as you want with different source files, and SCons will build all of them when the user types "scons install".

[Charles Crain, 14 August 2003, updated by Greg Noel, 1 December 2008]

Why is my directory only updated the first time?

Like every other build system, SCons considers a directory used as a target as up-to-date if it exists. The first time you built, the directory wasn't there, so SCons ran the update command. Each time after that, the directory already existed, so SCons considered it up-to-date.

As a workaround, make the dependency on some file within the directory that's always updated:

env.Command('html_dir/index.html', Glob('rst/*.rst'),        'rst2html -o $TARGET.dir $SOURCES')

If there isn't such a file, create one and put something in it that changes every time you build (such as the date):

env.Command('html_dir/last_updated', Glob('rst/*.rst'), ['rst2html -o $TARGET.dir $SOURCES', 'date >$TARGET'])

I'm already using ldconfig, pkg-config, gtk-config, etc. Do I have to rewrite their logic to use SCons?

SCons provides explicit support for getting information from programs like ldconfig and pkg-config. The relevant method is ParseConfig(), which executes an external *-config command, parses the returned flags, and puts them in the environment through which the ParseConfig method is called:

env.ParseConfig('pkg-config --cflags --libs libxml')

If you need to provide some special-purpose processing, you can supply a function to process the flags and apply them to the environment in any way you want.

Linking on Windows gives me an error: LINK: fatal error LNK1104: cannot open file 'TEMPFILE'. How do I fix this?

The Microsoft linker requires that the environment variable TMP is set. This should automatically be imported into the SCons execution environment by the Windows platform module, but may have been clobbered later (look for places where this might happen and try to fix them). If needed, you can pull it in by hand like this:

env['ENV']['TMP'] = os.environ['TMP']

There are potential pitfalls for copying user environment variables into the build environment, but this particular variable is important, and okay to copy. If you don't want to import from your external environment, set it to some (writable) directory of your choice - Python has a tempfile module that can help you generate a suitable name.

[Rich Hoesly, 18 November 2003]

How do I prevent commands from being executed in parallel?

Use the SideEffect() method and specify the same dummy file for each target that shouldn't be built in parallel. Even if the file doesn't exist, SCons will prevent the simultaneous execution of commands that affect the dummy file. See the linked method page for examples.

Compatibility with make

Is SCons compatible with make?

No. The SCons input files are Python scripts, with function calls to specify what you want built,

Is there a Makefile-to-SCons or SCons-to-Makefile converter?

There are no current plans for a converter. The SCons architecture, however, leaves open the future possibility of wrapping a Makefile interpreter around the SCons internal build engine, to provide an alternate Make-like interface. Contact the SCons developers if this is something you're interested in helping build.

Note that a proof-of-concept for parsing Makefiles in a scripting language exists in the Perl-based implementation for Gary Holt's Make++ tool, which has its home page at http://makepp.sourceforge.net/

Does SCons support building in parallel, like make's -j option?

Yes, SCons is designed from the ground up to support a -j option for parallel builds.

Does SCons support something like VPATH in make?

Yes. SCons supports a Repository() method and a -Y command-line option that provide very similar functionality to VPATH, although without some inconsistencies that make VPATH somewhat difficult to use. These features are directly modeled on (read: stolen from) the corresponding features in the Cons tool.

SCons History and Background

Who wrote SCons?

SCons was written by Steven Knight and the original band of developers: Chad Austin, Charles Crain, Steve Leblanc, and Anthony Roach.

Is SCons the same as Cons?

No, SCons and Cons are not the same program, although their architectures are very closely related. The most obvious difference is that SCons is implemented in Python and uses Python scripts as its configuration files, while Cons is implemented in Perl and uses Perl scripts.

SCons is essentially a re-design of the Cons architecture (by one of the principal Cons implementors) to take advantage of Python's ease of use, and to add a number of improvements and enhancements to the architecture based on several years of experience working with Cons.

Information about the classic Cons tool is available at http://dsmit.com/cons/

So what can SCons do that Cons can't?

Although SCons was not started to be the anti-Cons, there are a number of features designed into SCons that are not present in the Cons architecture:

SCons is easier to extend for new file types. In Cons, these methods are hard-coded inside the script, and to create a new Builder or Scanner, you need to write some Perl for an undocumented internal interface. In SCons, there are factory methods that you call to create new Builders and Scanners.

SCons is more modular. Cons is pretty monolithic. SCons is designed from the ground up in separate modules that can be imported or not depending on your needs.

The SCons build engine (dependency management) is separate from the wrapper "scons" script. Consequently, you can use the build engine in any other piece of Python software. For example, you could even theoretically wrap it in another interface that would read up Makefiles (a la Gary Holt's make++ Perl script).

SCons dependencies can be between arbitrary objects, not just files. Dependencies are actually managed in an abstract "Node" base class, and specific subclasses (can) exist for files, database fields, lines within a file, etc. So you will be able to use SCons to update a file because a certain web page changed, or a value changed in a database, for example.

SCons has good parallel build (-j) support. Cons' recursive dependency descent makes it difficult to restructure for good parallel build support. SCons was designed from the ground up with a multithreaded tasking engine (courtesy Anthony Roach) that will keep N jobs going simultaneously, modulo waiting for dependent files to finish building.

Should I use Cons or SCons for my project?

Well, this is the SCons FAQ, so of course we'll recommend that you use SCons. That having been said...

Unfortunately, Cons classic is essentially a dead project at this point. The last release many years ago (May 2001) and no one is actively working on it. This is really too bad, because Cons is still a very useful tool, and could continue to help people solve build problems if it got some more development.

In contrast, SCons has a thriving development and user community, and we're releasing new functionality and fixes approximately once a month. SCons also has a virtual superset of Cons classic functionality, the only things really missing are some minor debugging capabilities that don't affect basic software builds.

So at this point, probably the only reason to prefer Cons over SCons is if you're a die-hard Perl fan who really can't stomach using Python for your software build configuration scripts, and the functionality you need from Cons works well enough that you don't need new features or bug fixes, or you can get by with fixing your own bugs. If that's your situation and Cons is a better fit for you, then more power to you. Maybe you could even help get Cons kick-started again...

Is SCons the same as the ScCons design from the Software Carpentry competition?

Yes. Same design, same developer, same goals, essentially the same tool.

SCons, however, is an independent project, and no longer directly associated with Software Carpentry. Hence, we dropped the middle 'c' to differentiate it slightly, and to make it a tiny bit easier to type.

Even though SCons is being developed independently, the goal is for SCons to be a flexible enough tool that it would fit in with any future tools that the Software Carpentry project may produce.

Note that, at last report, the Software Carpentry project renamed their tools with the prefix "qm"--the build tool being "qmbuild"--so there shouldn't be any confusion between SCons and any independent build tool that Software Carpentry may eventually produce.

Although the information about the original Software Carpentry competition doesn't seem to be available any more, the project lives on as a source of teaching materials to teach software development skills. See http://en.wikipedia.org/wiki/Software_Carpentry for details and further links.

Administrivia

Copyright

This document may be freely copied, redistributed, or modified for any purpose and without fee, provided that this copyright notice is not removed or altered.

Individual items from this document may be excerpted and redistributed without inclusion of the copyright notice.

If you incorporate this FAQ in any commercial, salable, or for-profit collection or product, please be courteous and send a copy to the copyright holder.

Feedback

Any and all feedback on this FAQ is welcome: corrections to existing answers, suggested new questions, typographical errors, better organization of questions, etc. Contact the the user mailing list <scons-users AT scons DOT org>.