This FAQ contains information about the SCons software construction tool.
The most recent and up-to-date version of this FAQ may always be found at:
http://scons.sourceforge.net/faq/current.html (HTML)
http://scons.sourceforge.net/faq/current.txt (text)
Please check to make sure your question hasn't already been answered in the latest version before submitting a new question (or an addition or correction to this FAQ).
This document is copyright 2001 by Steven Knight (knight at baldmt dot com).
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.
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 author at knight at baldmt dot com.
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.
The SCons download page is:
http://scons.sourceforge.net/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 CVS tree.
Instructions for Anonymous CVS access are available at:
http://sourceforge.net/cvs/?group_id=30337
Or you can browse the tree on-line at:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/scons/
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.
SCons is written to work with Python version 1.5.2 or any later version. Extensive tests are used to ensure that SCons works on all supported versions.
In order to install SCons from a source distribution, the Python Distutils package is required. Distutils is part of Python version 1.6 and higher. For Python 1.5.2, you can obtain the Distutils package from:
http://www.python.org/sigs/distutils-sig/
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.
Python 1.5.2 is still in widespread use on many systems, and was the version shipped by Red Hat as late as Red Hat 7.3. By writing the internal code so that it works on these systems, we're making it as easy as possible for more sites to install and work with SCons on as wide a variety of systems as possible.
"Why don't people just upgrade their Python version?" you may ask. Yes, Python's packaging and installation make it easy for people to upgrade versions, but that's not the only barrier.
In commercial development environments, any new operating system or language version must usually be accompanied by extensive tests to make sure that the upgrade hasn't introduced subtle problems or regressions into the code being produced. Consequently, upgrading is an expensive proposition that many sites can't undertake just because a new tool like SCons might require it. When faced with that sort of choice, it's much less risky and expensive for them to just walk away from trying the new tool.
No, you can write Python code in your SConscript file using any version of Python you have installed. The SCons internal code will run on Python 1.5.2, but that does not in any way affect what Python code it can execute in an SConscript file.
There are several SCons mailing lists, and they are archived. Information about the lists and archives is available at either:
http://scons.sourceforge.net/lists.html
http://sourceforge.net/mail/?group_id=30337
There is no SCons newsgroup.
Yes. SCons is distributed under the MIT license, an 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.
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 at scons-devel@lists.sourceforge.net and tell us what you're interested in doing.
| A: |
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
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 |
|
| A: |
By default, SCons only builds what you tell it to, and anything that these files depend on. If you want SCons to install all your targets, you have to tell it to do so somehow. There are two ways you might do this: 1. 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'))
2. 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:
env.Alias(target="install", source=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] |
|
| A: |
A common problem for new users is that SCons can't seem to find a compiler, linker or other utility that they can run just fine from the command line. This is almost always because, by default, SCons does not use the same PATH environment variable that you use from the command line, so it can't find a program that has been installed in a "non-standard" location unless you tell it how. Here is the explanation from the SCons man page:
scons does not automatically propagate the external environment used to execute scons to the commands used to build target files. This is so that builds will be guaranteed repeatable regardless of the environment variables set at the time scons is invoked. This also means that if the compiler or other commands that you want to use to build your target files are not in standard system locations, scons will not find them unless you explicitly set the PATH to include those locations. Fortunately, it's easy to propagate the PATH value from your external environment by initializing the ENV construction variable as follows:
import os
env = Environment(ENV = \{'PATH' : os.environ['PATH']\})
Alternatively, you might want to propagate your entire external environment to the build commands as follows:
import os
env = Environment(ENV = os.environ)
Of course, by propagating external environment variables into your build, you're running the risk that a change in the external environment will affect the build, possibly in unintended ways. The way to guarantee that the build is repeatable is to explicitly initialize the PATH
path = ['/bin', '/usr/bin', '/path/to/other/compiler/bin']
env = Environment(ENV = \{'PATH' : path\})
|
|
| A: |
SCons provides explicit support for getting information from programs like ldconfig and pkg-config. The relevant method is ParseConfig(), which executes a *-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. |
|
| A: |
The Microsoft linker requires that the environment variable TMP is set. I do the following in my SConstruct file.
env['ENV']['TMP'] = os.environ['TMP']
There are potential pitfalls for copying user environement variables into the build environment, but that is well documented. If you don't want to import from your external environment, set it to some directory explicitly. [Rich Hoesly, 18 November 2003] |
|
No. The SCons input files are Python scripts, with function calls to specify what you want built,
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://lnc.usc.edu/~holt/makepp/
Yes, SCons is designed from the ground up to support a -j option for parallel builds.
Yes. SCons supports a Repository feature and -Y 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 was written by Steven Knight and the original band of developers: Chad Austin, Charles Crain, Steve Leblanc, and Anthony Roach.
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://www.dsmit.com/cons/
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 exmple, 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.
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 was more than two 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...
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 indepent build tool that Software Carpentry may eventually produce.
Information about Software Carpentry is available at:
http://software-carpentry.codesourcery.com/