Thank you for taking the time to read about SCons. SCons is a next-generation software construction tool, or make tool--that is, a software utility for building software (or other files) and keeping built software up-to-date whenever the underlying input files change.
The most distinctive thing about SCons is that its configuration files are actually scripts, written in the Python programming language. This is in contrast to most alternative build tools, which typically invent a new language to configure the build. SCons still has a learning curve, of course, because you have to know what functions to call to set up your build properly, but the underlying syntax used should be familiar to anyone who has ever looked at a Python script.
Paradoxically, using Python as the configuration file format makes SCons easier for non-programmers to learn than the cryptic languages of other build tools, which are usually invented by programmers for other programmers. This is in no small part due to the consistency and readability that are built in to Python. It just so happens that making a real, live scripting language the basis for the configuration files makes it a snap for more accomplished programmers to do more complicated things with builds, as necessary.
There are a few overriding principles we try to live up to in designing and implementing SCons:
First and foremost, by default, SCons guarantees a correct build even if it means sacrificing performance a little. We strive to guarantee the build is correct regardless of how the software being built is structured, how it may have been written, or how unusual the tools are that build it.
Given that the build is correct, we try to make SCons build software as quickly as possible. In particular, wherever we may have needed to slow down the default SCons behavior to guarantee a correct build, we also try to make it easy to speed up SCons through optimization options that let you trade off guaranteed correctness in all end cases for a speedier build in the usual cases.
SCons tries to do as much for you out of the box as reasonable, including detecting the right tools on your system and using them correctly to build the software.
In a nutshell, we try hard to make SCons just "do the right thing" and build software correctly, with a minimum of hassles.
One word of warning as you read through this Guide: Like too much Open Source software out there, the SCons documentation isn't always kept up-to-date with the available features. In other words, there's a lot that SCons can do that isn't yet covered in this User's Guide. (Come to think of it, that also describes a lot of proprietary software, doesn't it?)
Although this User's Guide isn't as complete as we'd like it to be, our development process does emphasize making sure that the SCons man page is kept up-to-date with new features. So if you're trying to figure out how to do something that SCons supports but can't find enough (or any) information here, it would be worth your while to look at the man page to see if the information is covered there. And if you do, maybe you'd even consider contributing a section to the User's Guide so the next person looking for that information won't have to go through the same thing...?
SCons would not exist without a lot of help from a lot of people, many of whom may not even be aware that they helped or served as inspiration. So in no particular order, and at the risk of leaving out someone:
First and foremost, SCons owes a tremendous debt to Bob Sidebotham, the original author of the classic Perl-based Cons tool which Bob first released to the world back around 1996. Bob's work on Cons classic provided the underlying architecture and model of specifying a build configuration using a real scripting language. My real-world experience working on Cons informed many of the design decisions in SCons, including the improved parallel build support, making Builder objects easily definable by users, and separating the build engine from the wrapping interface.
Greg Wilson was instrumental in getting SCons started as a real project when he initiated the Software Carpentry design competition in February 2000. Without that nudge, marrying the advantages of the Cons classic architecture with the readability of Python might have just stayed no more than a nice idea.
The entire SCons team have been absolutely wonderful to work with, and SCons would be nowhere near as useful a tool without the energy, enthusiasm and time people have contributed over the past few years. The "core team" of Chad Austin, Anthony Roach, Bill Deegan, Charles Crain, Steve Leblanc, Greg Noel, Gary Oberbrunner, Greg Spencer and Christoph Wiedemann have been great about reviewing my (and other) changes and catching problems before they get in the code base. Of particular technical note: Anthony's outstanding and innovative work on the tasking engine has given SCons a vastly superior parallel build model; Charles has been the master of the crucial Node infrastructure; Christoph's work on the Configure infrastructure has added crucial Autoconf-like functionality; and Greg has provided excellent support for Microsoft Visual Studio.
Special thanks to David Snopek for contributing his underlying "Autoscons" code that formed the basis of Christoph's work with the Configure functionality. David was extremely generous in making this code available to SCons, given that he initially released it under the GPL and SCons is released under a less-restrictive MIT-style license.
Thanks to Peter Miller for his splendid change management system, Aegis, which has provided the SCons project with a robust development methodology from day one, and which showed me how you could integrate incremental regression tests into a practical development cycle (years before eXtreme Programming arrived on the scene).
And last, thanks to Guido van Rossum for his elegant scripting language, which is the basis not only for the SCons implementation, but for the interface itself.
The best way to contact people involved with SCons, including the author, is through the SCons mailing lists.
If you want to ask general questions about how to use SCons send email to users@scons.tigris.org.
If you want to contact the SCons development community directly, send email to dev@scons.tigris.org.
If you want to receive announcements about SCons, join the low-volume announce@scons.tigris.org mailing list.
This chapter will take you through the basic steps of installing SCons on your system, and building SCons if you don't have a pre-built package available (or simply prefer the flexibility of building it yourself). Before that, however, this chapter will also describe the basic steps involved in installing Python on your system, in case that is necessary. Fortunately, both SCons and Python are very easy to install on almost any system, and Python already comes installed on many systems.
Because SCons is written in Python, you must obviously have Python installed on your system to use SCons. Before you try to install Python, you should check to see if Python is already available on your system by typing python -V (capital 'V') or python --version at your system's command-line prompt.
$ python -V
Python 2.5.1
And on a Windows system with Python installed:
C:\>python -V
Python 2.5.1
If Python is not installed on your system, 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 progam or batch file" (on Windows). In that case, you need to install Python before you can install SCons.
(Note that the -V option
was added to Python version 2.0,
so if your system only has an earlier version available
you may see an
"Unknown option: -V"
error message.)
The standard location for information about downloading and installing Python is http://www.python.org/download/. See that page for information about how to download and install Python on your system.
SCons will work with any version of Python from 1.5.2 or later. If you need to install Python and have a choice, we recommend using the most recent Python 2.5 version available. Python 2.5 has significant improvements the help speed up the performance of SCons'.
SCons comes pre-packaged for installation on a number of systems, including Linux and Windows systems. You do not need to read this entire section, you should only need to read the section appropriate to the type of system you're running on.
SCons comes in RPM (Red Hat Package Manager) format, pre-built and ready to install on Red Hat Linux, Fedora Core, or any other Linux distribution that uses RPM. Your distribution may already have an SCons RPM built specifically for it; many do, including SuSe, Mandrake and Fedora. You can check for the availability of an SCons RPM on your distribution's download servers, or by consulting an RPM search site like http://www.rpmfind.net/ or http://rpm.pbone.net/.
If your Linux distribution does not already have a specific SCons RPM file, you can download and install from the generic RPM provided by the SCons project. This will install the SCons script(s) in /usr/bin, and the SCons library modules in /usr/lib/scons.
To install from the command line, simply download the appropriate .rpm file, and then run:
# rpm -Uvh scons-0.96-1.noarch.rpm
Or, you can use a graphical RPM package manager like gnorpm. See your package manager application's documention for specific instructions about how to use it to install a downloaded RPM.
Debian Linux systems use a different package management format that also makes it very easy to install SCons.
If your system is connected to the Internet, you can install the latest official Debian package by running:
# apt-get install scons
SCons provides a Windows installer that makes installation extremely easy. Download the scons-0.95.win32.exe file from the SCons download page at http://www.scons.org/download.html. Then all you need to do is execute the file (usually by clicking on its icon in Windows Explorer). These will take you through a small sequence of windows that will install SCons on your system.
If a pre-built SCons package is not available for your system, then you can still easily build and install SCons using the native Python distutils package.
The first step is to download either the scons-__VERSION__.tar.gz or scons-__VERSION__.zip, which are available from the SCons download page at http://www.scons.org/download.html.
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-__VERSION__, usually in your local directory. Then change your working directory to that directory and install SCons by executing the following commands:
# cd scons-__VERSION__
#