4.6.6 Custom Constraints & Custom Platforms

Most builds never need custom constraints. The @platforms repository already ships standard constraint_settings for OS and CPU, plus @platforms//host to auto-detect the local machine.¹ Reach for custom constraints only when those standard dimensions cannot describe a real distinction your build matrix has to make: a GPU capability the toolchain depends on, a libc variant that leaks into binaries, a staging-versus-production hardware generation, or anything else that meaningfully changes which toolchain or sources Bazel should select.

A constraint is a distinguishing property of a build or production machine. CPU architecture, presence or absence of a GPU, or the version of a locally installed compiler are common examples, but a constraint can be anything that meaningfully distinguishes machines when orchestrating build work.² The vocabulary already exists from 3.3.3 Constraint Values. What changes at this level is that you decide when to add to it.

When @platforms Already Covers You

Before defining anything new, check whether the dimension you care about is already a constraint in @platforms. The Bazel team maintains github.com/bazelbuild/platforms precisely so OS and CPU vocabulary stays consistent across the ecosystem.³ If your build only needs to distinguish "Linux x86_64 vs macOS arm64," everything you need is already available — @platforms//os:linux, @platforms//cpu:x86_64, and so on. A custom constraint_setting for cpu would duplicate that vocabulary and break interoperability with other rule sets that read @platforms//cpu.

The same logic applies to extending an existing setting with a new value. Custom-purpose OSes or CPUs should be declared in your rule's repo rather than in @platforms, because rule-specific extensions belong to the owner of the rule, not to the shared ecosystem.⁴ You can do this directly: if visibility allows, you may add a new constraint_value for an existing constraint_setting such as @platforms//cpu.⁵

In short, default to @platforms. Add custom dimensions only when the distinction is real, your toolchain or sources need to branch on it, and no @platforms vocabulary covers it.

Defining a Custom Constraint

A constraint_setting declares a dimension. A constraint_value is a named value within that dimension. Both are plain BUILD-level targets.⁶

package(default_visibility = ["//visibility:public"])

constraint_setting(name = "gpu")

constraint_value(
    name = "cuda",
    constraint_setting = ":gpu",
)

constraint_value(
    name = "rocm",
    constraint_setting = ":gpu",
)

constraint_value(
    name = "no_gpu",
    constraint_setting = ":gpu",
)

If these live in //constraints/BUILD.bazel, downstream BUILD files refer to them as //constraints:cuda, //constraints:no_gpu, and so on — ordinary labels. They participate in everything that already accepts a constraint_value: platform(), config_setting, target_compatible_with, and toolchain target_compatible_with / exec_compatible_with clauses.⁶

A constraint_setting may also nominate one of its constraint_values as the setting's default. A target_compatible_with or exec_compatible_with clause matches a platform when, for each constraint_value in its list, the platform also has that constraint_value — either explicitly or as a default.⁷ In practice this means a "neutral" value can stand in for platforms that don't say anything about that setting — for example, marking :no_gpu as the default for the :gpu setting so platforms that omit a GPU value still match toolchains that require :no_gpu.

Refining an Existing Constraint Value

Some custom dimensions only make sense underneath a broader constraint. A glibc_version setting, for example, is not an arbitrary machine property in the same way OS or CPU is. It is a Linux-specific refinement. The Build Encyclopedia now exposes that relationship directly with constraint_setting(refines_constraint_value = ...).⁸

constraint_setting(
    name = "glibc_version",
    default_constraint_value = ":glibc_unspecified",
    refines_constraint_value = "@platforms//os:linux",
)

constraint_value(
    name = "glibc_unspecified",
    constraint_setting = ":glibc_version",
)

constraint_value(
    name = "glibc_2_31",
    constraint_setting = ":glibc_version",
)

platform(
    name = "linux_glibc_2_31",
    constraint_values = [
        "@platforms//os:linux",
        ":glibc_2_31",
    ],
)

The refinement is a validity rule, not inheritance. If a platform lists a non-default value from the refining setting, it must also list the refined value — :glibc_2_31 requires @platforms//os:linux in the example above. Platforms that get the default value, either implicitly by omitting the setting or explicitly by listing it, are exempt.⁸

