diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 012126cc842..6abec7c2569 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,6 +19,10 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of - [Contributing to CUDA Python](#contributing-to-cuda-python) - [Table of Contents](#table-of-contents) + - [Cloning the repository](#cloning-the-repository) + - [Recommended clone](#recommended-clone) + - [Fixing an existing clone](#fixing-an-existing-clone) + - [Symptoms of a bad clone](#symptoms-of-a-bad-clone) - [Type stubs for cuda.core](#type-stubs-for-cudacore) - [Pre-commit](#pre-commit) - [Signing Your Work](#signing-your-work) @@ -34,6 +38,113 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of - [Code coverage](#code-coverage) +## Cloning the repository + +Every package in this repository derives its version from git tags using +[`setuptools-scm`](https://setuptools-scm.readthedocs.io/), so **how you clone +determines whether you can build at all, and whether the version you build is +correct.** Each package matches its own tag prefix: + +| Package | Tag pattern | +| --- | --- | +| `cuda-bindings`, `cuda-python` | `v*` (e.g. `v13.3.1`) | +| `cuda-core` | `cuda-core-v*` (e.g. `cuda-core-v1.1.0`) | +| `cuda-pathfinder` | `cuda-pathfinder-v*` (e.g. `cuda-pathfinder-v1.6.0`) | + +Each package sets `root = ".."` in its `[tool.setuptools_scm]` table, meaning the +version is read from the *repository root* rather than the package directory. A +working build therefore needs all of the following: + +1. **A real git clone.** Source zips and GitHub "Download ZIP" archives have no + git metadata and the build fails outright. (Tarballs produced by + `git archive` do work, thanks to the `.git_archival.txt` substitutions + configured in `.gitattributes`.) +2. **The full repository**, not just the package subdirectory, because the + version lookup walks up to the repository root. +3. **Tags, reaching back at least as far as the most recent tag** matching the + package you are building. `git describe` needs to find that tag; the history + between it and your checkout must be present too. + +Each package is tagged on its own cadence, so the distance from `main` back to +the relevant tag differs per package and grows as commits land between releases. +There is no `--depth` value that is safe for all four packages, and any value +that works today will silently stop working later. + +This makes a partial `--depth` actively dangerous, because it can succeed for one +package while quietly failing for the others. A `--depth 20` clone taken while +the nearest `cuda-pathfinder-v*` tag was 10 commits back gives: + +```text +cuda_pathfinder -> 1.6.1.dev10+g0d22cb4 # correct +cuda_core -> 0.1.dev20+g0d22cb444 # wrong, no error +cuda_bindings -> 0.1.dev20+g0d22cb444 # wrong, no error +``` + +### Recommended clone + +```console +$ git clone --filter=blob:none https://github.com/NVIDIA/cuda-python.git +``` + +This is a *treeless* clone: it fetches the complete commit graph and all tags +(which is what `setuptools-scm` needs) while skipping historical file contents +(which it does not). It is substantially faster than a plain clone and is +exactly what CI uses — see the `fetch-depth: 0` plus `filter: blob:none` +checkout settings in `.github/workflows/build-wheel.yml`. + +Do **not** use `--depth`, `--shallow-since`, or `--no-tags`. + +### Fixing an existing clone + +If you already have a shallow clone: + +```console +$ git fetch --unshallow --tags +``` + +If you are working from a personal fork, your fork's tags stop tracking upstream +the moment new releases are cut, which silently yields a stale version. Fetch +tags from upstream directly: + +```console +$ git remote add upstream https://github.com/NVIDIA/cuda-python.git +$ git fetch --tags upstream +``` + +Keep doing this periodically — a fork that was correct when you created it will +drift. + +### Symptoms of a bad clone + +Only case 3 below reports an error. The first two fail *silently*, producing a +wrong version that surfaces much later as a confusing dependency-resolution or +version-check failure: + +1. **No tags reachable.** The build succeeds and produces a version starting at + `0.1.dev`: a `--depth 1` clone yields `0.1.dev1+g0d22cb444`, a full clone made + with `--no-tags` yields `0.1.dev2114+g0d22cb444`. Installing `cuda-python` + built this way then fails, because its `install_requires` pins + `cuda-bindings` to that same bogus version. +2. **Stale tags** (a fork that has not fetched upstream in a while): you get a + plausible-looking but wrong version, e.g. `13.0.4.dev650+g0d22cb44` when the + real latest tag is `v13.3.1`. Nothing warns you. Note there is no leading + `v` — the tag prefix is stripped by `tag_regex`. +3. **No git metadata** (source zip): the build fails with + `LookupError: setuptools-scm was unable to detect version`. + +As a last resort — for example when building inside a container that has no git +history — you can bypass the lookup entirely: + +```console +$ SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CUDA_CORE=1.1.0 pip install ./cuda_core +``` + +The environment variable is suffixed with the distribution name, uppercased with +hyphens replaced by underscores: `..._FOR_CUDA_BINDINGS`, `..._FOR_CUDA_CORE`, +`..._FOR_CUDA_PATHFINDER`, `..._FOR_CUDA_PYTHON`. Use this only when you +genuinely cannot provide tags; it is not a substitute for a correct clone. + + ## Type stubs for cuda.core `cuda.core` is a PEP 561-compliant package: it ships a `py.typed` marker and diff --git a/cuda_bindings/docs/source/install.rst b/cuda_bindings/docs/source/install.rst index 7f890365ea3..1001e6e80cc 100644 --- a/cuda_bindings/docs/source/install.rst +++ b/cuda_bindings/docs/source/install.rst @@ -120,11 +120,14 @@ Requirements * CUDA Toolkit headers[^1] * CUDA Runtime static library[^2] +* A git clone of the repository that includes tags[^3] [^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. [^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. +[^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 --filter=blob:none 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 `_ for details and recovery steps. + 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: .. code-block:: console diff --git a/cuda_core/docs/source/install.rst b/cuda_core/docs/source/install.rst index a49aab7c966..c67e22f5bdc 100644 --- a/cuda_core/docs/source/install.rst +++ b/cuda_core/docs/source/install.rst @@ -110,7 +110,7 @@ Development with uv .. code-block:: console - $ git clone https://github.com/NVIDIA/cuda-python + $ git clone --filter=blob:none https://github.com/NVIDIA/cuda-python.git $ cd cuda-python/cuda_core $ uv venv $ source .venv/bin/activate # On Windows: .venv\Scripts\activate @@ -132,7 +132,7 @@ From the repository root: .. code-block:: console - $ git clone https://github.com/NVIDIA/cuda-python + $ git clone --filter=blob:none https://github.com/NVIDIA/cuda-python.git $ cd cuda-python $ pixi run -e cu13 test-core @@ -151,8 +151,18 @@ Installing from Source .. code-block:: console - $ git clone https://github.com/NVIDIA/cuda-python + $ git clone --filter=blob:none https://github.com/NVIDIA/cuda-python.git $ cd cuda-python/cuda_core $ pip install . ``cuda-bindings`` 12.x or 13.x is a required dependency. + +.. note:: + + The version is derived from git tags via ``setuptools-scm``, so the clone + must include tags reaching back to at least the latest ``cuda-core-v*`` tag. + Do not use ``--depth`` or ``--no-tags``: a shallow clone builds without + error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See + `Cloning the repository + `_ + for details and recovery steps. diff --git a/cuda_pathfinder/docs/source/install.rst b/cuda_pathfinder/docs/source/install.rst index abc8fbb9d50..2d677b85167 100644 --- a/cuda_pathfinder/docs/source/install.rst +++ b/cuda_pathfinder/docs/source/install.rst @@ -59,7 +59,7 @@ Installing from Source .. code-block:: console - $ git clone https://github.com/NVIDIA/cuda-python + $ git clone --filter=blob:none https://github.com/NVIDIA/cuda-python.git $ cd cuda-python/cuda_pathfinder $ pip install . @@ -68,3 +68,13 @@ For an editable install (e.g. when developing ``cuda.pathfinder`` itself): .. code-block:: console $ pip install -v -e . + +.. note:: + + The version is derived from git tags via ``setuptools-scm``, so the clone + must include tags reaching back to at least the latest ``cuda-pathfinder-v*`` + tag. Do not use ``--depth`` or ``--no-tags``: a shallow clone builds without + error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See + `Cloning the repository + `_ + for details and recovery steps.