Building with Platforms

Bazel has sophisticated support for modeling platforms and toolchains. Integrating this with real projects requires careful cooperation between code owners, rule maintainers, and core Bazel devs.

This page summarizes the purpose of platforms and shows how to build with them.

tl;dr: Bazel's platform and toolchain APIs are available but won't work everywhere until all language rules, select()s and other legacy references are updated. This work is ongoing. Eventually all builds will be platform-based. Read below to see where your builds fit.

For more formal documentation, see:

• Platforms
• Toolchains

Background

Platforms and toolchains were introduced to standardize how software projects target different machines and build with the right language tools.

This is a relatively recent addition to Bazel. It was inspired by the observation that language maintainers were already doing this in ad hoc, incompatible ways. For example, C++ rules use --cpu and --crosstool_top to set a build's target CPU and C++ toolchain. Neither of these correctly models a "platform". Historic attempts to do so caused awkward and inaccurate builds. These flags also don't control Java compilation, which evolved its own independent interface with --java_toolchain.

Bazel is intended for large, multi-language, multi-platform projects. This demands more principled support for these concepts, including clear APIs that encourage language and project interoperability. This is what these new APIs are for.

Migration

The platform and toolchain APIs only work when projects actually use them. This isn't trivial because a project's rule logic, toolchains, dependencies, and select()s have to support them. This requires a careful migration sequence to keep all projects and their dependencies working correctly.

For example, Bazel's C++ Rules support platforms. But the Apple Rules don't. Your C++ project may not care about Apple. But others may. So it's not yet safe to globally enable platforms for all C++ builds.

The remainder of this page describes this migration sequence and how and when your projects can fit in.

Goal

Bazel's platform migration is complete when all projects build with the form:

bazel build //:myproject --platforms=//:myplatform

This implies:

1. The rules your project uses can infer correct toolchains from //:myplatform.
2. The rules your project's dependencies use can infer correct toolchains from //:myplatform.
3. Either the projects depending on yours support //:myplatform or your project supports the legacy APIs (like --crosstool_top).
4. //:myplatform references [common declarations][Common Platform Declaration]{: .external} of CPU, OS, and other generic concepts that support automatic cross-project compatibility.
5. All relevant projects' select()s understand the machine properties implied by //:myplatform.
6. //:myplatform is defined in a clear, reusable place: in your project's repo if the platform is unique to your project, otherwise somewhere all projects that may use this platform can find.

The old APIs will be removed as soon as this goal is achieved. Then this will be the standard way projects select platforms and toolchains.

Should I use platforms?

If you just want to build or cross-compile a project, you should follow the project’s official documentation.

If you’re a project, language, or toolchain maintainer, you'll eventually want to support the new APIs. Whether you wait until the global migration is complete or opt in early depends on your specific value / cost needs:

Value

• You can select() or choose toolchains on the exact properties you care about instead of hard-coded flags like --cpu. For example, multiple CPUs can support the same instruction set.
• More correct builds. If you select() with --cpu in the above example, then add a new CPU that supports the same instruction set, the select() fails to recognize the new CPU. But a select() on platforms remains accurate.
• Simpler user experience. All projects understand: --platforms=//:myplatform. No need for multiple language-specific flags on the command line.
• Simpler language design. All languages share a common API for defining toolchains, using toolchains, and selecting the right toolchain for a platform.
• Targets can be skipped in the build and test phase if they are incompatible with the target platform.

Costs

• Dependent projects that don't yet support platforms might not automatically work with yours.
• Making them work may require additional temporary maintenance.
• Co-existence of new and legacy APIs requires more careful user guidance to avoid confusion.
• Canonical definitions for common properties like OS and CPU are still evolving and may require extra initial contributions.
• Canonical definitions for language-specific toolchains are still evolving and may require extra initial contributions.

API review

A platform is a collection of constraint_value targets:

