4.3.3 Builders

Rscons uses builder objects to produce target output files from source input files. A build target to be built using a builder is registered by calling a method on the Environment object that matches the builder's name. For example, a Program build target is registered by calling the env.Program method.

The general syntax for registering a build target using a builder is:

env.BuilderName(target, sources, vars = {})

The target parameter is the path to the output file or directory. The sources parameter is the path or paths to the input file(s) to be used by the builder. In the target and sources parameters, the user can explicitly refer to a path within the Environment's build root by beginning the path with "^/", or to a path within the Rscons top-level built directory by beginning with "^^/". The vars parameter is an optional Hash which can include construction variables to be used for this build target. Any construction variable values specified in this parameter will override those assigned to the Environment.

There are several default builders that are built-in to Rscons:

• Command, which executes a user-defined command to produce the target.
• Copy, which copies files or directories to a specified destination.
• Directory, which creates a directory.
• Disassemble, which disassembles an object file to a disassembly listing.
• Install, which installs files or directories to a specified destination.
• InstallDirectory, which creates a directory in an install destination.
• Lex, which builds a source file from a lex input file.
• Library, which collects object files into a static library archive file.
• Object, which compiles source files to produce an object file.
• Preprocess, which invokes the C/C++ preprocessor on a source file.
• Program, which links object files to produce an executable.
• SharedLibrary, which links object files to produce a dynamically loadable library.
• SharedObject, which compiles source files to produce an object file, in a way that is able to be used to create a shared library.
• Size, which runs the 'size' utility on an executable file.
• Yacc, which builds a source file from a yacc input file.