SCons - a software construction tool

Welcome to the SCons development tree. The real purpose of this tree is to package SCons for production distribution in a variety of formats, not just to hack SCons code.

If all you want to do is install and run SCons, it will be easier for you to download and install the scons-{version}.tar.gz or scons-{version}.zip package rather than to work with the packaging logic in this tree.

To the extent that this tree is about building SCons packages, the full development cycle is not just to test the code directly, but to package SCons, unpack the package, "install" SCons in a test subdirectory, and then to run the tests against the unpacked and installed software. This helps eliminate problems caused by, for example, failure to update the list of files to be packaged.

For just working on making an individual change to the SCons source, however, you don't actually need to build or install SCons; you can actually edit and execute SCons in-place. See the following sections below for more information:

MAKING CHANGES
    How to edit and execute SCons in-place.

DEBUGGING
    Tips for debugging problems in SCons.

TESTING
    How to use the automated regression tests.

DEVELOPMENT WORKFLOW
    An example of how to put the edit/execute/test pieces
    together in a reasonable development workflow.

LATEST VERSION

Before going further, you can check that this package you have is the latest version at the SCons download page:

    http://www.scons.org/download.php

EXECUTION REQUIREMENTS

Running SCons requires Python version 2.4 or later. There should be no other dependencies or requirements to run SCons.

The default SCons configuration assumes use of the Microsoft Visual C++ compiler suite on WIN32 systems, and assumes a C compiler named 'cc', a C++ compiler named 'c++', and a Fortran compiler named 'g77' (such as found in the GNU C compiler suite) on any other type of system. You may, of course, override these default values by appropriate configuration of Environment construction variables.

By default, SCons knows how to search for available programming tools on various systems--see the SCons man page for details. You may, of course, override the default SCons choices made by appropriate configuration of Environment construction variables.

INSTALLATION REQUIREMENTS

Nothing special.

EXECUTING SCONS WITHOUT INSTALLING

You can execute the local SCons directly from the src/ subdirectory by first setting the SCONS_LIB_DIR environment variable to the local src/engine subdirectory, and then executing the local src/script/scons.py script to populate the build/scons/ subdirectory. You would do this as follows on a Linux or UNIX system (using sh or a derivative like bash or ksh):

    $ setenv MYSCONS=`pwd`/src
    $ setenv SCONS_LIB_DIR=$MYSCONS/engine
    $ python $MYSCONS/script/scons.py [arguments]

Or on Windows:

    C:\scons>set MYSCONS=%cd%\src
    C:\scons>set SCONS_LIB_DIR=%MYSCONS%\engine
    C:\scons>python %MYSCONS%\script\scons.py [arguments]

An alternative approach is to skip the above and use:

    $ python bootstrap.py [arguments]

bootstrap.py keeps the src/ subdirectory free of compiled Python (*.pyc or *.pyo) files by copying the necessary SCons files to a local bootstrap/ subdirectory and executing it from there.

You can use the -C option to have SCons change directory to another location where you already have a build configuration set up.

$ python bootstrap.py -C /some/other/location [arguments]

For simplicity in the following examples, we will only show the bootstrap.py approach.

INSTALLATION

NOTE: You don't need to build SCons packages or install SCons if
you just want to work on developing a patch.  See the sections
about MAKING CHANGES and TESTING below if you just want to submit
a bug fix or some new functionality.  See the sections below about
BUILDING PACKAGES and TESTING PACKAGES if your enhancement involves
changing the way in which SCons is packaged and/or installed on an
end-user system.

Assuming your system satisfies the installation requirements in the previous section, install SCons from this package by first populating the build/scons/ subdirectory. (For an easier way to install SCons, without having to populate this directory, use the scons-{version}.tar.gz or scons-{version}.zip package.)

Populate build/scons/ using a pre-installed SCons

If you already have an appropriate version of SCons installed on your system, populate the build/scons/ directory by running:

    $ scons build/scons

Populate build/scons/ using the SCons source