platform(
    name = "myplatform",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

A constraint_value is a machine property. Values of the same "kind" are grouped under a common constraint_setting:

constraint_setting(name = "os")
constraint_value(
    name = "linux",
    constraint_setting = ":os",
)
constraint_value(
    name = "mac",
    constraint_setting = ":os",
)

A toolchain is a Starlark rule. Its attributes declare a language's tools (like compiler = "//mytoolchain:custom_gcc"). Its providers pass this information to rules that need to build with these tools.

Toolchains declare the constraint_values of machines they can target (target_compatible_with = ["@platforms//os:linux"]) and machines their tools can run on (exec_compatible_with = ["@platforms//os:mac"]).

When building $ bazel build //:myproject --platforms=//:myplatform, Bazel automatically selects a toolchain that can run on the build machine and build binaries for //:myplatform. This is known as toolchain resolution.

The set of available toolchains can be registered in the WORKSPACE with register_toolchains or at the command line with --extra_toolchains.

See here for a deeper dive.

Status

Current platform support varies among languages. All of Bazel's major rules are moving to platforms. But this process will take time. This is for three main reasons:

1. Rule logic must be updated to get tool info from the new toolchain API (ctx.toolchains) and stop reading legacy settings like --cpu and --crosstool_top. This is relatively straightforward.

2. Toolchain maintainers must define toolchains and make them accessible to users (in GitHub repositories and WORKSPACE entries). This is technically straightforward but must be intelligently organized to maintain an easy user experience.

   Platform definitions are also necessary (unless you build for the same machine Bazel runs on). Generally, projects should define their own platforms.

3. Existing projects must be migrated. select()s and transitions also have to be migrated. This is the biggest challenge. It's particularly challenging for multi-language projects (which may fail if all languages can't read --platforms).

If you're designing a new rule set, you must support platforms from the beginning. This automatically makes your rules compatible with other rules and projects, with increasing value as the platform API becomes more ubiquitous.

Common platform properties

Platform properties like OS and CPU that are common across projects should be declared in a standard, centralized place. This encourages cross-project and cross-language compatibility.

For example, if MyApp has a select() on constraint_value @myapp//cpus:arm and SomeCommonLib has a select() on @commonlib//constraints:arm, these trigger their "arm" modes with incompatible criteria.

