Please note:The SCons wiki is in read-only mode due to ongoing spam/DoS issues. Also, new account creation is currently disabled. We are looking into alternative wiki hosts.

Introduction

SCons core provides tools implemented as Python modules. This is fine for tools that are part of the SCons distribution, but for contributed tools supported separately from the SCons code repository, using modules is not the best architecture. Fortunately, SCons allows for tools to be implemented as Python packages (i.e. directories with a file __init__.py). This allows for tools to be managed as packages in distributed version control system (DVCS) branches and repositories -- a Python package is a directory and directories not files are the top-level thing managed by a DVCS (which is why it is easier to deal with packages rather than modules using a DVCS).

To manage tools that are not part of SCons core, or provide enhancements for core tools independently, a DVCS (e.g. Mercurial, Git, Bazaar) repository (branch in Bazaar) should be created and the directory should contain a file __init__.py so that it is a package in the Python sense. The tool can then be installed by cloning (branching in Bazaar) the repository into the site_scons/site_tools directory.

No matter which DVCS and hosting site is used for a given tool, it should be indexed on this page: this page is the central index of all contributed tools. The index works best where there is a wiki page explaining the tool linked to by the entry in the first column of the tool list.

Install and usage

Installing an external Tool requires you to clone (branch in Bazaar) the contents of the package's folder to

1. /path_to_your_project/site_scons/site_tools/foo, if you need the foo Tool in one project only, or

2. ~/.scons/site_scons/site_tools/foo, for a personal installation of foo that can be used by you for all your projects (SCons 2.1 and later).

In SCons 2.1 and later, the following paths are tried in order to detect SCons specific settings, like the site_scons/site_tools folder:

OS (Platform)

Path

Windows (win32/cygwin)

$ALLUSERSPROFILE\Application Data\scons

$USERPROFILE\Local Settings\Application Data\scons

$APPDATA\scons

~\.scons

MacOS X (darwin)

/Library/Application Support/SCons

/opt/local/share/scons

/sw/share/scons

~/Library/Application Support/SCons

~/.scons

Solaris (sunos)

/opt/sfw/scons

/usr/share/scons

~/.scons

Linux/HPUX/... (other)

/usr/share/scons

~/.scons

