Adding to a CompositeBuilder

[mwichmann]

If you want to write a tool to help taking sources of a new type, but that will produce a file type that SCons already has a builder for, the procedure is somewhat different than just writing a builder. As an example of a core tool that does this, swig takes interface files (.i) and can generate C/C++ files (as well as Java). That means it needs to hook into the existing CFile, CXXFile and Java builders, which are of type CompositeBuilder. A CompositeBuilder has add_action and add_emitter methods, and a suffix attribute, and SCons has convenience methods for obtaining the existing builder instance so those methods can be called on it. However, all of this stuff is set up so while it's easily available to internal tools (in SCons/Tool), there's no description of how to do this in a user-written tool. Even the API docs are quite lacking - some of the important stuff is in comments rather than docstrings and thus not picked up by Sphinx, and some of the convenience methods like createJavaFileBuilder have no docstring at all.

Proposing that a recipe in the cookbook might be useful.