From f64d48acd6fbb0729bd6f213e5bd6f993f085c02 Mon Sep 17 00:00:00 2001 From: Tobias Hunger Date: Mon, 6 Jul 2026 13:39:27 +0000 Subject: [PATCH] docs: document the build variants pixi sets automatically Pixi fills in some build variants for you rather than requiring them in [workspace.build-variants]: target_platform, and c_stdlib/c_stdlib_version derived from the target platform's system requirements when building against conda-forge. Only the compiler defaults were documented before. Add a "Variants Pixi Sets for You" section to the build variants tutorial covering the derivation, its conda-forge gating, the bare-subdir defaults, and the Windows/musl/CUDA limitations, and cross-reference it from the manifest reference. --- docs/build/variants.md | 26 ++++++++++++++++++++++++++ docs/reference/pixi_manifest.md | 10 ++++++---- 2 files changed, 32 insertions(+), 4 deletions(-) diff --git a/docs/build/variants.md b/docs/build/variants.md index cce56afac9..b82fc80830 100644 --- a/docs/build/variants.md +++ b/docs/build/variants.md @@ -90,6 +90,32 @@ python_rich 0.1.0 pyhbf21a9e_0 conda python_rich ``` +## Variants Pixi Sets for You + +Not every variant has to be spelled out in `[workspace.build-variants]`. +When you build a package, Pixi fills in a few variants automatically based on the platform you build for and its [system requirements](../workspace/system_requirements.md). +An explicit `[workspace.build-variants]` entry always wins over a value Pixi derives, so you can override any of these by hand. + +### `target_platform` + +Every build is tagged with the platform it is built for, so a build made for `linux-64` and one made for `osx-arm64` stay distinct. +You never set this yourself; it comes from the platform being built. + +### `c_stdlib` and `c_stdlib_version` + +Build backends pin the minimum OS/libc target through the recipe's `stdlib("c")` function, which resolves against the `c_stdlib` and `c_stdlib_version` variants. +Rather than making you repeat this in `[workspace.build-variants]`, Pixi derives the pair from the target platform's system requirements (recorded as the `__osx` and `__glibc` virtual packages): + +| Subdir | Virtual package | `c_stdlib` | `c_stdlib_version` | +|-----------|-----------------|----------------------------|------------------------| +| `osx-*` | `__osx` | `macosx_deployment_target` | the `__osx` version | +| `linux-*` | `__glibc` | `sysroot` | the `__glibc` version | + +Platforms declared as a bare subdir string carry Pixi's portable defaults (`__glibc = "2.28"`, `__osx = "13.0"`), so the derivation works even when you don't declare system requirements explicitly. + +The providers `macosx_deployment_target` and `sysroot` are conda-forge packages, so this derivation only applies when one of your channels is conda-forge. +It is skipped on Windows (which has no meaningful stdlib version), and musl (`__musl`) and CUDA (`__cuda`) are not derived yet. + ## Conclusion In this tutorial, we showed how to use variants to build multiple versions of a single package. diff --git a/docs/reference/pixi_manifest.md b/docs/reference/pixi_manifest.md index aa8352ba5e..4541510aee 100644 --- a/docs/reference/pixi_manifest.md +++ b/docs/reference/pixi_manifest.md @@ -218,7 +218,7 @@ internal = false ``` Mapping files are JSON objects with `conda_name: pypi_package_name` entries. -The value can also be a list of PyPI names — the conda package then satisfies all of them and one PURL is emitted per name — or `null` to mark a package as not available on PyPI. +The value can also be a list of PyPI names (the conda package then satisfies all of them and one PURL is emitted per name), or `null` to mark a package as not available on PyPI. This is the same format that parselmouth publishes under [`files/v0//compressed_mapping.json`](https://github.com/prefix-dev/parselmouth/tree/main/files/v0), so those files can be used directly (use the raw file URL). ```json title="local/robostack_mapping.json" @@ -450,6 +450,8 @@ When build variants are specified, Pixi will: 3. **Resolve dependencies**: Ensure each variant resolves with compatible dependency versions 4. **Generate unique build strings**: Each variant gets a unique build identifier in the package name +On top of the variants you declare, Pixi fills in some automatically: `target_platform`, and (for conda-forge builds) `c_stdlib`/`c_stdlib_version` derived from the platform's [system requirements](../workspace/system_requirements.md). An explicit entry here always overrides a derived value. See [Variants Pixi Sets for You](../build/variants.md#variants-pixi-sets-for-you). + #### Platform-Specific Variants Build variants can also be specified per-platform: @@ -489,7 +491,7 @@ For detailed examples and tutorials, see the [build variants documentation](../b Use `build-variants-files` to reference external variant definitions from YAML files. Paths are resolved relative to the workspace root and processed in the listed -order—entries from earlier files take precedence over values loaded from later ones. +order: entries from earlier files take precedence over values loaded from later ones. ```toml [workspace] @@ -508,9 +510,9 @@ Otherwise, it will use `rattler-build`'s syntax as outlined in the [rattler-buil !!! warning "Preview Feature" `[workspace.dependencies]` requires the `pixi-build` preview feature to be - enabled and only applies to **package** dependencies — see + enabled and only applies to **package** dependencies (see [Workspace Dependencies](../build/workspace_dependencies.md) for the - semantics, override rules and error cases. + semantics, override rules and error cases). A pool of conda dependency specs that members of the workspace can inherit per entry by writing `{ workspace = true }` in any of their