//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:

PATH, RULES_PYTHON_REPO_DEBUG

repo rule local_runtime_repo.local_runtime_toolchains_repo(name, repo_mapping, default_runtimes=[], runtimes=[])

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.

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

  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

Envvars:

RULES_PYTHON_REPO_DEBUG