fix(toolchains): register native_build_toolchain per exec/target platform for sdist builds (#928)

## Problem

`native_build_toolchain` (used by `pep517_whl` for sdist builds) was not
registered with `@rules_py_tools//:all` and it was a single static
toolchain with `use_target_platform_constraints = True`. This only
matches when exec == target, but Bazel needs one registered entry per
exec platform so it can resolve `native_build_toolchain_type` for each
build host.

## Fix

Generate one `native_build_toolchain` entry per exec platform in
`toolchains_repo` (`repo.bzl`), so they land in `@rules_py_tools//:all`
which is already registered by all users.

`native_build_toolchain_type` now resolves automatically on all
supported exec platforms via the existing
`register_toolchains("@rules_py_tools//:all")`.

---------

Co-authored-by: Jason Bedard <jason+github@jbedard.ca>

Author: gregmagolan

e2e/MODULE.bazel

@@ -47,6 +47,13 @@ use_repo(interpreters, "python_interpreters")
 
 register_toolchains("@python_interpreters//:all")
 
+# rules_py tools — provides the native_build_toolchain entries for sdist builds.
+tools = use_extension("@aspect_rules_py//py:extensions.bzl", "py_tools")
+tools.rules_py_tools()
+use_repo(tools, "rules_py_tools")
+
+register_toolchains("@rules_py_tools//:all")
+
 # For the OCI tests
 # {{{
 oci = use_extension("@rules_oci//oci:extensions.bzl", "oci")
@@ -345,4 +352,21 @@ uv.project(
     lock = "//cases/pytest-subdir-imports:uv.lock",
     pyproject = "//cases/pytest-subdir-imports:pyproject.toml",
 )
+
+# For cases/uv-sdist-native-build
+# Verify that native_build_toolchain_type is registered via @rules_py_tools//:all
+# so that sdist packages with C extensions can be built with pep517_native_whl.
+# python-geohash is sdist-only and contains a C++ extension (_geohash).
+# {{{
+uv.project(
+    default_build_dependencies = [
+        "build",
+        "setuptools",
+    ],
+    hub_name = "pypi",
+    lock = "//cases/uv-sdist-native-build:uv.lock",
+    pyproject = "//cases/uv-sdist-native-build:pyproject.toml",
+)
+# }}}
+
 use_repo(uv, "pypi")

e2e/cases/uv-sdist-native-build/BUILD.bazel

@@ -0,0 +1,16 @@
+# Regression test: python-geohash (sdist-only, C++ extension) must be buildable
+# when native_build_toolchain_type is registered via @rules_py_tools//:all.
+#
+# The pep517_native_whl rule requires the native_build_toolchain_type to resolve,
+# asserting that the exec and target platforms match. This test verifies that the
+# per-platform toolchain entries generated into @rules_py_tools are reachable.
+
+load("@aspect_rules_py//py/unstable:defs.bzl", "py_venv_test")
+
+py_venv_test(
+    name = "test",
+    srcs = ["test_geohash.py"],
+    main = "test_geohash.py",
+    target_compatible_with = ["@platforms//os:linux"],
+    deps = ["@pypi//python_geohash"],
+)

e2e/cases/uv-sdist-native-build/pyproject.toml

@@ -0,0 +1,7 @@
+[project]
+name = "uv-sdist-native-build"
+version = "0.0.0"
+requires-python = ">=3.11"
+dependencies = [
+    "python-geohash",
+]

e2e/cases/uv-sdist-native-build/test_geohash.py

@@ -0,0 +1,16 @@
+"""Verify that python-geohash (built from sdist via pep517_native_whl) is importable."""
+
+import geohash
+
+
+def test_encode_decode():
+    lat, lon = 37.7749, -122.4194
+    encoded = geohash.encode(lat, lon)
+    assert encoded, "geohash.encode should return a non-empty string"
+    decoded = geohash.decode(encoded)
+    assert len(decoded) == 2, "geohash.decode should return (lat, lon)"
+
+
+if __name__ == "__main__":
+    test_encode_decode()
+    print("OK")

e2e/cases/uv-sdist-native-build/uv.lock

@@ -28,31 +28,24 @@ toolchain_type(
     visibility = ["//visibility:public"],
 )
 
-# Implementation detail of the target exec toolchain
+# Dummy toolchain backing target — no binary, used as a sentinel.
+# Public so the generated @rules_py_tools repo can reference it for
+# native_build toolchain entries.
 dummy_toolchain(
     name = "empty",
-    visibility = ["//visibility:private"],
+    visibility = ["//visibility:public"],
 )
 
 toolchain_type(
     name = "native_build_toolchain_type",
+    visibility = ["//visibility:public"],
 )
 
 toolchain_type(
     name = "exec_tools_toolchain_type",
     visibility = ["//visibility:public"],
 )
 
-# This creates a toolchain instance with exec_compatible_with placement
-# constraints matching the target, backed by the Python toolchain already
-# resolved for the target.
-toolchain(
-    name = "native_build_toolchain",
-    toolchain = ":empty",
-    toolchain_type = "native_build_toolchain_type",
-    use_target_platform_constraints = True,
-)
-
 bzl_library(
     name = "autodetecting",
     srcs = ["autodetecting.bzl"],

py/private/toolchain/BUILD.bazel

@@ -69,6 +69,28 @@ toolchain(
                     compatible_with = meta.compatible_with,
                 )
 
+    # Generate one native_build toolchain entry per platform.
+    # Used by pep517_whl (sdist builds) as a sentinel asserting the build is
+    # running natively (exec == target). Both exec_compatible_with and
+    # target_compatible_with are set to the same constraints so that this
+    # toolchain is only selected when the exec and target platforms match —
+    # cross-compilation sdist builds are unsupported and correctly fail.
+    # Registered via @rules_py_tools//:all.
+    for [platform, meta] in TOOLCHAIN_PLATFORMS.items():
+        build_content += """
+toolchain(
+    name = "native_build_{platform}_toolchain",
+    exec_compatible_with = {compatible_with},
+    target_compatible_with = {compatible_with},
+    toolchain = "@aspect_rules_py//py/private/toolchain:empty",
+    toolchain_type = "@aspect_rules_py//py/private/toolchain:native_build_toolchain_type",
+)
+
+""".format(
+            platform = platform,
+            compatible_with = meta.compatible_with,
+        )
+
     # Base BUILD file for this repository
     repository_ctx.file("BUILD.bazel", build_content)
 
@@ -87,14 +109,35 @@ toolchains_repo = repository_rule(
 )
 
 def _prerelease_toolchains_repo_impl(repository_ctx):
-    repository_ctx.file("BUILD.bazel", "# No toolchains created for pre-releases")
+    # No tool toolchains in prerelease (no pre-built binaries), but we still
+    # generate the native_build toolchain entries. These use the sentinel
+    # @aspect_rules_py//py/private/toolchain:empty target which requires no
+    # downloaded binary, so they work correctly in development/prerelease mode.
+    build_content = "# No tool toolchains created for pre-releases\n"
+    for [platform, meta] in TOOLCHAIN_PLATFORMS.items():
+        build_content += """
+toolchain(
+    name = "native_build_{platform}_toolchain",
+    exec_compatible_with = {compatible_with},
+    target_compatible_with = {compatible_with},
+    toolchain = "@aspect_rules_py//py/private/toolchain:empty",
+    toolchain_type = "@aspect_rules_py//py/private/toolchain:native_build_toolchain_type",
+)
+
+""".format(
+            platform = platform,
+            compatible_with = meta.compatible_with,
+        )
+    repository_ctx.file("BUILD.bazel", build_content)
 
 prerelease_toolchains_repo = repository_rule(
     _prerelease_toolchains_repo_impl,
-    doc = """Create a repo with an empty BUILD file, which registers no toolchains.
-    This is used for pre-releases, which have no pre-built binaries, but still want to call
+    doc = """Create a repo with native_build toolchain entries but no tool toolchains.
+    This is used for pre-releases, which have no pre-built tool binaries, but still want to call
       register_toolchains("@this_repo//:all")
-    By doing this, we can avoid those register_toolchains callsites needing to be conditional on IS_PRERELEASE
+    By doing this, we can avoid those register_toolchains callsites needing to be conditional on IS_PRERELEASE.
+    The native_build toolchain entries are included because they reference only the sentinel :empty
+    target (no downloaded binary required), so they work in dev mode too.
     """,
 )
 

py/private/toolchain/repo.bzl

@@ -159,6 +159,16 @@ constraints of the target platform.
         # Create an exec group which depends on a toolchain which can only be
         # resolved to exec_compatible_with constraints equal to the target. This
         # allows us to discover what those constraints need to be.
+        #
+        # NATIVE_BUILD_TOOLCHAIN has matching exec_compatible_with and
+        # target_compatible_with, so this exec group only resolves when the exec
+        # and target platforms match. Cross-compilation of sdists is intentionally
+        # unsupported: PEP 517 build backends (setuptools, meson-python, etc.)
+        # have no standard mechanism for cross-compilation, Python headers for
+        # the target platform are not readily available, and output wheel tags
+        # would need to encode the target platform with no upstream tooling
+        # support. Packages that need cross-compiled native extensions should
+        # publish pre-built wheels for their target platforms instead.
         "target": exec_group(
             toolchains = [
                 PY_TOOLCHAIN,