The State of Path Mapping

[fmeum]

What is path mapping?

With path mapping enabled, Bazel automatically rewrites paths in action command lines with the aim of making them more likely to be disk or remote cache hits.
Specifically, configuration prefixes such as bazel-out/darwin-amd64-fastbuild/bin are replaced with a fixed string such as bazel-out/cfg/bin, so that the result of an action that doesn't depend on all aspects of the configuration encoded in the path (e.g. the OS, architecture and build mode) can be shared between different target platforms and configurations.

Path mapping by itself won't result in cache hits between different execution platforms because toolchains typically differ between platforms (in content, not just paths). One way to address this is to bundle toolchains for multiple execution platforms, see "Universal toolchains". Another is to use cache key scrubbing.

For more information on path mapping, watch the "Towards faster cross-platform builds" talk.

Using path mapping

Bazel has experimental support for path mapping for both native and Starlark rules as detailed below.

General requirements

• At least Bazel 7.2.0rc3 or 8.0.0-pre.20240523.3 are recommended.
• Set --experimental_output_paths=strip.
• Use a disk or remote cache (or remote execution).
• Actions must use a compatible strategy:
  • remote
  • dynamic
  • sandboxed
  • multiplex-worker with --experimental_worker_multiplex_sandbox
  • worker with --worker_sandboxing

Java

Java compilation actions as well as header compilation actions support path mapping.

Requirements

Since the default Java toolchain doesn't enable support for multiplex sandboxing yet, non-remote execution with path mapping requires using a custom Java toolchain:

load("@bazel_tools//tools/jdk:default_java_toolchain.bzl", "default_java_toolchain")
default_java_toolchain(
    name = "java_toolchain",
    source_version = "17",
    target_version = "17",
    javac_supports_worker_multiplex_sandboxing = True,
)

rules_java 7.5.0 and higher have support for multiplex sandboxing.

Go

rules_go optionally uses path mapping for its non-cgo compilation actions, including the stdlib.

Requirements

rules_go from HEAD including this commit.

Custom Starlark rules

Custom Starlark rules can opt into path mapping by adding an entry with the key supports-path-mapping to the execution_requirements dict passed to ctx.actions.run or ctx.actions.run_shell.
They can also be opted in from the command line via --modify_execution_info.

Additionally, command lines need to be constructed using ctx.actions.args and avoiding any of the methods on File that return a path string. Assuming that src is a File representing a file and dir is a File representing a directory ("tree artifact"):

1. instead of args.add(src.path), use args.add(src);
2. instead of args.add(dir.path), use args.add_all([dir], expand_directories = False);
3. instead of args.add(src.dirname), use:

def _dirname(file):
    return file.dirname

def _my_rule_impl(ctx):
    ...
    args.add_all([src], map_each = _dirname)

Generally speaking, all functions that return a path string that may contain a configuration prefix such as bazel-out/darwin-amd64-fastbuild/bin must only be called in map_each callbacks, where they are automatically path mapped by Bazel.

C++

Support for C++ compilation actions is work in progress here.

[illicitonion]

FWIW rules_pkl is a starlark rule which supports path mapping, see https://github.com/apple/rules_pkl/blob/bf3de08ea8c7f05329a2d59d9790ec8653d2a28c/pkl/private/pkl.bzl#L232 for an example.

[illicitonion]

When implementing support, we ran into #16430 (comment) - @fmeum I think the discussion there is currently waiting on a reply from you?

[fmeum]

I'll try to get back to it soon, but the main part of the discussion (what's the API going to look like, is Args supported, ...) is still very much open.

[lior10r]

Do you think that c++ support would be available at the next version (7.3.0)?

[fmeum]

I can't promise anything, but I would say that's very likely. The main PR has already been approved and the follow-ups are pretty small.

[ThomasCJY]

Is there any plan to support android?

[fmeum]

Do you have a link to an example project I could try this on? It is being used for Android internally at Google, but I don't know the state of internal vs. external Android rules well enough to assess whether this translated into Bazel support.