Skip to content

Commit ca14583

Browse files
bharatr21bharatr21
authored
[doc-only] docs: document setuptools-scm clone requirements for source builds (#2424)
* docs: document setuptools-scm clone requirements for source builds Signed-off-by: Bharat Raghunathan <bharatrgatech@gmail.com> * Applied review suggestions from @mdboom Signed-off-by: Bharat Raghunathan <bharatrgatech@gmail.com> --------- Signed-off-by: Bharat Raghunathan <bharatrgatech@gmail.com>
1 parent 2a62ae8 commit ca14583

4 files changed

Lines changed: 119 additions & 4 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,10 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
1919

2020
- [Contributing to CUDA Python](#contributing-to-cuda-python)
2121
- [Table of Contents](#table-of-contents)
22+
- [Cloning the repository](#cloning-the-repository)
23+
- [Recommended clone](#recommended-clone)
24+
- [Fixing an existing clone](#fixing-an-existing-clone)
25+
- [Symptoms of a bad clone](#symptoms-of-a-bad-clone)
2226
- [Type stubs for cuda.core](#type-stubs-for-cudacore)
2327
- [Pre-commit](#pre-commit)
2428
- [Signing Your Work](#signing-your-work)
@@ -34,6 +38,94 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
3438
- [Code coverage](#code-coverage)
3539

3640

41+
## Cloning the repository
42+
43+
Every package in this repository derives its version from git tags using
44+
[`setuptools-scm`](https://setuptools-scm.readthedocs.io/), so **how you clone
45+
determines whether you can build at all, and whether the version you build is
46+
correct.** Each package matches its own tag prefix:
47+
48+
| Package | Tag pattern |
49+
| --- | --- |
50+
| `cuda-bindings`, `cuda-python` | `v*` (e.g. `v13.3.1`) |
51+
| `cuda-core` | `cuda-core-v*` (e.g. `cuda-core-v1.1.0`) |
52+
| `cuda-pathfinder` | `cuda-pathfinder-v*` (e.g. `cuda-pathfinder-v1.6.0`) |
53+
54+
Each package sets `root = ".."` in its `[tool.setuptools_scm]` table, meaning the
55+
version is read from the *repository root* rather than the package directory. A
56+
working build therefore needs all of the following:
57+
58+
1. **A real git clone.** Source zips and GitHub "Download ZIP" archives have no
59+
git metadata and the build fails outright. (Tarballs produced by
60+
`git archive` do work, thanks to the `.git_archival.txt` substitutions
61+
configured in `.gitattributes`.)
62+
2. **The full repository**, not just the package subdirectory, because the
63+
version lookup walks up to the repository root.
64+
3. **Tags, reaching back at least as far as the most recent tag** matching the
65+
package you are building. `git describe` needs to find that tag; the history
66+
between it and your checkout must be present too.
67+
68+
### Recommended clone
69+
70+
The default `git clone` gives you everything you need:
71+
72+
```console
73+
$ git clone https://github.com/NVIDIA/cuda-python.git
74+
```
75+
76+
77+
78+
### Fixing an existing clone
79+
80+
If you already have a shallow clone:
81+
82+
```console
83+
$ git fetch --unshallow --tags
84+
```
85+
86+
If you are working from a personal fork, your fork's tags stop tracking upstream
87+
the moment new releases are cut, which silently yields a stale version. Fetch
88+
tags from upstream directly:
89+
90+
```console
91+
$ git remote add upstream https://github.com/NVIDIA/cuda-python.git
92+
$ git fetch --tags upstream
93+
```
94+
95+
Keep doing this periodically — a fork that was correct when you created it will
96+
drift.
97+
98+
### Symptoms of a bad clone
99+
100+
Only case 3 below reports an error. The first two fail *silently*, producing a
101+
wrong version that surfaces much later as a confusing dependency-resolution or
102+
version-check failure:
103+
104+
1. **No tags reachable.** The build succeeds and produces a version starting at
105+
`0.1.dev`: a `--depth 1` clone yields `0.1.dev1+g0d22cb444`, a full clone made
106+
with `--no-tags` yields `0.1.dev2114+g0d22cb444`. Installing `cuda-python`
107+
built this way then fails, because its `install_requires` pins
108+
`cuda-bindings` to that same bogus version.
109+
2. **Stale tags** (a fork that has not fetched upstream in a while): you get a
110+
plausible-looking but wrong version, e.g. `13.0.4.dev650+g0d22cb44` when the
111+
real latest tag is `v13.3.1`. Nothing warns you. Note there is no leading
112+
`v` — the tag prefix is stripped by `tag_regex`.
113+
3. **No git metadata** (source zip): the build fails with
114+
`LookupError: setuptools-scm was unable to detect version`.
115+
116+
As a last resort — for example when building inside a container that has no git
117+
history — you can bypass the lookup entirely:
118+
119+
```console
120+
$ SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CUDA_CORE=1.1.0 pip install ./cuda_core
121+
```
122+
123+
The environment variable is suffixed with the distribution name, uppercased with
124+
hyphens replaced by underscores: `..._FOR_CUDA_BINDINGS`, `..._FOR_CUDA_CORE`,
125+
`..._FOR_CUDA_PATHFINDER`, `..._FOR_CUDA_PYTHON`. Use this only when you
126+
genuinely cannot provide tags; it is not a substitute for a correct clone.
127+
128+
37129
## Type stubs for cuda.core
38130

39131
`cuda.core` is a PEP 561-compliant package: it ships a `py.typed` marker and

‎cuda_bindings/docs/source/install.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,11 +120,14 @@ Requirements
120120

121121
* CUDA Toolkit headers[^1]
122122
* CUDA Runtime static library[^2]
123+
* A git clone of the repository that includes tags[^3]
123124

124125
[^1]: User projects that ``cimport`` CUDA symbols in Cython must also use CUDA Toolkit (CTK) types as provided by the ``cuda.bindings`` major.minor version. This results in CTK headers becoming a transitive dependency of downstream projects through CUDA Python.
125126

126127
[^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.
127128

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.
130+
128131
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. 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:
129132

130133
.. code-block:: console

‎cuda_core/docs/source/install.rst‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ Development with uv
110110

111111
.. code-block:: console
112112
113-
$ git clone https://github.com/NVIDIA/cuda-python
113+
$ git clone https://github.com/NVIDIA/cuda-python.git
114114
$ cd cuda-python/cuda_core
115115
$ uv venv
116116
$ source .venv/bin/activate # On Windows: .venv\Scripts\activate
@@ -132,7 +132,7 @@ From the repository root:
132132

133133
.. code-block:: console
134134
135-
$ git clone https://github.com/NVIDIA/cuda-python
135+
$ git clone https://github.com/NVIDIA/cuda-python.git
136136
$ cd cuda-python
137137
$ pixi run -e cu13 test-core
138138
@@ -151,8 +151,18 @@ Installing from Source
151151

152152
.. code-block:: console
153153
154-
$ git clone https://github.com/NVIDIA/cuda-python
154+
$ git clone https://github.com/NVIDIA/cuda-python.git
155155
$ cd cuda-python/cuda_core
156156
$ pip install .
157157
158158
``cuda-bindings`` 12.x or 13.x is a required dependency.
159+
160+
.. note::
161+
162+
The version is derived from git tags via ``setuptools-scm``, so the clone
163+
must include tags reaching back to at least the latest ``cuda-core-v*`` tag.
164+
Do not use ``--depth`` or ``--no-tags``: a shallow clone builds without
165+
error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See
166+
`Cloning the repository
167+
<https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md>`_
168+
for details and recovery steps.

‎cuda_pathfinder/docs/source/install.rst‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ Installing from Source
5959

6060
.. code-block:: console
6161
62-
$ git clone https://github.com/NVIDIA/cuda-python
62+
$ git clone https://github.com/NVIDIA/cuda-python.git
6363
$ cd cuda-python/cuda_pathfinder
6464
$ pip install .
6565
@@ -68,3 +68,13 @@ For an editable install (e.g. when developing ``cuda.pathfinder`` itself):
6868
.. code-block:: console
6969
7070
$ pip install -v -e .
71+
72+
.. note::
73+
74+
The version is derived from git tags via ``setuptools-scm``, so the clone
75+
must include tags reaching back to at least the latest ``cuda-pathfinder-v*``
76+
tag. Do not use ``--depth`` or ``--no-tags``: a shallow clone builds without
77+
error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See
78+
`Cloning the repository
79+
<https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md>`_
80+
for details and recovery steps.

0 commit comments

Comments
 (0)