17.5. Builders That Create Actions Using a Generator
Prev | Chapter 17. Extending SCons: Writing Your Own Builders | Next

## 17.5. Builders That Create Actions Using a Generator

SCons Builder objects can create an action "on the fly" by using a function called a Generator. (Note: this is not the same thing as a Python generator function described in PEP 255) This provides a great deal of flexibility to construct just the right list of commands to build your target. A generator looks like:

    def generate_actions(source, target, env, for_signature):
        return 'foobuild < %s > %s' % (target[0], source[0])

The arguments of a generator are:

`source`

  A list of Node objects representing the sources to be built by the command or other action generated by this function. The file names of these source(s) may be extracted using the Python `str` function.

`target`

  A list of Node objects representing the target or targets to be built by the command or other action generated by this function. The file names of these target(s) may be extracted using the Python `str` function.

`env`

  The construction environment used for building the target(s). The generator may use any of the environment's construction variables in any way to determine what command or other action to return.

`for_signature`

  A flag that specifies whether the generator is being called to contribute to a build signature, as opposed to actually executing the command.

The generator must return a command string or other action that will be used to build the specified target(s) from the specified source(s).

Once you've defined a generator, you create a Builder to use it by specifying the `generator` keyword argument instead of `action`.

    def generate_actions(source, target, env, for_signature):
        return 'foobuild < %s > %s' % (source[0], target[0])

    bld = Builder(
        generator=generate_actions,
        suffix='.foo',
        src_suffix='.input',
    )
    env = Environment(BUILDERS={'Foo': bld})
    env.Foo('file')

    % scons -Q
    foobuild < file.input > file.foo

Note that it's illegal to specify both an `action` and a `generator` for a Builder.

Prev | Up | Next
17.4. Builders That Execute Python Functions | Home | 17.6. Builders That Modify the Target or Source Lists Using an Emitter