From 6443a87212b3128877694acf2ab97de180e8dc3b Mon Sep 17 00:00:00 2001 From: Saish-3 Date: Mon, 16 Feb 2026 16:53:27 +0530 Subject: [PATCH 1/3] Docs: Document current_py_cc_headers and related toolchain targets --- docs/toolchains.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/toolchains.md b/docs/toolchains.md index 186ad11e73..d1cfaa8931 100644 --- a/docs/toolchains.md +++ b/docs/toolchains.md @@ -846,3 +846,24 @@ 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. + +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. + From 19e1447d6fbbc67af2a776b8892dee449db7a2da Mon Sep 17 00:00:00 2001 From: Saish-3 Date: Mon, 16 Feb 2026 19:25:54 +0530 Subject: [PATCH 2/3] docs: format target names with backticks --- docs/toolchains.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/toolchains.md b/docs/toolchains.md index d1cfaa8931..1a8f872837 100644 --- a/docs/toolchains.md +++ b/docs/toolchains.md @@ -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 @@ -851,7 +851,8 @@ environment variable automatically. The `//python/bin:python` target will not. 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` - `@rules_python//python/cc:current_py_cc_headers_abi3` - `@rules_python//python/cc:current_py_cc_libs` From 83aef9b5865c4ebc2652ba2b428d4a6f1893a35e Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Tue, 17 Feb 2026 16:45:17 -0800 Subject: [PATCH 3/3] add seealso, some xref, and fix some backticks --- docs/toolchains.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/toolchains.md b/docs/toolchains.md index 1a8f872837..1e1e61fde8 100644 --- a/docs/toolchains.md +++ b/docs/toolchains.md @@ -558,7 +558,7 @@ that isn't compatible with build-time assumptions. `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} @@ -566,7 +566,7 @@ Python version, etc. 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 @@ -846,15 +846,16 @@ 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:` +- {obj}`@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` +- {obj}`@rules_python//python/cc:current_py_cc_headers_abi3` +- {obj}`@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- @@ -868,3 +869,8 @@ 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. + +:::{seealso} +The _How to get Python headres for C extensions_ how-to guide, and the +{obj}`@rules_python//python/cc` package API documentation. +:::