(see also sect. 19.7 http://scons.org/doc/production/HTML/scons-user/x3697.html in the User's Guide).

This makes the tool available but it must be included explicitly in a SCons build by creating an Environment with a tools entry since only named tools from the SCons core are initialized automatically when SCons runs. Example:

  # Create environment and init Tool foo
  env = Environment(tools=['foo'])

  # Use the builder, provided by the Tool foo
  env.Foo(Glob('*.foo'))

Have a pick (the actual index)

The index of Tools maintained outside of SCons repository:

Name

DVCS

Location

Branch/Clone command

Chapel

Mercurial

https://bitbucket.org/russel/scons_chapel

hg clone https://bitbucket.org/russel/scons_chapel chapel

C#

Mercurial

https://bitbucket.org/russel/scons_csharp

hg clone https://bitbucket.org/russel/scons_csharp csharp

CPython

Mercurial

https://bitbucket.org/dirkbaechle/scons_cpython

hg clone https://bitbucket.org/dirkbaechle/scons_cpython cpython

D (*)

Docbook

Mercurial

https://bitbucket.org/dirkbaechle/scons_docbook

hg clone https://bitbucket.org/dirkbaechle/scons_docbook docbook

Doxyfile

Git

https://github.com/ptomulik/scons-tool-doxyfile

git clone https://github.com/ptomulik/scons-tool-doxyfile

Doxygen

Mercurial

https://bitbucket.org/russel/scons_doxygen

hg clone https://bitbucket.org/russel/scons_doxygen doxygen

dvipdfm

Git

https://github.com/ptomulik/scons-tool-dvipdfm

git clone https://github.com/ptomulik/scons-tool-dvipdfm dvipdfm

Eiffel

Bazaar

https://launchpad.net/scons-eiffel

bzr branch lp:scons-eiffel eiffel

Erlang

Mercurial

https://bitbucket.org/russel/scons_erlang

hg clone https://bitbucket.org/russel/scons_erlang erlang

fastcpp

Mercurial

https://bitbucket.org/dirkbaechle/scons_fastcpp

hg clone https://bitbucket.org/dirkbaechle/scons_fastcpp fastcpp

GccCov

Git

https://github.com/ptomulik/scons-tool-gcccov

git clone https://github.com/ptomulik/scons-tool-gcccov gcccov

Go

Mercurial

https://bitbucket.org/russel/scons-go-tool

hg clone https://bitbucket.org/russel/scons-go-tool go

Gnuplot

Git

https://github.com/ptomulik/scons-tool-gnuplot

git clone https://github.com/ptomulik/scons-tool-gnuplot gnuplot

Go

Git

http://github.com/alberts/goscons/tree/master/goscons/

git clone git://github.com/alberts/goscons.git

GObject (gob2)

Mercurial

https://bitbucket.org/dirkbaechle/scons_gob2

hg clone https://bitbucket.org/dirkbaechle/scons_gob2 gob2

Haskell

Mercurial

https://bitbucket.org/russel/scons_haskell

hg clone https://bitbucket.org/russel/scons_haskell haskell

Jinja2

Git

https://github.com/hgomersall/scons-jinja

git clone https://github.com/hgomersall/scons-jinja jinja

Matlab (Mex)

Git

https://github.com/marcecj/scons_matlab

git clone https://github.com/marcecj/scons_matlab matlab

MFObject

Bazaar

https://code.launchpad.net/~asomers/sconsaddons/mfobject

bzr branch lp:~asomers/sconsaddons/mfobject

OCaml

Mercurial

https://bitbucket.org/russel/scons_ocaml

hg clone https://bitbucket.org/russel/scons_ocaml ocaml

Protocol Buffers

Mercurial

https://bitbucket.org/russel/scons_protobuf

hg clone https://bitbucket.org/russel/scons_protobuf protoc

Qt4

Mercurial

https://bitbucket.org/dirkbaechle/scons_qt4

hg clone https://bitbucket.org/dirkbaechle/scons_qt4 qt4

Qt5

Mercurial

https://bitbucket.org/dirkbaechle/scons_qt5

hg clone https://bitbucket.org/dirkbaechle/scons_qt5 qt5

reST (docutils)

Mercurial

https://bitbucket.org/dirkbaechle/scons_rest

hg clone https://bitbucket.org/dirkbaechle/scons_rest rest

RightNow

Bazaar

https://code.launchpad.net/~asomers/sconsaddons/rightnow

bzr branch lp:~asomers/sconsaddons/rightnow

Sphinx

Mercurial

http://bitbucket.org/zondo/sphinx-scons/overview

hg clone https://bitbucket.org/zondo/sphinx-scons

sphinx4scons

Mercurial

https://bitbucket.org/wingbrant/sphinx4scons/

hg clone https://bitbucket.org/wingbrant/sphinx4scons

Vala

Mercurial

https://bitbucket.org/russel/scons_vala

hg clone https://bitbucket.org/russel/scons_vala vala

Watcom

Git

http://code.google.com/p/scons-wat/

git clone http://code.google.com/p/scons-wat/ watcom

X10

Mercurial

https://bitbucket.org/russel/scons_x10

hg clone https://bitbucket.org/russel/scons_x10 x10

(*) The D tool is no longer developed outside of the SCons source tree (as it once was) to enable correct integration between D, C++ and C in multi-language systems. D tool development now happens in a clone of the SCons repository specifically for developing the D tool.

Workflows

If you simply want to use the Tools above, or have a look at the sources, issue the command given in the Branch/Clone column. This will give you a local copy to work with.

Patching or extending and then, finally, contributing your code, needs a little more effort. For each DVCS, the following sections try to outline the required steps.

Mercurial/BitBucket

If you just want to create a read-only copy of the tool then just use "hg clone . . . ". If you are wanting to get involved in development of the tool then you will need a writeable clone.

Bazaar/Launchpad

We assume that you have initially branched an existing tool, modified it and want to publish your changes.

Please also regard the special page ToolsBazaarWorkflows, it contains more info about

In many ways all branches for a given tool are equal; all branches are effectively forks of the tool. The mainline is the one agreed to be the mainline and is the one to be indexed above.

For more detailed infos about Bazaar and DVCS in general, you should also visit the UsingBzr page.

ToolsIndex (last edited 2014-03-01 18:44:29 by ptomulik)