Boost C++ Libraries


Custom commands

For most main target rules, Boost.Build automatically figures out the commands to run. When you want to use new file types or support new tools, one approach is to extend Boost.Build to support them smoothly, as documented in Chapter 6, Extender Manual. However, if the new tool is only used in a single place, it might be easier just to specify the commands to run explicitly.

Three main target rules can be used for that. The make rule allows you to construct a single file from any number of source file, by running a command you specify. The notfile rule allows you to run an arbitrary command, without creating any files. And finaly, the generate rule allows you to describe a transformation using Boost.Build's virtual targets. This is higher-level than the file names that the make rule operates with and allows you to create more than one target, create differently named targets depending on properties or use more than one tool.

The make rule is used when you want to create one file from a number of sources using some specific command. The notfile is used to unconditionally run a command.

Suppose you want to create the file file.out from the file by running the command in2out. Here is how you would do this in Boost.Build:

make file.out : : @in2out ;
actions in2out
    in2out $(<) $(>)

If you run b2 and file.out does not exist, Boost.Build will run the in2out command to create that file. For more details on specifying actions, see the section called “Boost.Jam Language”.

It could be that you just want to run some command unconditionally, and that command does not create any specific files. For that you can use the notfile rule. For example:

notfile echo_something : @echo ;
actions echo
    echo "something"

The only difference from the make rule is that the name of the target is not considered a name of a file, so Boost.Build will unconditionally run the action.

The generate rule is used when you want to express transformations using Boost.Build's virtual targets, as opposed to just filenames. The generate rule has the standard main target rule signature, but you are required to specify the generating-rule property. The value of the property should be in the form @rule-name, the named rule should have the following signature:

rule generating-rule ( project name : property-set : sources * )

and will be called with an instance of the project-target class, the name of the main target, an instance of the property-set class containing build properties, and the list of instances of the virtual-target class corresponding to sources. The rule must return a list of virtual-target instances. The interface of the virtual-target class can be learned by looking at the build/virtual-target.jam file. The generate example contained in the Boost.Build distribution illustrates how the generate rule can be used.