Globally common properties are declared in the @platforms repo (so the canonical label for the above example is @platforms//cpu:arm). Language-common properties should be declared in the repos of their respective languages.

Default platforms

Generally, project owners should define explicit platforms to describe the kinds of machines they want to build for. These are then triggered with --platforms.

When --platforms isn't set, Bazel defaults to a platform representing the local build machine. This is auto-generated at @local_config_platform//:host so there's no need to explicitly define it. It maps the local machine's OS and CPU with constraint_values declared in @platforms.

C++

Bazel's C++ rules use platforms to select toolchains when you set --incompatible_enable_cc_toolchain_resolution (#7260).

This means you can configure a C++ project with:

bazel build //:my_cpp_project --platforms=//:myplatform

instead of the legacy:

bazel build //:my_cpp_project` --cpu=... --crosstool_top=...  --compiler=...

If your project is pure C++ and not depended on by non-C++ projects, you can use platforms safely as long as your selects and transitions are compatible. See #7260 and Configuring C++ toolchains for more guidance.

This mode is not enabled by default. This is because Apple projects still configure C++ dependencies with --cpu and --crosstool_top (example). So this depends on the Apple rules migrating to platforms.

Java

Bazel's Java rules use platforms.

This replaces legacy flags --java_toolchain, --host_java_toolchain, --javabase, and --host_javabase.

To learn how to use the configuration flags, see the Bazel and Java manual. For additional information, see the Design document.

If you are still using legacy flags, follow the migration process in Issue #7849.

Android

Bazel's Android rules use platforms to select toolchains when you set --incompatible_enable_android_toolchain_resolution.

This is not enabled by default. But migration is well on its way.

Apple

Bazel's Apple rules do not yet support platforms to select Apple toolchains.

They also don't support platform-enabled C++ dependencies because they use the legacy --crosstool_top to set the C++ toolchain. Until this is migrated, you can mix Apple projects with platorm-enabled C++ with platform mappings (example).

Other languages

• Bazel's Rust rules fully support platforms.
• Bazel's Go rules fully support platforms (details).

If you're designing rules for a new language, use platforms to select your language's toolchains. See the toolchains documentation for a good walkthrough.

select()

Projects can select() on constraint_value targets but not complete platforms. This is intentional so that select()s supports as wide a variety of machines as possible. A library with ARM-specific sources should support all ARM-powered machines unless there's reason to be more specific.

To select on one or more constraint_values, use:

config_setting(
    name = "is_arm",
    constraint_values = [
        "@platforms//cpu:arm",
    ],
)

This is equivalent to traditionally selecting on --cpu:

config_setting(
    name = "is_arm",
    values = {
        "cpu": "arm",
    },
)

More details here.

selects on --cpu, --crosstool_top, etc. don't understand --platforms. When migrating your project to platforms, you must either convert them to constraint_values or use platform mappings to support both styles through the migration window.

Transitions

Starlark transitions change flags down parts of your build graph. If your project uses a transition that sets --cpu, --crossstool_top, or other legacy flags, rules that read --platforms won't see these changes.

When migrating your project to platforms, you must either convert changes like return { "//command_line_option:cpu": "arm" } to return { "//command_line_option:platforms": "//:my_arm_platform" } or use platform mappings to support both styles through the migration window.

How to use platforms today

If you just want to build or cross-compile a project, you should follow the project's official documentation. It's up to language and project maintainers to determine how and when to integrate with platforms, and what value that offers.

If you're a project, language, or toolchain maintainer and your build doesn't use platforms by default, you have three options (besides waiting for the global migration):

1. Flip on the "use platforms" flag for your project's languages (if they have one) and do whatever testing you need to see if the projects you care about work.

2. If the projects you care about still depend on legacy flags like --cpu and --crosstool_top, use these together with --platforms:

   bazel build //:my_mixed_project --platforms==//:myplatform --cpu=... --crosstool_top=...

   This has some maintenance cost (you have to manually make sure the settings match). But this should work in the absence of renegade transitions.

3. Write platform mappings to support both styles by mapping --cpu-style settings to corresponding platforms and vice versa.

Platform mappings

Platform mappings is a temporary API that lets platform-powered and legacy-powered logic co-exist in the same build through the latter's deprecation window.

A platform mapping is a map of either a platform() to a corresponding set of legacy flags or the reverse. For example:

platforms:
  # Maps "--platforms=//platforms:ios" to "--cpu=ios_x86_64 --apple_platform_type=ios".
  //platforms:ios
    --cpu=ios_x86_64
    --apple_platform_type=ios

flags:
  # Maps "--cpu=ios_x86_64 --apple_platform_type=ios" to "--platforms=//platforms:ios".
  --cpu=ios_x86_64
  --apple_platform_type=ios
    //platforms:ios

  # Maps "--cpu=darwin --apple_platform_type=macos" to "//platform:macos".
  --cpu=darwin
  --apple_platform_type=macos
    //platforms:macos

Bazel uses this to guarantee all settings, both platform-based and legacy, are consistently applied throughout the build, including through transitions.

By default Bazel reads mappings from the platform_mappings file in your workspace root. You can also set --platform_mappings=//:my_custom_mapping.

See here for complete details.

Questions

For general support and questions about the migration timeline, contact bazel-discuss@googlegroups.com or the owners of the appropriate rules.

For discussions on the design and evolution of the platform/toolchain APIs, contact bazel-dev@googlegroups.com.

See also

• Configurable Builds - Part 1
• Platforms
• Toolchains
• Bazel Platforms Cookbook
• hlopko/bazel_platforms_examples
• Example C++ custom toolchain