Boost C++ Libraries

PrevUpHomeNext

Custom commands

When you use most of main target rules, Boost.Build automatically figures what commands to run and it what order. As soon as you want to use new file types, or support new tools, one approach is to extend Boost.Build to smoothly support them, as documented in Chapter 6, Extender Manual. However, if there's a single place where the new tool is used, it might be easier to just explicitly specify the commands to run.

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. Finaly, the generate rule allows you to describe transformation using Boost.Build's virtual targets. This is higher-level than file names that the make rule operates with, and allows you to create more than one target, or 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 file file.out from file file.in by running command in2out. Here's how you'd do this in Boost.Build:

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

If you run bjam 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. The, 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 and 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 in Boost.Build distribution illustrates how the generate rule can be used.


PrevUpHomeNext