Refinement also helps select() specificity. If one branch matches the broad value (@platforms//os:linux) and another matches the refining value (:glibc_2_31), Bazel treats the refining condition as more specific when both match, instead of reporting an ambiguous match.⁸ That is useful for nested vocabularies: choose a broad Linux default, then override only for particular libc versions, SDK families, or hardware generations that refine an existing platform value.

Practical guidance on picking custom constraints:

• One setting per orthogonal dimension. GPU vendor, libc variant, and hardware generation are independent and belong to separate constraint_settings. A platform may only carry one constraint_value per setting, so you cannot encode multiple values of the same kind on a single platform.⁹
• PascalCase or lowercase names tied to vocabulary, not products. Prefer gpu over nvidia_a100_or_amd_mi300, since the value, not the setting, names the concrete option.
• Public visibility for cross-package consumption. In a constraints-only package, use package(default_visibility = ["//visibility:public"]). Otherwise set visibility = ["//visibility:public"] on each exported constraint_setting / constraint_value.

Composing a Custom Platform

A platform() target is a named set of constraint_values.¹⁰ To define a platform that uses both standard @platforms constraints and your custom ones, list them together:

platform(
    name = "linux_arm64_cuda",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm64",
        "//constraints:cuda",
    ],
)

This is the shape that puts custom constraints to use: standard OS and CPU vocabulary for portability and interop with toolchains that already read @platforms, plus your project-specific dimension for the distinction @platforms cannot express. The platform() rule does not require a special syntax for "custom" values — every entry in constraint_values is a label to a constraint_value target, whatever repository it lives in.

A platform may only carry one constraint_value per constraint_setting. So a platform cannot describe a machine with "two CPUs" without a second constraint_setting modeling the second slot.⁹ In practice this means custom constraints should describe orthogonal capabilities, not alternative values of the same capability.

You can see this end-to-end in the target-compatibility snippet: a custom demo_os constraint setting with demo_linux and demo_macos values, two platform() targets composed from them, and filegroups using target_compatible_with to demonstrate the wildcard-skip behavior introduced in 3.3.4 Target Compatibility.

Where Custom Constraints Show Up

Once defined, a custom constraint is a normal constraint_value label. Every place that already accepts @platforms//cpu:arm64 accepts //constraints:cuda:

• select() keys. A config_setting with constraint_values = ["//constraints:cuda"] matches platforms that include the :cuda value, just like the is_arm example in the migration guide does for @platforms//cpu:arm.¹¹
• target_compatible_with on targets and toolchains. A target restricted to ["//constraints:cuda"] will be silently skipped under bazel build //... when the target platform does not include :cuda, following the rules from 3.3.4 Target Compatibility.
• Toolchain resolution. When you write a toolchain() target as in 4.6.2 Defining, Registering & Accessing Toolchains, its target_compatible_with and exec_compatible_with clauses can list custom constraints. The resolution algorithm from 4.6.3 Toolchain Resolution treats them like any other constraint_value: each clause must be satisfied by the candidate platform.⁷

The mental model is symmetric. Define a constraint once. Consume it in any of the existing platform APIs without adding new machinery. That is what makes custom constraints a localized extension rather than a parallel system.

Common Pitfalls

• Modelling the wrong axis. If two values are alternatives within a single dimension — like "CUDA" and "no GPU" — they should be constraint_values of the same constraint_setting, not separate settings. If they are independent capabilities — like "has GPU" and "uses glibc 2.31" — they need separate settings.⁹
• Putting common vocabulary in your repo. OS and CPU constraints belong in @platforms so multiple rule sets read the same labels. Putting os:linux in your project's own constraint package fragments the ecosystem and breaks interop with rule sets that already consume @platforms//os:linux.⁴
• Forgetting visibility. Constraint targets are referenced from BUILD files all over the workspace. If a downstream package cannot see your constraint_value, every platform() and target_compatible_with that references it fails to load.
• Treating platforms as arbitrary sets. A platform() is a constraint vector with at most one value per setting. Custom constraints widen the vector. They do not let you encode multiple values of the same dimension on one platform.⁹
• Forgetting the refined parent. refines_constraint_value does not add the parent value automatically. A platform that lists a non-default refining value must also list the value it refines. Use defaults for the neutral or "unspecified" case.⁸