Guide to Build Variants

When are build variants useful?

Build variants help reduce the number of build targets and build types by lifting out repetitive build arguments that depend on some kind of option you want to change regularly.

Some example use cases:: Compiler or toolset; Target platform (win32 / win64); Full / incremental rebuild

Build variants also provide custom macros that are accessible across the IDE. These macros can be used to specify the executable path for build targets.

What are build variants?

Build variants are specific to this plugin. They play the same role as options in CMake but are applied to Jam.

Build variants provide a global state configuration of options that control arguments for the invocation of Jam.

The selected variant options can add new arguments to Jam's invocation. They also support macros to make them available in the rest of the IDE.

Screenshot showing the settings for a custom build variant

Preview

Every invocation of Jam will include either one of these command line arguments.

Screenshot of a custom build variant in action

Preview

Configure the build variants in the tool window displayed in the screenshot.

How to use build variants?

The Tool Window

Variants are managed in a tool window called Jam Variant Config.

This tool window automatically activates when the plugin is configured for the current project.

This tool window also provides a shortcut to the build variant settings.

Screenshot showing the Jam Variant Config tool window

Preview

The Jam Variant Config tool window appears on the left side of the IDE by default. It gives a shortcut to the build variant settings.

Configure the build variants

Open the settings in: Settings -> Build, Execution, Deployment -> Jam -> Build Variants.

Add new variants to the list and configure their options.

The names of both the variant parameter and the variant option are only used for display.

The build arguments and environmental variables are appended to whatever is already defined by the build target and build type.

Screenshot of the settings editor of build variants

Preview

The build variant settings can be found in Settings -> Build, Execution, Deployment -> Jam -> Build Variants.

Using Macros

Build variants can generate macros dynamically. These macros are available throughout the entire IDE.

Specify a value for the Macro name: option in the settings, and the plugin will automatically create a macro with that name.

If you provide a macro name: test_macro, you'll be able to use it later as $test_macro$ (for example, inside the executable path in the build target settings).

The macro will be substituted for the value specified in Macro value within the Build variants settings editor.

Screenshot showing the settings for custom macros

Preview

The build variants can generate custom macros. This example will create a macro named 'test_macro', which will expand to either 'value_1' or 'value_2'.

Screenshot showing the generated custom macro in the macro browser

Preview

The custom macros generated by the build variants are available in the macro browser of the IDE.