how to create a new variant in bjam

bjam, boost-build

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.)

Problem

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.)

Original source