4.4 Variants

Rscons supports build variants. Variants can be used to built multiple variations of the same item with a specific change. For example, a desktop application with the same sources could be built to target KDE or GNOME using build variants. It is up to the build script author to define the variants and what effect they have on the build.

This build script defines "kde" and "gnome" variants:

variant "kde"
variant "gnome"

with_variants do
  env "prog" do |env|
    if variant "kde"
      env["CPPDEFINES"] << "KDE"
    end
    if variant "gnome"
      env["CPPDEFINES"] << "GNOME"
    end
    env.Program("^/prog.exe", "src/**/*.cpp")
  end
end

The variant build script method has two uses:

• At the top of the build script, it defines a variant.
• Within a with_variants block, it queries for whether the given variant is active.

The with_variants build script method allows the power of variants to be harnessed. It iterates through each enabled variant and calls the given block. In this example, the block would be called twice, once with the "kde" variant active, and the second time with the "gnome" variant active.

Each env method call creates an Environment, so two environments are created. When an Environment is created within a with_variants block, the Environment's build directory name has the active variant(s) keys appended to the given Environment name, and separated by a "-".

In this example, a "prog-kde" Environment would be created with build root build/prog-kde and -DKDE would be passed to the compiler when compiling each source. Next a "prog-gnome" Environment would be created with build root build/prog-gnome and -DGNOME would be passed to the compiler when compiling the sources.

The key for a variant is the variant's name by default but can be overridden by passing a :key value to the variant method. A nil value for the :key parameter will omit that variant from appearing in the environment's build directory name. For example:

variant "debug"
variant "release", key: nil

with_variants do
  env "prog" do |env|
  end
end

In this example, one "prog" environment will be created for the "debug" variant with the build directory "prog-debug", and another "prog" environment will be created for the "release" variant with the build directory "prog". The build directory for the release variant of the "prog" environment is just "prog" instead of "prog-release" because the key for the "release" variant is set to nil.

Variants are enabled by default, but can be disabled by passing a false value to the :default option of the variant method. For example:

variant "debug", default: false
variant "release"

with_variants do
  env "prog" do |env|
    env.Program("^/prog.exe", "prog.c")
  end
end

The rscons command line interface provides a -e/--variants argument which allows the user to enable a different set of variants from those enabled by default according to the build script author. This argument accepts a comma-separated list of variants to enable. Each entry in the list can begin with "-" to disable the variant instead of enable it. If the list begins with "+" or "-", then the entire given list modifies the defaults given in the build script. Otherwise, it exactly specifies which variants should be enabled, and any variant not listed is disabled.

When the project is configured, the set of enabled variants is recorded and remembered for later Rscons invocations. This way, a user working on a single variant of a project does not need to specify the -e/--variants option on each build operation.

The variant_enabled? build script method can be called to query whether the given variant is enabled.