This repository contains contributed software to use with SCons. These contributions enable the use of additional tools, builders, and other components that are not part of mainline SCons. Many of these were previously (or still are) on the wiki, but it's harder to extract code snippets from wiki pages, and the wiki pages arn't always maintained (e.g. support for Python 3) so some of the popular ones are collected here for convenience.
The tools in this repository are intended to be used with Python 3. If necessary, they have been converted with 2to3, and reformatted with Black. The original versions of the tools are available in the python27 branch if you need versions that worked wtih Python 2.
Contribute new tools by making a Pull Request on this repository. Please create a new directory per contribution. (We may re-organize this it becomes obvious that doing so would make it easier for users to find useful logic.) Please include a README file (README.rst or other form) describing any information about your tool, including the license it is released under. If at all possible, please use the MIT license that SCons itself is released under, for maximum license compatibility, but that is not mandatory as long as the actual license is clearly indicated.
Tools in this repository are available under their listed licence (see the respective README files). If no license is called out specifically, the tool is available under the same MIT license SCons is released under. If the license is not MIT, make sure you are okay to include the tool in your project under its terms.
These are not "supported" directly by the SCons project. For problems/discussion, please file an Issue or raise a Pull Request against this project. Several of the original authors are not hanging around here, so you may need to be a little patient or propose fixes yourself.
The tools are organized as a collection of individual directories under sconscontrib/SCons/Tool. When you activate a tool in SCons, it pulls it in via Python's import system. This broadly means any tool you want to use needs to be findable by Python, in sys.path, which when running SCons includes several special directories. For more information on this, see the SCons Manual page under Tools and site-dir
You can manually place tools in a findable place, or you can use pip to install to the same place that version of Python puts SCons itself.
To install using a setuptools backed method (pip or setup.py), you must be using SCons 4.0 or newer. If you are using an older version of SCons, see the Manual Installation instructions.
For installing via pip, you need to point directly to the code repostory, as this collection is not available on the Python Package Index:
python -m pip install --user git+https://github.com/SCons/scons-contrib.gitThis puts all of the tools into the `Tool subdirectory of the SCons installation, in other words, in the same place SCons looks for its own built-in tools. Usually you don't have permission to write here, so the --user` option is used to put them into a parallel writable location specific to your account.
The SCons project generally recommends that you use a Python virtualenv to set up SCons, because you can keep the dependencies isolated from others. Since many of the contributed tools use other facilities (for example the Sphinx tools require Sphinx itself, which requires quite a few other Python packages) this avoids installing a lot of dependnecies into your system install of Python (even if they went into the user location). Inside an activated virtualenv you can use the somewhat simpler:
pip install git+https://github.com/SCons/scons-contrib.gitThere's an alternate installation style you can perform as well -clone the scons-contrib repository yourself and then run setup manually:
git clone https://github.com/SCons/scons-contrib.git
cd scons-contrib
python setup.py installThe Python packaging experts no longer recommend any project call setup.py manually, and since the pip install command pointing to the remote code repository does basically the same thing behind the covers but more cleanly/safely, this alternate install is no longer recommended, unless there's a reason pip cannot be used to point to a code repository (company security policy, perhaps?)
Installing via pip results in all of the contrib tools being installed at once. If you just want a specific tool or two, a manual installation may be a better choice.
To do this, clone the repository:
git clone https://github.com/SCons/scons-contrib.gitand copy the required tool directory into one of the locations SCons searches for tools. Often the preferred choice is to copy it to the project's site_scons/site_tools.
Roughly speaking, there are three (operating system-specific) locations that are searched by default: a system-wide location, a user-account location, and a location insde a specific project (which is the path listed above). These default locations are listed by operating system in the SCons Manual Page.
In addition to the defaults as places to search, the project-level site directory can be changed by supplying the --site-dir option, and SCons can also be given additional locations to look for tools using the toolpath parameter when creating a Construction Environment.
The choice of which one of these to use depends on the intended scope - whether the tool is to be used for many projects or just for one, etc.
Once a tool is used, it needs to be activated for actual use. SCons searches for various default tools, and activates them if found, but must be asked to look at others, whether built-in or added later. In most cases this is done by giving a list of desired tools for a given construction environment when it is created:
env = Environment(tools=['default', 'mytool'])The SCons contrib package requires you to have scons installed. If any individual tool package has dependencies, they will also be pulled in during an installation using pip. For manual installation, you will need to satisfy any Python package requirements manually.
- Implement more commands/builders/tools.
- Set up "subpackage" type installs, so that
pip installof an individual tool is possible.