build: keep _build_shared.py as identical copies

[juenglin]

Description

Follow-up to #3000. That PR shared the PEP 517 helpers through a cuda_core/_build_shared.py symlink, which makes a Windows source build depend on core.symlinks=true. This change goes back to two regular files kept byte-identical by a pre-commit check.

cuda_core/_build_shared.py is a 100644 copy of cuda_bindings/_build_shared.py. check-build-shared-sync compares them with git diff --no-index; CI --all-files still catches drift. There is no intended build-flag or import-path change: each backend still loads _build_shared from its own package directory.

Checklist

• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[juenglin]

/ok to test 18ecce0

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: NVIDIA/cuda-python/.coderabbit.yaml
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 4d3b7bc8-0266-4038-8233-0b547c5f9d81

📥 Commits

Reviewing files that changed from the base of the PR and between 18ecce0 and 67ea7cf.

📒 Files selected for processing (12)

• CONTRIBUTING.md
• cuda_bindings/AGENTS.md
• cuda_bindings/MANIFEST.in
• cuda_bindings/_build_shared.py
• cuda_bindings/docs/source/install.rst
• cuda_core/AGENTS.md
• cuda_core/MANIFEST.in
• cuda_core/_build_shared.py
• cuda_core/_build_shared.py
• cuda_core/docs/source/install.rst
• cuda_python_test_helpers/cuda_python_test_helpers/build_shared.py
• cuda_python_test_helpers/cuda_python_test_helpers/cython_cache.py

🚧 Files skipped from review as they are similar to previous changes (2)

• cuda_core/_build_shared.py
• cuda_core/_build_shared.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• Build Improvements
  • Build configuration supports GNU, MSVC, and explicitly selected LLVM toolchains, with debug, coverage, and warnings-as-errors options where supported.
  • Optional Cython caching can be configured, and builds refresh when their configuration changes.
• Documentation
  • Windows contributors can build and test outside WSL without enabling Git symlinks; setup guidance explains which links remain and how to restore them.
• Chores
  • Added a pre-commit check that flags mismatched shared build files.

Walkthrough

The pull request adds build helpers to cuda_core for CUDA discovery, toolchain setup, compiler flags, Cython support, and build-key stamps. It adds a pre-commit check for matching helper copies and updates Windows symlink guidance.

Changes

Shared Build Helpers

Layer / File(s)	Summary
CUDA discovery and toolchain flags cuda_core/_build_shared.py	Adds CUDA path discovery, platform-specific toolchain selection, compiler environment handling, and compile and link flag generation.
Cython support and build-key stamps cuda_core/_build_shared.py	Adds opt-in Cython cache paths, a temporary include-tree symlink alias, and build-key stamp checks and recording.
Helper-copy parity and symlink guidance .pre-commit-config.yaml, cuda_bindings/_build_shared.py, cuda_bindings/AGENTS.md, cuda_bindings/MANIFEST.in, cuda_bindings/docs/source/install.rst, cuda_core/AGENTS.md, cuda_core/MANIFEST.in, cuda_core/docs/source/install.rst, CONTRIBUTING.md, cuda_python_test_helpers/cuda_python_test_helpers/*	Adds a pre-commit check that compares the helper copies. Updates documentation and comments about package-local helper copies and Windows symlink handling.

Priority: ⬇️ Low

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 67ea7

The change removes the Windows build dependency on symlink support while preserving package-local build paths and checking that the helper copies match. No concrete PR-specific merge risk remains.

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository: NVIDIA/cuda-python/.coderabbit.yaml
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 0aff2716-401b-4bb2-8ce4-2907013c389c

📥 Commits

Reviewing files that changed from the base of the PR and between 4c893de and 18ecce0.

📒 Files selected for processing (4)

• .pre-commit-config.yaml
• CONTRIBUTING.md
• cuda_core/_build_shared.py
• cuda_core/_build_shared.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

[coderabbitai]

Caution

Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository: NVIDIA/cuda-python/.coderabbit.yaml
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 0aff2716-401b-4bb2-8ce4-2907013c389c

📥 Commits

Reviewing files that changed from the base of the PR and between 4c893de and 18ecce0.

📒 Files selected for processing (4)

• .pre-commit-config.yaml
• CONTRIBUTING.md
• cuda_core/_build_shared.py
• cuda_core/_build_shared.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

🛑 Comments failed to post (2)

cuda_core/_build_shared.py (2)

6-9: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

important: The module docstring is out of date after this PR. Lines 6-7 still say that cuda_core/_build_shared.py is a symlink to this file, but this PR replaces the symlink with a regular file. Line 389 has the same problem: it says "the package's own copy through the symlink". Both copies must stay byte-identical because check-build-shared-sync compares them. Make the same wording fix in cuda_bindings/_build_shared.py and in this file. Say that the two files are identical copies and that the pre-commit hook checks them. Path(__file__) resolves under the package that loads the module, so the rest of that explanation is still correct.

-This is the single source of truth. ``cuda_core/_build_shared.py`` is a symlink
-to this file. Python does not dereference symlinks in ``__file__``, so any
-``Path(__file__)``-relative location in here resolves under whichever package
-loads it.
+``cuda_bindings/_build_shared.py`` and ``cuda_core/_build_shared.py`` are
+identical copies, kept in sync by the ``check-build-shared-sync`` pre-commit
+hook. Any ``Path(__file__)``-relative location in here resolves under
+whichever package loads it.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

``cuda_bindings/_build_shared.py`` and ``cuda_core/_build_shared.py`` are
identical copies, kept in sync by the ``check-build-shared-sync`` pre-commit
hook. Any ``Path(__file__)``-relative location in here resolves under
whichever package loads it.

---

54-62: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

suggestion: The fallback path crashes when the cuda package itself cannot be imported. In that case, Line 57 sets cuda = None. If the loop then finds a pathfinder directory, Line 62 runs None.__path__ and raises AttributeError instead of the intended error. Handle the cuda is None case on its own. For example, raise the ModuleNotFoundError with the explanation, or add sp_cuda's parent to sys.path and import again. Apply the same fix to both copies.

[github-actions]

Doc Preview CI
Preview removed because the pull request was closed or merged.

[rwgk]

I'm approving: The regular-file rollback is a good short-term way to keep Windows and SWQA builds predictable while we revisit the longer-term symlink-versus-copy design.

Before merging, I suggest folding in changes similar to c756374, with this rationale in mind:

• It could be misleading (especially for agents) if helper comments, maintainer instructions, and installation docs still describe the core file as a symlink and make Windows symlink setup sound build-critical.
• Representation-neutral wording leaves an accurate breadcrumb whether we keep copies longer or return to a symlink.

Scope

• Marks cuda_bindings/_build_shared.py as canonical and the core path as either a symlink or a byte-for-byte identical copy.
• Clarifies that core.symlinks=false supports source builds and tests; the remaining links are documentation and metadata.
• Points the synchronization error toward copying the canonical bindings file to core.

Commit c756374 changes only documentation, comments, and that diagnostic.

[juenglin]

/ok to test 67ea7cf