local_toolchains:repos.bzl

Rules/macros for repository phase for local toolchains.

Added in version 1.4.0.

repo rule local_runtime_repo(name, repo_mapping, interpreter_path='', interpreter_target=None, on_failure='skip')

Use a locally installed Python runtime as a toolchain implementation.

Note this uses the runtime as a platform runtime. A platform runtime means means targets don’t include the runtime itself as part of their runfiles or inputs. Instead, users must assure that where the targets run have the runtime pre-installed or otherwise available.

This results in lighter weight binaries (in particular, Bazel doesn’t have to create thousands of files for every py_test), at the risk of having to rely on a system having the necessary Python installed.

Attributes:

name – (Name)
A unique name for this repository.

mandatory
repo_mapping – (dict[str, str])
In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension’s implementation function).

optional
interpreter_path – (str) (default “”)
An absolute path or program name on the PATH env var.

Mutually exclusive with interpreter_target.

Values with slashes are assumed to be the path to a program. Otherwise, it is treated as something to search for on PATH

Note that, when a plain program name is used, the path to the interpreter is resolved at repository evalution time, not runtime of any resulting binaries.

If not set, defaults to python3.

See also

The interpreter_target attribute for getting the interpreter from a label

optional
interpreter_target – (label) (default None)
A label to a Python interpreter executable.

Mutually exclusive with interpreter_path.

On Windows, if the path doesn’t exist, various suffixes will be tried to find a usable path.

See also

The interpreter_path attribute for getting the interpreter from a path or PATH environment lookup.

optional
on_failure – (str) (default “skip”)
How to handle errors when trying to automatically determine settings.
- skip will silently skip creating a runtime. Instead, a non-functional runtime will be generated and marked as incompatible so it cannot be used. This is best if a local runtime is known not to work or be available in certain cases and that’s OK. e.g., one use windows paths when there are people running on linux.
- warn will print a warning message. This is useful when you expect a runtime to be available, but are OK with it missing and falling back to some other runtime.
- fail will result in a failure. This is only recommended if you must ensure the runtime is available.
optional

Envvars:

DEVELOPER_DIR, PATH, RULES_PYTHON_REPO_DEBUG, XCODE_VERSION

repo rule local_runtime_toolchains_repo(name, repo_mapping, default_runtimes=[], exec_compatible_with={}, runtimes=[], target_compatible_with={}, target_settings={})

Create a repo of toolchains definitions for local runtimes.

This is intended to be used on the toolchain implemenations generated by local_runtime_repo.

NOTE: This does not call native.register_toolchains – the caller is responsible for registering the toolchains this defines.

Attributes:

name – (Name)
A unique name for this repository.

mandatory
repo_mapping – (dict[str, str])
In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension’s implementation function).

optional
default_runtimes – (list[str]) (default [])
The repo names of local_runtime_repo repos to define as toolchains.

These will be defined as version-unaware toolchains. This means they will match any Python version. As such, they are registered after the version-aware toolchains defined by the runtimes attribute.

If not set, then the runtimes values will be used.

Note that order matters: it determines the toolchain priority within the package.

optional
exec_compatible_with – (dict[str, list[str]]) (default {})
Constraints that must be satisfied by an exec platform for a toolchain to be used.

This is a dict[str, list[str]], where the keys are repo names from the runtimes or default_runtimes args, and the values are constraint target labels (e.g. OS, CPU, etc).

Note

Specify @//foo:bar, not simply //foo:bar or :bar. The additional @ is needed because the strings are evaluated in a different context than where they originate.

The list of settings become the toolchain.exec_compatible_with value for each respective repo.

This allows a local toolchain to only be used if certain exec platform conditions are met, typically values from @platforms.

See the [Local toolchains] docs for examples and further information.

Added in version 1.5.0.

optional
runtimes – (list[str]) (default [])
The repo names of local_runtime_repo repos to define as toolchains.

These will be defined as version-aware toolchains. This means they require the --//python/config_settings:python_version to be set in order to match. These are registered before default_runtimes.

Note that order matters: it determines the toolchain priority within the package.

optional
target_compatible_with – (dict[str, list[str]]) (default {})
Constraints that must be satisfied for a toolchain to be used.

This is a dict[str, list[str]], where the keys are repo names from the runtimes or default_runtimes args, and the values are constraint target labels (e.g. OS, CPU, etc), or the special string "HOST_CONSTRAINTS" (which will be replaced with the current Bazel hosts’s constraints).

If a repo’s entry is missing or empty, it defaults to the supported OS the underlying runtime repository detects as compatible.

Note

Specify @//foo:bar, not simply //foo:bar or :bar. The additional @ is needed because the strings are evaluated in a different context than where they originate.

The list of settings becomes the the toolchain.target_compatible_with value for each respective repo; i.e. they replace the auto-detected values the local runtime itself computes.

This allows a local toolchain to only be used if certain target platform conditions are met, typically values from @platforms.

See the [Local toolchains] docs for examples and further information.

See also

The target_settings attribute, which handles config_setting values, instead of constraints.

Added in version 1.5.0.

optional
target_settings – (dict[str, list[str]]) (default {})
Config settings that must be satisfied for a toolchain to be used.

This is a dict[str, list[str]], where the keys are repo names from the runtimes or default_runtimes args, and the values are config_setting() target labels.

If a repo’s entry is missing or empty, it will default to @<repo>//:is_match_python_version (for repos in runtimes) or an empty list (for repos in default_runtimes).

Note

Specify @//foo:bar, not simply //foo:bar or :bar. The additional @ is needed because the strings are evaluated in a different context than where they originate.

The list of settings will be applied atop of any of the local runtime’s settings that are used for toolchain.target_settings. i.e. they are evaluated first and guard the checking of the local runtime’s auto-detected conditions.

This allows a local toolchain to only be used if certain flags or config setting conditions are met. Such conditions can include user-defined flags, platform constraints, etc.

See the [Local toolchains] docs for examples and further information.

See also

The target_compatible_with attribute, which handles constraint values, instead of config_settings.

Added in version 1.5.0.

optional

Envvars:

RULES_PYTHON_REPO_DEBUG