Variants

Overview
Disk Structure
Why Use Variants?
Platform As Variant

Overview

Packages in rez can contain different variants. Think of these as different flavors of the same package version. Each variant has one or more package dependencies that differ to the other variants in the same package.

Use of variants is best illustrated with an example. Consider a maya plugin, my_maya_plugin. Let us assume that there are two active versions of maya currently in use at your studio - 2016.sp2 and 2017. If your plugin is compiled, you may need to build it separately for each maya version, even though the source is no different.

You would use variants to create a version of your plugin that will work with both maya versions. Consider the following package definition for our plugin:

name = "my_maya_plugin"

version = "1.0.0"

requires = [
    "openexr-2.2"
]

variants = [
    ["maya-2016.sp2"],
    ["maya-2017]
]

When you build and install this package, two separate builds will occur - one using maya-2016.sp2, and the other maya-2017. When an environment is resolved that includes my_maya_plugin, the correct variant will be selected depending on the version of maya present. Only one variant of a package is ever used in a given configured environment.

Each variant entry is a list of dependencies, no different to the packages listed in the requires field. These dependencies are appended to the requires list for each variant. Thus the first variant requires openexr-2.2 and maya-2016.sp1, and the second variant requires openexr-2.2 and maya-2017.

Disk Structure

Package variants are stored within the package, under subdirectories that match the variant requirements. For example, continuing on with our my_maya_plugin package, the installation of that package would look like so:

/rez/packages/my_maya_plugin/1.0.0/maya-2016.sp2/<PAYLOAD>
                                  /maya-2017/<PAYLOAD>

The anatomy of a package with variants is illustrated in the following diagram:

The root of a package is the root directory of its current variant (the one the current environment is configured to use); the base if a package is the directory containing its variants. In a package that does not have variants, base and root are the same.

Why Use Variants?

Variants are a powerful mechanism in rez. They avoid the need to maintain separate branches of a package in order to support varying dependencies. You may have had problems in the past where a common library depends on, say, boost, and is used in various DCCs (maya, nuke etc), and depended on by many other packages in your pipeline. When a DCC moves to a new version of boost (or python, or OIIO, etc) you now have to branch this library, which potentially affects many other packages. The problem gets worse if you have multiple dependencies with varying versions. Variants solve that problem - you simply add another boost variant to your library, and other dependent packages are not affected. Rez will correctly select the package variant that does not conflict with the resolved environment.