17.7. Modifying a Builder by adding an Emitter
Prev | Chapter 17. Extending SCons: Writing Your Own Builders | Next

## 17.7. Modifying a Builder by adding an Emitter

Defining an emitter to work with a custom Builder is a powerful concept, but sometimes all you really want is to be able to use an existing builder but change its concept of what targets are created. In this case, trying to recreate the logic of an existing Builder to supply a special emitter can be a lot of work. The typical case for this is when you want to use a compiler flag that causes additional files to be generated. For example the GNU linker accepts an option `-Map` which outputs a link map to the file specified by the option's argument. If this option is just supplied to the build, SCons will not consider the link map file a tracked target, which has various undesirable efffects.

To help with this, SCons provides construction variables which correspond to a few standard builders: `$PROGEMITTER` for `Program`; `$LIBEMITTER` for `Library`; `$SHLIBEMITTER` for `SharedLibrary` and `$LDMODULEEMITTER` for `LoadableModule`;. Adding an emitter to one of these will cause it to be invoked in addition to any existing emitter for the corresponding builder.

This example adds map creation as a linker flag, and modifies the standard `Program` emitter to know that map generation is a side-effect:

    env = Environment()
    map_filename = "${TARGET.name}.map"

    def map_emitter(target, source, env):
        target.append(map_filename)
        return target, source

    env.Append(LINKFLAGS="-Wl,-Map={},--cref".format(map_filename))
    env.Append(PROGEMITTER=map_emitter)
    env.Program('hello.c')

If you run this example, adding an option to tell SCons to dump some information about the dependencies it knows, it shows the map file option in use, and that SCons indeed knows about the map file, it's not just a silent side effect of the compiler:

    % scons -Q --tree=prune
    cc -o hello.o -c hello.c
    cc -o hello -Wl,-Map=hello.map,--cref hello.o
    +-.
      +-SConstruct
      +-hello
      | +-hello.o
      |   +-hello.c
      +-hello.c
      +-hello.map
      | +-[hello.o]
      +-[hello.o]

Prev | Up | Next
17.6. Builders That Modify the Target or Source Lists Using an Emitter | Home | 17.8. Where To Put Your Custom Builders and Tools