Skip to content

Commit 67ea7cf

Browse files
rwgkjuenglin
rwgk
authored and
juenglin
committed
docs: clarify shared build helper representations
1 parent 18ecce0 commit 67ea7cf

11 files changed

Lines changed: 51 additions & 57 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 21 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,11 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
4444

4545
## Cloning the repository
4646

47-
> **Windows contributors (not WSL):** configure Git for symlinks *before*
48-
> cloning, or tracked symlinks (`CLAUDE.md`, `cuda_python/README.md`,
49-
> `.git_archival.txt`) land as text stubs. See
50-
> [Enabling git symlinks](#enabling-git-symlinks) under Development on Windows.
47+
> **Windows contributors (not WSL):** source builds and tests work with
48+
> `core.symlinks=false`. Git symlink support is optional and only affects the
49+
> remaining documentation and metadata links (`CLAUDE.md`,
50+
> `cuda_python/README.md`, and `.git_archival.txt`). See
51+
> [Enabling git symlinks](#enabling-git-symlinks) if you want those links materialized.
5152
5253
Every package in this repository derives its version from git tags using
5354
[`setuptools-scm`](https://setuptools-scm.readthedocs.io/), so **how you clone
@@ -137,17 +138,18 @@ genuinely cannot provide tags; it is not a substitute for a correct clone.
137138

138139
## Development on Windows
139140

140-
This section collects the Windows-specific setup a contributor needs when
141-
working outside of WSL. WSL contributors can follow the Linux flow in the rest
142-
of this document.
141+
This section collects Windows-specific guidance for contributors working
142+
outside of WSL. WSL contributors can follow the Linux flow in the rest of this
143+
document.
143144

144145
### Enabling git symlinks
145146

146-
Some files in this repository are Git symlinks, including `CLAUDE.md`,
147-
`cuda_python/README.md`, and the per-package `.git_archival.txt` files. Git
148-
materializes symlinks by default on Linux and macOS, but on Windows it needs
149-
to be configured before cloning, otherwise the "symlinks" land in your working
150-
tree as plain text files that contain the target path.
147+
The repository still contains documentation and metadata symlinks, including
148+
`CLAUDE.md`, `cuda_python/README.md`, and the per-package `.git_archival.txt`
149+
files. With `core.symlinks=false`, Git checks them out as plain text files
150+
containing the target path. This does not affect source builds or tests.
151+
152+
If you want these links materialized as symlinks:
151153

152154
1. **[Activate Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development#activate-developer-mode)**
153155
so Git can create symlinks without Administrator privileges.
@@ -161,22 +163,19 @@ tree as plain text files that contain the target path.
161163

162164
Then clone as usual (see [Cloning the repository](#cloning-the-repository)).
163165

164-
If you already cloned without these settings, note that `git clone` probes
165-
symlink support at clone time and writes `core.symlinks=false` into the
166-
repo-local config when the probe fails. Repo-local config overrides
167-
`--global`, so you must clear it *inside the existing clone* — the global
168-
setting alone won't take effect:
166+
If you already cloned with `core.symlinks=false`, the repository-local
167+
setting overrides the global setting. Enable it locally, then rematerialize
168+
all tracked symlinks. For example:
169169

170170
```console
171-
$ git config core.symlinks true # no --global — clears the repo-local override
171+
$ git config core.symlinks true
172172
$ git rm --cached cuda_python/README.md
173173
$ git checkout HEAD -- cuda_python/README.md
174174
```
175175

176-
In practice, deleting the checkout and re-cloning after the two steps at
177-
the top of this section (Developer Mode + `git config --global core.symlinks
178-
true`) is usually simpler and less error-prone than repairing an existing
179-
clone in place.
176+
Repeat the last two commands for every other tracked symlink. Re-cloning after
177+
enabling Developer Mode and setting the global option is simpler if you want
178+
all links restored.
180179

181180
### Pre-commit lychee workaround
182181

‎cuda_bindings/AGENTS.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,9 @@ subpackage in the `cuda-python` monorepo.
2121
- **Build backend**: `build_hooks.py` drives extension configuration and
2222
Cythonization. Logic shared with `cuda_core` (toolchain selection, the
2323
compiler flag set, the Cython cache helpers and the rebuild stamps) lives
24-
in `_build_shared.py`; `cuda_core/_build_shared.py` is a symlink to this
25-
file, so an edit here changes both packages.
24+
in `_build_shared.py`. `cuda_bindings/_build_shared.py` is canonical;
25+
`cuda_core/_build_shared.py` must be either a symlink to it or a byte-for-byte
26+
identical copy.
2627

2728
## Generated-source workflow
2829

‎cuda_bindings/MANIFEST.in‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,5 @@ recursive-include cuda/ *.pyx *.pxd *.pxi *.pyx.in *.pxd.in *.pxi.in *.h
66
# to the payload, causing file copying to the build environment failed
77
exclude cuda/bindings cuda?bindings
88
exclude cuda/bindings/_bindings cuda?bindings?_bindings
9-
# canonical shared PEP 517 helper (cuda_core/_build_shared.py symlinks to the cuda_bindings copy)
9+
# package-local shared PEP 517 helper
1010
include _build_shared.py

‎cuda_bindings/_build_shared.py‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@
33

44
"""Build helpers shared by the cuda-bindings and cuda-core PEP 517 backends.
55
6-
This is the single source of truth. ``cuda_core/_build_shared.py`` is a symlink
7-
to this file. Python does not dereference symlinks in ``__file__``, so any
8-
``Path(__file__)``-relative location in here resolves under whichever package
9-
loads it.
6+
``cuda_bindings/_build_shared.py`` is canonical. ``cuda_core/_build_shared.py``
7+
is either a symlink to it or a byte-for-byte identical copy. Both backends load
8+
the helper through their package-local path, keeping ``Path(__file__)``-relative
9+
state package-local.
1010
1111
PEP 517 build isolation gives each backend its own ``build_hooks.py`` but not a
1212
shared import path. Both packages declare ``backend-path = ["."]``, which puts
@@ -385,9 +385,8 @@ def _stable_cython_alias(target: Path, alias: Path):
385385
unstable across runs. This context manager creates a fixed, worktree-
386386
relative symlink so Cython sees a stable lexical path.
387387
388-
The symlink is created in the *package directory* (the directory containing
389-
this file, which is the package's own copy through the symlink), not in
390-
the cwd, to keep aliases package-local and avoid cross-package races.
388+
The symlink is created in the package directory containing this file, not
389+
in the cwd, to keep aliases package-local and avoid cross-package races.
391390
392391
alias must not already exist as a real file or directory; if it is a
393392
symlink (including a dangling one) it is atomically replaced.

‎cuda_bindings/docs/source/install.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ Requirements
126126

127127
[^2]: The CUDA Runtime static library (``libcudart_static.a`` on Linux, ``cudart_static.lib`` on Windows) is part of the CUDA Toolkit. If using conda packages, it is contained in the ``cuda-cudart-static`` package.
128128

129-
[^3]: The version is derived from git tags via ``setuptools-scm``, so the clone must include tags reaching back to at least the latest ``v*`` tag. Clone with ``git clone https://github.com/NVIDIA/cuda-python.git``; do not use ``--depth`` or ``--no-tags``, since a shallow clone builds without error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See `Cloning the repository <https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md>`_ for details and recovery steps. Windows contributors building outside of WSL should also see `Development on Windows <https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md#development-on-windows>`_ for the git-symlink configuration that must be set *before* cloning.
129+
[^3]: The version is derived from git tags via ``setuptools-scm``, so the clone must include tags reaching back to at least the latest ``v*`` tag. Clone with ``git clone https://github.com/NVIDIA/cuda-python.git``; do not use ``--depth`` or ``--no-tags``, since a shallow clone builds without error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See `Cloning the repository <https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md>`_ for details and recovery steps.
130130

131131
Source builds require that the provided CUDA headers are of the same major.minor version as the ``cuda.bindings`` you're trying to build. Despite this requirement, note that the minor version compatibility is still maintained. The build checks the header before it compiles anything. A mismatch stops the build with a message that names the ``cuda.h`` it found and the version this source tree needs. Use the ``CUDA_PATH`` (or ``CUDA_HOME``) environment variable to specify the location of your headers. If both are set, ``CUDA_PATH`` takes precedence. For example, if your headers are located in ``/usr/local/cuda/include``, then you should set ``CUDA_PATH`` with:
132132

‎cuda_core/AGENTS.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,9 @@ This file describes `cuda_core`, the high-level Pythonic CUDA subpackage in the
2525
- **Build backend**: `build_hooks.py` handles Cython extension setup and build
2626
dependency wiring. Logic shared with `cuda_bindings` (toolchain selection,
2727
the compiler flag set, the Cython cache helpers and the rebuild stamps)
28-
lives in `_build_shared.py`, a symlink to `cuda_bindings/_build_shared.py`; an edit through either path changes both
29-
packages.
28+
lives in `_build_shared.py`. `cuda_bindings/_build_shared.py` is canonical;
29+
`cuda_core/_build_shared.py` must be either a symlink to it or a byte-for-byte
30+
identical copy.
3031

3132
## Build and version coupling
3233

‎cuda_core/MANIFEST.in‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,5 @@ recursive-include cuda/core/_cpp *.cpp *.h *.hpp
77
recursive-include cuda/core/_include *.h *.hpp
88
include cuda/core/py.typed
99
include NOTICE
10-
# canonical shared PEP 517 helper (cuda_core/_build_shared.py symlinks to the cuda_bindings copy)
10+
# package-local shared PEP 517 helper
1111
include _build_shared.py

‎cuda_core/_build_shared.py‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@
33

44
"""Build helpers shared by the cuda-bindings and cuda-core PEP 517 backends.
55
6-
This is the single source of truth. ``cuda_core/_build_shared.py`` is a symlink
7-
to this file. Python does not dereference symlinks in ``__file__``, so any
8-
``Path(__file__)``-relative location in here resolves under whichever package
9-
loads it.
6+
``cuda_bindings/_build_shared.py`` is canonical. ``cuda_core/_build_shared.py``
7+
is either a symlink to it or a byte-for-byte identical copy. Both backends load
8+
the helper through their package-local path, keeping ``Path(__file__)``-relative
9+
state package-local.
1010
1111
PEP 517 build isolation gives each backend its own ``build_hooks.py`` but not a
1212
shared import path. Both packages declare ``backend-path = ["."]``, which puts
@@ -385,9 +385,8 @@ def _stable_cython_alias(target: Path, alias: Path):
385385
unstable across runs. This context manager creates a fixed, worktree-
386386
relative symlink so Cython sees a stable lexical path.
387387
388-
The symlink is created in the *package directory* (the directory containing
389-
this file, which is the package's own copy through the symlink), not in
390-
the cwd, to keep aliases package-local and avoid cross-package races.
388+
The symlink is created in the package directory containing this file, not
389+
in the cwd, to keep aliases package-local and avoid cross-package races.
391390
392391
alias must not already exist as a real file or directory; if it is a
393392
symlink (including a dangling one) it is atomically replaced.

‎cuda_core/docs/source/install.rst‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -178,8 +178,4 @@ A source build has two requirements. See :ref:`cuda-core-bindings-floor`.
178178
error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See
179179
`Cloning the repository
180180
<https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md>`_
181-
for details and recovery steps. Windows contributors building outside of
182-
WSL should also see
183-
`Development on Windows
184-
<https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md#development-on-windows>`_
185-
for the git-symlink configuration that must be set *before* cloning.
181+
for details and recovery steps.

‎cuda_python_test_helpers/cuda_python_test_helpers/build_shared.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,11 @@
33

44
"""Shared tests for the helpers in ``_build_shared.py``.
55
6-
The helpers live in ``cuda_bindings/_build_shared.py``, and
7-
``cuda_core/_build_shared.py`` is a symlink to that file, so their behavior is
8-
identical whichever backend loads them. The mixins here hold the tests of that
9-
shared behavior. Each package's ``tests/test_build_hooks.py`` mixes them in
10-
against the ``_build_shared`` module it loaded, by setting the class attribute
6+
Both backends load the same ``_build_shared.py`` implementation through
7+
package-local paths, so their behavior is identical. The mixins here hold the
8+
tests of that shared behavior. Each package's ``tests/test_build_hooks.py``
9+
mixes them in against the ``_build_shared`` module it loaded, by setting the
10+
class attribute
1111
``build_shared``.
1212
1313
Kept out of the mixins on purpose:

0 commit comments

Comments
 (0)