//python/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='python3', 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 “python3”)

  An absolute path or program name on the PATH env var.

  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.

  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