Skip to content

Commit 6938ddc

Browse files
committed
feat: allow toolchain without host compatible variant
1 parent e73dccf commit 6938ddc

15 files changed

+510
-89
lines changed

.python-version

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
3.13.3
1+
3.12

CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,10 @@ END_UNRELEASED_TEMPLATE
105105
Set the `RULES_PYTHON_ENABLE_PIPSTAR=1` environment variable to enable it.
106106
* (utils) Add a way to run a REPL for any `rules_python` target that returns
107107
a `PyInfo` provider.
108+
* (toolchains) Arbitrary python-build-standalone runtimes can be registered
109+
and activated with custom flags. See the [Registering custom runtimes]
110+
docs and {obj}`single_version_platform_override()` API docs for more
111+
information.
108112

109113
{#v0-0-0-removed}
110114
### Removed

MODULE.bazel

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,23 @@ dev_python = use_extension(
125125
dev_python.override(
126126
register_all_versions = True,
127127
)
128+
dev_python.toolchain(python_version = "3.13")
129+
130+
# For testing an arbitrary runtime triggered by a custom flag.
131+
# See //tests/toolchains:custom_platform_toolchain_test
132+
dev_python.single_version_platform_override(
133+
platform = "linux-x86-install-only-stripped",
134+
python_version = "3.13.3",
135+
sha256 = "01d08b9bc8a96698b9d64c2fc26da4ecc4fa9e708ce0a34fb88f11ab7e552cbd",
136+
#target_compatible_with = [
137+
# "@platforms//os:linux",
138+
# "@platforms//cpu:x86_64",
139+
#],
140+
#target_settings = [
141+
# "@@//tests/support:is_custom_runtime_linux-x86-install-only-stripped",
142+
#],
143+
urls = ["https://github.com/astral-sh/python-build-standalone/releases/download/20250409/cpython-3.13.3+20250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz"],
144+
)
128145

129146
dev_pip = use_extension(
130147
"//python/extensions:pip.bzl",

docs/toolchains.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -243,6 +243,76 @@ existing attributes:
243243
* Adding additional Python versions via {bzl:obj}`python.single_version_override` or
244244
{bzl:obj}`python.single_version_platform_override`.
245245

246+
### Registering custom runtimes
247+
248+
Because the python-build-standalone project has _thousands_ of prebuilt runtimes
249+
available, rules_python only includes popular runtimes in its built in
250+
configurations. If you want to use a runtime that isn't already known to
251+
rules_python then {obj}`single_version_platform_override()` can be used to do
252+
so. In short, it allows specifying an arbitrary URL and using custom flags
253+
to control when a runtime is used.
254+
255+
In the example below, we register a particular python-build-standalone runtime
256+
that is activated for Linux x86 builds when the custom flag
257+
`--//:runtime=my-custom-runtime` is set.
258+
259+
```
260+
# File: MODULE.bazel
261+
bazel_dep(name = "bazel_skylib", version = "1.7.1.")
262+
bazel_dep(name = "rules_python", version = "1.5.0")
263+
python = use_extension("@rules_python//python/extensions:python.bzl", "python")
264+
python.toolchain(python_version="3.13.3")
265+
python.single_version_platform_override(
266+
platform = "my-platform",
267+
python_version = "3.13.3",
268+
sha256 = "01d08b9bc8a96698b9d64c2fc26da4ecc4fa9e708ce0a34fb88f11ab7e552cbd",
269+
target_compatible_with = [
270+
"@platforms//os:linux",
271+
"@platforms//cpu:x86_64",
272+
],
273+
target_settings = [
274+
"@@//:runtime=my-custom-runtime",
275+
],
276+
urls = ["https://github.com/astral-sh/python-build-standalone/releases/download/20250409/cpython-3.13.3+20250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz"],
277+
)
278+
# File: //:BUILD.bazel
279+
load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
280+
string_flag(
281+
name = "custom_runtime",
282+
build_setting_default = "",
283+
)
284+
config_setting(
285+
name = "is_custom_runtime_linux-x86-install-only-stripped",
286+
flag_values = {
287+
":custom_runtime": "linux-x86-install-only-stripped",
288+
},
289+
)
290+
```
291+
292+
Notes:
293+
- While any URL and archive can be used, it's assumed their content looks how
294+
a python-build-standalone archive looks.
295+
- `python.toolchain()` is required if the version is unknown; if the version
296+
is already known, it can be omitted.
297+
- A "version aware" toolchain is registered, which means the Python version flag
298+
must also match (e.g. `--@rules_python//python/config_settings:python_version=3.13.3`
299+
must be set -- see `minor_mapping` and `is_default` for controls and docs
300+
about version matching and selection).
301+
- The labels in `target_settings` must be absolute; `@@` refers to the main repo.
302+
- The `target_settings` are `config_setting` targets, which means you can
303+
customize how matching occurs.
304+
305+
:::{seealso}
306+
See {obj}`//python/config_settings` for flags rules_python already defines
307+
that can be used with `target_settings`. Some particular ones of note are:
308+
{flag}`--py_linux_libc` and {flag}`--py_freethreaded`, among others.
309+
:::
310+
311+
:::{versionadded} VERSION_NEXT_FEATURE
312+
Added support for custom platform names, `target_compatible_with`, and
313+
`target_settings` with `single_version_platform_override`.
314+
:::
315+
246316
### Using defined toolchains from WORKSPACE
247317

248318
It is possible to use toolchains defined in `MODULE.bazel` in `WORKSPACE`. For example

python/private/BUILD.bazel

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -241,11 +241,17 @@ bzl_library(
241241
],
242242
)
243243

244+
bzl_library(
245+
name = "platform_info_bzl",
246+
srcs = ["platform_info.bzl"],
247+
)
248+
244249
bzl_library(
245250
name = "python_bzl",
246251
srcs = ["python.bzl"],
247252
deps = [
248253
":full_version_bzl",
254+
":platform_info_bzl",
249255
":python_register_toolchains_bzl",
250256
":pythons_hub_bzl",
251257
":repo_utils_bzl",

python/private/platform_info.bzl

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
"""Helper to define a struct used to define platform metadata."""
2+
3+
def platform_info(
4+
*,
5+
compatible_with = [],
6+
flag_values = {},
7+
target_settings = [],
8+
os_name,
9+
arch):
10+
"""Creates a struct of platform metadata.
11+
12+
This is just a helper to ensure structs are created the same and
13+
the meaning/values are documented.
14+
15+
Args:
16+
compatible_with: list[str], where the values are string labels. These
17+
are the target_compatible_with values to use with the toolchain
18+
flag_values: dict[str|Label, Any] of config_setting.flag_values
19+
compatible values. DEPRECATED -- use target_settings instead
20+
target_settings: list[str], where the values are string labels. These
21+
are the target_settings values to use with the toolchain.
22+
os_name: str, the os name; must match the name used in `@platfroms//os`
23+
arch: str, the cpu name; must match the name used in `@platforms//cpu`
24+
25+
Returns:
26+
A struct with attributes and values matching the args.
27+
"""
28+
return struct(
29+
compatible_with = compatible_with,
30+
flag_values = flag_values,
31+
target_settings = target_settings,
32+
os_name = os_name,
33+
arch = arch,
34+
)

0 commit comments

Comments
 (0)