Building wheel variants¶
Added in version 1.0.
Warning
This is an early preview of PEP 817 wheel variant support. The interface may
change, and it must be opted into with experimental = true.
Scikit-build-core can attach variant metadata to a wheel, producing a
variant-labeled filename (the label becomes the final field of the wheel name)
and a variant.json file inside *.dist-info. This lets you ship several
wheels for the same version that differ by hardware or library features (CPU
ABI, CUDA version, BLAS implementation, etc.).
Declaring providers¶
Every namespace you provide must have a provider declared in the [variant]
table of pyproject.toml, and must be listed in default-priorities. The table
is required for the null variant too, since PEP 825 requires at least one
namespace in every variant wheel:
[variant]
"$schema" = "https://variants-schema.wheelnext.dev/v0.2.0.json"
[variant.default-priorities]
namespace = ["x86_64"]
[variant.providers.x86_64]
requires = ["x86-64-variant-provider>=0.2.3"]
plugin-api = "x86_64_variant_provider"
Selecting a variant¶
Declare each variant you can build in [variant.variants], keyed by its label:
[variant.variants.x86_64_v3]
x86_64.level = ["v3"]
Then select one with the variant-label setting, as PEP 817 describes. It
is only allowed in config-settings or [[tool.scikit-build.overrides]]; it
cannot be set at the top level of [tool.scikit-build]. When it is set,
variantlib is added as a build requirement, and the experimental flag must
be enabled. For example, with pip:
pip wheel . -Cexperimental=true -Cvariant-label=x86_64_v3
This produces a wheel ending in -x86_64_v3.whl. Labels may only contain
lowercase letters, digits, _, and .. The label null is reserved by PEP
825 for the null variant, which has no properties; build it with
-Cvariant-label=null. It does not need a [variant.variants] entry.
The provider plugins for the namespaces you select are added to the build
requirements, and the properties are checked against them before the wheel is
written. A property the plugin does not list is an error. Providers declared
with build-requires are ahead-of-time plugins; their supported values are also
embedded into variant.json as static-properties, so installers do not need
the plugin. Providers declared with requires are queried again at install
time.
You can also set experimental = true under [tool.scikit-build] instead of
passing it every time.
For more information you can see the available PEPs: