Lines Matching +full:toolchain +full:- +full:version
1 :::{default-domain} bzl
6 This documents how to configure the Python toolchain and runtimes for different
16 2. A library module with dev-only uses of Python. For example, a Java project
18 3. A library module without version constraints. For example, a rule set with
19 Python build tools, but defers to the user as to what Python version is used
21 4. A library module with version constraints. For example, a rule set with
22 Python build tools, and the module requires a specific version of Python
27 Root modules are always the top-most module. These are special in two ways:
34 explicitly specify the Python version you want to use. This ensures that
35 dependencies don't change the Python version out from under you. Remember that
36 `rules_python` will set a version by default, but it will change regularly as
37 it tracks a recent Python version.
40 you should read the dev-only library module section.
43 bazel_dep(name="rules_python", version=...)
46 python.toolchain(python_version = "3.12", is_default = True)
52 bzlmod module graph -- it's unknown where in the breadth-first search order the
56 #### Library modules with dev-only Python usage
58 A library module with dev-only Python usage is usually one where Python is only
61 Python to work. To configure this, follow the root-module setup, but remember to
66 bazel_dep(name = "rules_python", version=..., dev_dependency = True)
74 python.toolchain(python_version = "3.12", is_default=True)
77 #### Library modules without version constraints
79 A library module without version constraints is one where the version of Python
81 it's up to the root module to pick an appropriate version of Python.
85 `python.toolchain` -- rules_python ensures _some_ Python version is available,
86 but more often the root module will specify some version.
90 bazel_dep(name = "rules_python", version=...)
93 #### Library modules with version constraints
95 A library module with version constraints is one where the module requires a
96 specific Python version be used with its tools. This has some pros/cons:
98 * It allows the library's tools to use a different version of Python than
102 to test for the particular Python version they intend to run as.
103 * It raises the support burden for the library module because the version of
109 the version-aware rules for `py_binary`.
113 bazel_dep(name = "rules_python", version=...)
116 python.toolchain(python_version = "3.12")
124 ### Pinning to a Python version
126 Pinning to a version allows targets to force that a specific Python version is
127 used, even if the root module configures a different version as a default. This
130 1. For submodules to ensure they run with the appropriate Python version
131 2. To allow incremental, per-target, upgrading to newer Python versions,
132 typically in a mono-repo situation.
134 To configure a submodule with the version-aware rules, request the particular
135 version you need, then use the `@python_versions` repo to use the rules that
141 python.toolchain(
148 the rules that force that particular version. Multiple versions can be specified
151 For more documentation, see the bzlmod examples under the {gh-path}`examples`
154 ### Other toolchain details
156 The `python.toolchain()` call makes its contents available under a repo named
158 `python.toolchain(python_version="3.11")` creates the repo `@python_3_11`.
162 #### Toolchain usage in other rules
168 Variables](https://bazel.build/reference/be/make-variables). See the
169 {gh-path}`test_current_py_toolchain <tests/load_from_macro/BUILD.bazel>` target
172 ### Overriding toolchain defaults and adding more versions
180 * Setting particular `X.Y.Z` Python versions when modules request `X.Y` version
182 * Per-version control of the coverage tool used using
193 To depend on a particular unreleased version, you can do the following:
199 # Update the SHA and VERSION to the lastest version available here:
204 VERSION="0.23.1"
209 strip_prefix = "rules_python-{}".format(VERSION),
210 …b.com/bazelbuild/rules_python/releases/download/{}/rules_python-{}.tar.gz".format(VERSION,VERSION),
218 ### Workspace toolchain registration
220 To register a hermetic Python toolchain rather than rely on a system-installed interpreter for runt…
228 # We recommend using the same version your team is already standardized on.
243 …r registration, your Python targets will use the toolchain's interpreter during execution, but a s…
245 … using this toolchain. Please refer to [python-build-standalone documentation's _Quirks_ section](…
247 ## Autodetecting toolchain
249 The autodetecting toolchain is a deprecated toolchain that is built into Bazel.
256 as the lowest priority toolchain. For WORKSPACE builds, if no other toolchain
257 is registered, that toolchain will be used. For bzlmod builds, rules_python
258 automatically registers a higher-priority toolchain; it won't be used unless
259 there is a toolchain misconfiguration somewhere.
261 To aid migration off the Bazel-builtin toolchain, rules_python provides
263 toolchain, but is implemented using rules_python's objects.
280 toolchains a "toolchain suite".
284 {obj}`RBE`, cross-platform building, multiple Python versions,
290 ### Target toolchain type
292 The target toolchain type is {obj}`//python:toolchain_type`, and it
293 is for _target configuration_ runtime information, e.g., the Python version
302 This toolchain type is intended to hold only _target configuration_ values. As
303 such, when defining its associated {external:bzl:obj}`toolchain` target, only
304 set {external:bzl:obj}`toolchain.target_compatible_with` and/or
305 {external:bzl:obj}`toolchain.target_settings` constraints; there is no need to
306 set {external:bzl:obj}`toolchain.exec_compatible_with`.
308 ### Python C toolchain type
310 The Python C toolchain type ("py cc") is {obj}`//python/cc:toolchain_type`, and
318 This toolchain type is intended to hold only _target configuration_ values
320 its associated {external:obj}`toolchain` target, only set
321 {external:bzl:obj}`toolchain.target_compatible_with` and/or
322 {external:bzl:obj}`toolchain.target_settings` constraints; there is no need to
323 set {external:bzl:obj}`toolchain.exec_compatible_with`.
325 ### Exec tools toolchain type
327 The exec tools toolchain type is {obj}`//python:exec_tools_toolchain_type`,
331 This toolchain type is intended to hold only _exec configuration_ values --
332 usually tools (prebuilt or from-source) used to build Python targets.
338 The toolchain constraints of this toolchain type can be a bit more nuanced than
339 the other toolchain types. Typically, you set
340 {external:bzl:obj}`toolchain.target_settings` to the Python version the tools
341 are for, and {external:bzl:obj}`toolchain.exec_compatible_with` to the platform
342 they can run on. This allows the toolchain to first be considered based on the
343 target configuration (e.g. Python version), then for one to be chosen based on
349 * If you had a precompiler that supported any version of Python, then
350 putting the Python version in `target_settings` is unnecessary.
362 ### Custom toolchain example
364 Here, we show an example for a semi-complicated toolchain suite, one that is:
366 * A CPython-based interpreter
367 * For Python version 3.12.0
368 * Using an in-build interpreter built from source
414 precompiler = "precompiler-cpython-3.12"
422 # Putting toolchain() calls in a separate package from the toolchain
425 toolchain(
427 toolchain = "//toolchain_impl:runtime_pair",
431 toolchain(
433 toolchain = "//toolchain_impl:py_cc_toolchain_impl",
438 toolchain(
440 toolchain = "//toolchain_impl:exec_tools_toolchain_impl",
453 When registering custom toolchains, be aware of the the [toolchain registration
454 order](https://bazel.build/extending/toolchains#toolchain-resolution). In brief,
455 toolchain order is the BFS-order of the modules; see the bazel docs for a more
459 The toolchain() calls should be in a separate BUILD file from everything else.
464 ## Toolchain selection flags
466 Currently the following flags are used to influence toolchain selection:
467 * {obj}`--@rules_python//python/config_settings:py_linux_libc` for selecting the Linux libc variant.
468 * {obj}`--@rules_python//python/config_settings:py_freethreaded` for selecting