Skip to content

docs: document current_py_cc_headers and related toolchain targets #3602

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Saish-3 wants to merge 2 commits into
base: main
Choose a base branch
from
+26 −4
Open

docs: document current_py_cc_headers and related toolchain targets #3602

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6443a87
Docs: Document current_py_cc_headers and related toolchain targets
Saish-3 Feb 16, 2026
19e1447
docs: format target names with backticks
Saish-3 Feb 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 26 additions & 4 deletions docs/toolchains.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -555,18 +555,18 @@ Python is used to run a program but also makes it easy to use a Python version
that isn't compatible with build-time assumptions.

```
register_toolchains("@rules_python//python/runtime_env_toolchains:all")
`register_toolchains`("@rules_python//python/runtime_env_toolchains:all")
```

Note that this toolchain has no constraints, i.e. it will match any platform,
Note that this `toolchain` has no constraints, i.e. it will match any platform,
Python version, etc.

:::{seealso}
[Local toolchain], which creates a more full featured toolchain from a
[Local `toolchain`], which creates a more full featured toolchain from a
locally installed Python.
:::

### Autodetecting toolchain
### Autodetecting `toolchain`

The autodetecting toolchain is a deprecated toolchain that is built into Bazel.
**Its name is a bit misleading: it doesn't autodetect anything.** All it does is
Expand Down Expand Up @@ -846,3 +846,25 @@ The [`//python/bin:repl` target](repl) provides an environment identical to
what `py_binary` provides. That means it handles things like the
[`PYTHONSAFEPATH`](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONSAFEPATH)
environment variable automatically. The `//python/bin:python` target will not.
## Consuming Python C headers and libraries

The following targets expose the headers and libraries from the
currently selected Python C toolchain:

- `@rules_python//python/cc:`
`current_py_cc_headers`
- `@rules_python//python/cc:current_py_cc_headers_abi3`
- `@rules_python//python/cc:current_py_cc_libs`

These targets behave similarly to a `cc_library`, but instead of defining
their own sources, they forward providers from the underlying toolchain-
selected `cc_library`.

A Python C toolchain must be registered for these targets to work.
Under bzlmod, a toolchain is registered automatically. In non-bzlmod
setups, users must ensure that a toolchain is explicitly registered.
Comment on lines +864 to +865
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For consistency with the rest of the document, please wrap bzlmod and non-bzlmod in backticks to format them as code.

Suggested change
Under bzlmod, a toolchain is registered automatically. In non-bzlmod
setups, users must ensure that a toolchain is explicitly registered.
Under `bzlmod`, a toolchain is registered automatically. In `non-bzlmod`
setups, users must ensure that a toolchain is explicitly registered.


Users should depend on these targets instead of legacy alias targets
when embedding Python or building C extensions, as this ensures
compatibility across different toolchain configurations.