Although &SCons; provides many useful methods for building common software products: programs, libraries, documents. you frequently want to be able to build some other type of file not supported directly by &SCons; Fortunately, &SCons; makes it very easy to define your own &Builder; objects for any custom file types you want to build. (In fact, the &SCons; interfaces for creating &Builder; objects are flexible enough and easy enough to use that all of the the &SCons; built-in &Builder; objects are created the mechanisms described in this section.)

The simplest &Builder; to create is one that executes an external command. For example, if we want to build an output file by running the contents of the input file through a command named foobuild, creating that &Builder; might look like: bld = Builder(action = 'foobuild < $SOURCE > $TARGET') All the above line does is create a free-standing &Builder; object. The next section will show us how to actually use it.

A &Builder; object isn't useful until it's attached to a &consenv; so that we can call it to arrange for files to be built. This is done through the &cv-link-BUILDERS; &consvar; in an environment. The &cv-BUILDERS; variable is a Python dictionary that maps the names by which you want to call various &Builder; objects to the objects themselves. For example, if we want to call the &Builder; we just defined by the name Foo, our &SConstruct; file might look like: bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) import os env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() env.Foo('file.foo', 'file.input') file.input cat bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) With the &Builder; so attached to our &consenv; we can now actually call it like so: env.Foo('file.foo', 'file.input') Then when we run &SCons; it looks like: scons -Q Note, however, that the default &cv-BUILDERS; variable in a &consenv; comes with a default set of &Builder; objects already defined: &b-link-Program;, &b-link-Library;, etc. And when we explicitly set the &cv-BUILDERS; variable when we create the &consenv;, the default &Builder;s are no longer part of the environment: import SCons.Defaults; SCons.Defaults.ConstructionEnvironment['TOOLS'] = {}; bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') env.Program('hello.c') bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') env.Program('hello.c') file.input hello.c scons -Q To be able to use both our own defined &Builder; objects and the default &Builder; objects in the same &consenv;, you can either add to the &cv-BUILDERS; variable using the &Append; function: env = Environment() import os env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env.Append(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') env.Program('hello.c') file.input hello.c cat env = Environment() bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env.Append(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') env.Program('hello.c') Or you can explicitly set the appropriately-named key in the &cv-BUILDERS; dictionary: env = Environment() bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env['BUILDERS']['Foo'] = bld env.Foo('file.foo', 'file.input') env.Program('hello.c') Either way, the same &consenv; can then use both the newly-defined Foo &Builder; and the default &b-link-Program; &Builder;: scons -Q

By supplying additional information when you create a &Builder;, you can let &SCons; add appropriate file suffixes to the target and/or the source file. For example, rather than having to specify explicitly that you want the Foo &Builder; to build the file.foo target file from the file.input source file, you can give the .foo and .input suffixes to the &Builder;, making for more compact and readable calls to the Foo &Builder;: bld = Builder(action = 'foobuild < $SOURCE > $TARGET', suffix = '.foo', src_suffix = '.input') env = Environment(BUILDERS = {'Foo' : bld}) import os env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() env.Foo('file1') env.Foo('file2') file1.input file2.input cat bld = Builder(action = 'foobuild < $SOURCE > $TARGET', suffix = '.foo', src_suffix = '.input') env = Environment(BUILDERS = {'Foo' : bld}) env.Foo('file1') env.Foo('file2') scons -Q You can also supply a prefix keyword argument if it's appropriate to have &SCons; append a prefix to the beginning of target file names.

In &SCons;, you don't have to call an external command to build a file. You can, instead, define a Python function that a &Builder; object can invoke to build your target file (or files). Such a &buildfunc; definition looks like: def build_function(target, source, env): # Code to build "target" from "source" return None The arguments of a &buildfunc; are: target A list of Node objects representing the target or targets to be built by this builder function. The file names of these target(s) may be extracted using the Python &str; function. source A list of Node objects representing the sources to be used by this builder function to build the targets. The file names of these source(s) may be extracted using the Python &str; function. env The &consenv; used for building the target(s). The builder function may use any of the environment's construction variables in any way to affect how it builds the targets. The builder function must return a 0 or None value if the target(s) are built successfully. The builder function may raise an exception or return any non-zero value to indicate that the build is unsuccessful, Once you've defined the Python function that will build your target file, defining a &Builder; object for it is as simple as specifying the name of the function, instead of an external command, as the &Builder;'s action argument: def build_function(target, source, env): # Code to build "target" from "source" return None bld = Builder(action = build_function, suffix = '.foo', src_suffix = '.input') env = Environment(BUILDERS = {'Foo' : bld}) env.Foo('file') file.input And notice that the output changes slightly, reflecting the fact that a Python function, not an external command, is now called to build the target file: scons -Q

&SCons; Builder objects can create an action "on the fly" by using a function called a &generator;. 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 &consenv; 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}) import os env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() env.Foo('file') file.input cat 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 Note that it's illegal to specify both an action and a generator for a &Builder;.

&SCons; supports the ability for a Builder to modify the lists of target(s) from the specified source(s). def modify_targets(target, source, env): target.append('new_target') source.append('new_source') return target, source bld = Builder(action = 'foobuild $TARGETS - $SOURCES', suffix = '.foo', src_suffix = '.input', emitter = modify_targets) env = Environment(BUILDERS = {'Foo' : bld}) import os env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() env.Foo('file') file.input new_source cat def modify_targets(target, source, env): target.append('new_target') source.append('new_source') return target, source bld = Builder(action = 'foobuild $TARGETS - $SOURCES', suffix = '.foo', src_suffix = '.input', emitter = modify_targets) env = Environment(BUILDERS = {'Foo' : bld}) env.Foo('file') scons -Q bld = Builder(action = 'my_command', suffix = '.foo', src_suffix = '.input', emitter = 'MY_EMITTER') def modify1(target, source, env): return target, source def modify2(target, source, env): return target, source env1 = Environment(BUILDERS = {'Foo' : bld}, MY_EMITTER = modify1) env2 = Environment(BUILDERS = {'Foo' : bld}, MY_EMITTER = modify2) env1.Foo('file1') env2.Foo('file2')