8000 docs: Better explain when and how to use toolchains for bzlmod (#1349) · matts1/rules_python@e355bec · GitHub 8000
[go: up one dir, main page]
Skip to content

Commit e355bec

Browse files
rickeylevrickeylev
authored
docs: Better explain when and how to use toolchains for bzlmod (bazel-contrib#1349)
This explains the different ways to register toolchains and how to use them. Also fixes python_aliases -> python_versions repo name
1 parent afc40f0 commit e355bec

File tree

3 files changed

+81
-17
lines changed

3 files changed

+81
-17
lines changed

‎README.md

Lines changed: 74 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -41,37 +41,98 @@ the older way of configuring bazel with a `WORKSPACE` file.
4141

4242
**IMPORTANT: bzlmod support is still in Beta; APIs are subject to change.**
4343

44+
The first step to using rules_python with bzlmod is to add the dependency to
45+
your MODULE.bazel file:
46+
47+
```starlark
48+
# Update the version "0.0.0" to the release found here:
49+
# https://github.com/bazelbuild/rules_python/releases.
50+
bazel_dep(name = "rules_python", version = "0.0.0")
51+
```
52+
53+
Once added, you can load the rules and use them:
54+
55+
```starlark
56+
load("@rules_python//python:py_binary.bzl", "py_binary")
57+
58+
py_binary(...)
59+
```
60+
61+
Depending on what you're doing, you likely want to do some additional
62+
configuration to control what Python version is used; read the following
63+
sections for how to do that.
64+
4465
#### Toolchain registration with bzlmod
4566

4667
A default toolchain is automatically configured depending on
4768
`rules_python`. Note, however, the version used tracks the most recent Python
4869
release and will change often.
4970

50-
If you want to register specific Python versions, then use
51-
`python.toolchain()` for each version you need:
71+
If you want to use a specific Python version for your programs, then how
72+
to do so depends on if you're configuring the root module or not. The root
73+
module is special because it can set the *default* Python version, which
74+
is used by the version-unaware rules (e.g. `//python:py_binary.bzl` et al). For
75+
submodules, it's recommended to use the version-aware rules to pin your programs
76+
to a specific Python version so they don't accidentally run with a different
77+
version configured by the root module.
78+
79+
##### Configuring and using the default Python version
80+
81+
To specify what the default Python version is, set `is_default = True` when
82+
calling `python.toolchain()`. This can only be done by the root module; it is
83+
silently ignored if a submodule does it. Similarly, using the version-unaware
84+
rules (which always use the default Python version) should only be done by the
85+
root module. If submodules use them, then they may run with a different Python
86+
version than they expect.
5287

5388
```starlark
54-
# Update the version "0.0.0" to the release found here:
55-
# https://github.com/bazelbuild/rules_python/releases.
56-
bazel_dep(name = "rules_python", version = "0.0.0")
5789
python = use_extension("@rules_python//python/extensions:python.bzl", "python")
5890

5991
python.toolchain(
6092
python_version = "3.11",
93+
is_default = True,
6194
)
62-
use_repo(python, "python_3_11", "python_aliases")
6395
```
6496

65-
The `use_repo` statement above is essential as it imports one or more
66-
repositories into the current module's scope. The two repositories `python_3_11`
67-
and `python_aliases` are created internally by the `python` extension.
68-
The name `python_versions` is a constant and is always imported. The identifier
69-
`python_3_11` was created by using `"python_{}".format("3.11".replace(".","_"))`.
70-
This rule takes the Python version and creates the repository name using
71-
the version.
97+
Then use the base rules from e.g. `//python:py_binary.bzl`.
98+
99+
##### Pinning to a Python version
100+
101+
Pinning to a version allows targets to force that a specific Python version is
102+
used, even if the root module configures a different version as a default. This
103+
is most useful for two cases:
104+
105+
1. For submodules to ensure they run with the appropriate Python version
106+
2. To allow incremental, per-target, upgrading to newer Python versions,
107+
typically in a mono-repo situation.
108+
109+
To configure a submodule with the version-aware rules, request the particular
110+
version you need, then use the `@python_versions` repo to use the rules that
111+
force specific versions:
112+
113+
```starlark
114+
python = use_extension("@rules_python//python/extensions:python.bzl", "python")
115+
116+
python.toolchain(
117+
python_version = "3.11",
118+
)
119+
use_repo(python, "python_versions")
120+
```
121+
122+
Then use e.g. `load("@python_versions//3.11:defs.bzl", "py_binary")` to use
123+
the rules that force that particular version. Multiple versions can be specified
124+
and use within a single build.
72125

73126
For more documentation, see the bzlmod examples under the [examples](examples) folder. Look for the examples that contain a `MODULE.bazel` file.
74127

128+
##### Other toolchain details
129+
130+
The `python.toolchain()` call makes its contents available under a repo named
131+
`python_X_Y`, where X and Y are the major and minor versions. For example,
132+
`python.toolchain(python_version="3.11")` creates the repo `@python_3_11`.
133+
Remember to call `use_repo()` to make repos visible to your module:
134+
`use_repo(python, "python_3_11")`
135+
75136
### Using a WORKSPACE file
76137

77138
To import rules_python in your project, you first need to add it to your

‎python/extensions/pip.bzl

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -345,9 +345,10 @@ Targets from different hubs should not be used together.
345345
"python_version": attr.string(
346346
mandatory = True,
347347
doc = """
348-
The Python version to use for resolving the pip dependencies. If not specified,
349-
then the default Python version (as set by the root module or rules_python)
350-
will be used.
348+
The Python version to use for resolving the pip dependencies, in Major.Minor
349+
format (e.g. "3.11"). Patch level granularity (e.g. "3.11.1") is not supported.
350+
If not specified, then the default Python version (as set by the root module or
351+
rules_python) will be used.
351352
352353
The version specified here must have a corresponding `python.toolchain()`
353354
configured.

‎python/extensions/python.bzl

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -250,7 +250,9 @@ A toolchain's repository name uses the format `python_{major}_{minor}`, e.g.
250250
),
251251
"python_version": attr.string(
252252
mandatory = True,
253-
doc = "The Python version, in `major.minor` format, e.g '3.12', to create a toolchain for.",
253+
doc = "The Python version, in `major.minor` format, e.g " +
254+
"'3.12', to create a toolchain for. Patch level " +
255+
"granularity (e.g. '3.12.1') is not supported.",
254256
),
255257
},
256258
),

0 commit comments

Comments
 (0)
0