You can also use this version of SCons to populate its own build directory by using a supplied bootstrap.py script (see the section above about EXECUTING SCONS WITHOUT INSTALLING):

    $ python bootstrap.py build/scons

Install the built SCons files

Any of the above commands will populate the build/scons/ directory with the necessary files and directory structure to use the Python-standard setup script as follows on Linux or UNIX:

    # cd build/scons
    # python setup.py install

Or on Windows:

    C:\scons\>cd build\scons
    C:\scons\build\scons>python setup.py install

By default, the above commands will do the following:

--  Install the version-numbered "scons-2.0.0" and "sconsign-2.0.0"
    scripts in the default system script directory (/usr/bin or
    C:\Python*\Scripts, for example).  This can be disabled by
    specifying the "--no-version-script" option on the command
    line.

--  Install scripts named "scons" and "sconsign" scripts in the
    default system script directory (/usr/bin or C:\Python*\Scripts,
    for example).  This can be disabled by specifying the
    "--no-scons-script" option on the command line, which is useful
    if you want to install and experiment with a new version before
    making it the default on your system.

    On UNIX or Linux systems, you can have the "scons" and "sconsign"
    scripts be hard links or symbolic links to the "scons-2.0.0" and
    "sconsign-2.0.0" scripts by specifying the "--hardlink-scons" or
    "--symlink-scons" options on the command line.

--  Install "scons-2.0.0.bat" and "scons.bat" wrapper scripts in the
    Python prefix directory on Windows (C:\Python*, for example).
    This can be disabled by specifying the "--no-install-bat" option
    on the command line.

    On UNIX or Linux systems, the "--install-bat" option may be
    specified to have "scons-2.0.0.bat" and "scons.bat" files installed
    in the default system script directory, which is useful if you
    want to install SCons in a shared file system directory that can
    be used to execute SCons from both UNIX/Linux and Windows systems.

--  Install the SCons build engine (a Python module) in an
    appropriate version-numbered SCons library directory
    (/usr/lib/scons-2.0.0 or C:\Python*\scons-2.0.0, for example).
    See below for more options related to installing the build
    engine library.

--  Install the troff-format man pages in an appropriate directory
    on UNIX or Linux systems (/usr/share/man/man1 or /usr/man/man1,
    for example).  This can be disabled by specifying the
    "--no-install-man" option on the command line.  The man pages
    can be installed on Windows systems by specifying the
    "--install-man" option on the command line.

Note that, by default, SCons does not install its build engine library in the standard Python library directories. If you want to be able to use the SCons library modules (the build engine) in other Python scripts, specify the "--standard-lib" option on the command line, as follows:

    # python setup.py install --standard-lib

This will install the build engine in the standard Python library directory (/usr/lib/python*/site-packages or C:\Python*\Lib\site-packages).

Alternatively, you can have SCons install its build engine library in a hard-coded standalone library directory, instead of the default version-numbered directory, by specifying the "--standalone-lib" option on the command line, as follows:

    # python setup.py install --standalone-lib

This is usually not recommended, however.

Note that, to install SCons in any of the above system directories, you should have system installation privileges (that is, "root" or "Administrator") when running the setup.py script. If you don't have system installation privileges, you can use the --prefix option to specify an alternate installation location, such as your home directory:

    $ python setup.py install --prefix=$HOME

This will install SCons in the appropriate locations relative to $HOME--that is, the scons script itself $HOME/bin and the associated library in $HOME/lib/scons, for example.

MAKING CHANGES

Because SCons is implemented in a scripting language, you don't need to build it in order to make changes and test them.

Virtually all of the SCons functionality exists in the "build engine," the src/engine/SCons subdirectory hierarchy that contains all of the modules that make up SCons. The src/script/scons.py wrapper script exists mainly to find the appropriate build engine library and then execute it.

In order to make your own changes locally and test them by hand, simply edit modules in the local src/engine/SCons subdirectory tree and use the local bootstrap.py script (see the section above about EXECUTING SCONS WITHOUT INSTALLING):

$ python bootstrap.py [arguments]

If you want to be a