how to create a new variant in bjam

I've tried reading the documentation but it is rather impenetrable so I'm hoping someone may have a simple answer. I want to define a new 'variant', based on 'debug', which just adds some macro definitions to the compiler command line, eg "-DSOMEMACRO". I think I may be able to do this as a "sub-variant" of debug, or else just define a new variant copying 'debug', but I'm not even sure where to do this. It looks like feature.jam in $BOOST_BUILD_DIR/build may be the place. Perhaps what I really want is simply a new 'feature' but it's still not clear to me exactly what I need to do and where, and I don't know if a 'feature' allows me to direct the build products to a different directory to the 'debug' build.

Any suggestions will be appreciated. (In case you're wondering, I have to use bjam since it has been adopted as our corporate standard.)

Solution

I'm not quite sure what you want, but there's a number of possibilities.

A. You always want to compile with the SOMEMACRO macro defined. In which case, in the Jamfile for your project add

project
  : requirements # These are requirements for this project
      # If compiling debug, define SOMEMACRO
      <variant>debug:<define>SOMEMACRO
  : usage-requirements
      # These are requirements projects using this project must have
      <variant>debug:<define>SOMEMACRO
  ;

If you need SOMEMACRO always defined, you can remove the <variant>debug: condition. If you need to set other flags you can use <cflags>, <cxxflags>, and <linkflags> as appropriate.

B. You want a quick switch to turn on your flags/define, perhaps by default, perhaps not, and builds with it on are not compatible with builds with it off. In which case you want a feature.

import feature ;
feature.feature steves-feature : off on
  : composite propagated link-incompatible ;
feature.compose <steves-feature>on : <define>SOMEMACRO ;

The feature.feature rule defines a feature called <steves-feature> with two possible values and three properties. composite means it's a feature composed of other features (in this case <define>SOMEMACRO). propagated means that any targets that include a target with this feature set will also have this feature set. and link-incompatible means targets with <steves-feature>on can't be combined with targets with <steves-feature>off. (As a result, bjam will put the created files under a directory named steves-feature-on or steves-feature-off if this feature is set by any target.)

This feature can be used just like the <define> feature used in the project rule in the above section. (You can even add it to a default-build section of the project rule.)

Note that you can also set features from the command line: bjam steves-feature=on.

C. You want a full variant. I think the idea is if you have a few common build configurations with a bunch of different features that should be set together. Well, if you've already created the feature as above, this is now easy.

variant steves-debug : debug : <steves-feature>on ;

This variant will be the same as the debug variant but with the additional feature <steves-feature>on.

I've never used the variant rule, so it might need to be imported from somewhere. Also, you might be able to do

variant steves-debug : debug : <define>SOMEMACRO ;

but I don't know if bjam will create the directory structure or not. (It probably will.)