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_sandboxing
  • worker with --worker_sandboxing and --noworker_multiplex

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.

C/C++

C++ compilation actions have experimental support for path mapping.

Requirements

Bazel 7.3.0rc1 or higher is required and path mapping needs to be explicitly enabled for C/C++ actions via --modify_execution_info=CppCompile=+supports-path-mapping.

Known issues

The following features are not yet supported (but being worked on):

• output directories ("tree artifacts") in srcs (Add path mapping support for C++ compile action templates #22890)
• layering_check (Support layering_check with C++ path mapping #22957)
• location expansion in copts (Heuristically path map copts and defines #23630)

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.