Skip to content

Commit 0a67d90

Browse files
rluo8rluo8
authored
Merge branch 'main' into fix/pch-heap-retry-status
2 parents 1ae478b + 9292406 commit 0a67d90

6 files changed

Lines changed: 149 additions & 627 deletions

File tree

‎.pre-commit-config.yaml‎

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -85,16 +85,6 @@ repos:
8585
language: python
8686
files: '^cuda_core/tests/.*\.py$'
8787

88-
- id: check-build-shared-sync
89-
name: Check _build_shared.py copies are identical
90-
language: system
91-
pass_filenames: false
92-
files: '^(cuda_bindings|cuda_core)/_build_shared\.py$'
93-
entry: bash -c
94-
args:
95-
- 'git diff --no-index --exit-code -- cuda_bindings/_build_shared.py cuda_core/_build_shared.py || { echo "ERROR: cuda_bindings/_build_shared.py and cuda_core/_build_shared.py must be byte-identical. Copy one onto the other and commit both." >&2; exit 1; }'
96-
- "_" # fake script name, because bash considers $0 (the first argument) to be the script name
97-
9888
- id: no-markdown-in-docs-source
9989
name: Prevent markdown files in docs/source directories
10090
entry: bash -c

‎CONTRIBUTING.md‎

Lines changed: 71 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
2121
- [Table of Contents](#table-of-contents)
2222
- [Cloning the repository](#cloning-the-repository)
2323
- [Recommended clone](#recommended-clone)
24-
- [Fixing an existing clone](#fixing-an-existing-clone)
2524
- [Updating your clone](#updating-your-clone)
25+
- [Why the clone matters](#why-the-clone-matters)
2626
- [Symptoms of a bad clone](#symptoms-of-a-bad-clone)
2727
- [Development on Windows](#development-on-windows)
2828
- [Enabling git symlinks](#enabling-git-symlinks)
@@ -45,11 +45,56 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
4545

4646
## Cloning the repository
4747

48-
> **Windows contributors (not WSL):** source builds and tests work with
49-
> `core.symlinks=false`. Git symlink support is optional and only affects the
50-
> remaining documentation and metadata links (`CLAUDE.md`,
51-
> `cuda_python/README.md`, and `.git_archival.txt`). See
52-
> [Enabling git symlinks](#enabling-git-symlinks) if you want those links materialized.
48+
### Recommended clone
49+
50+
**On native Windows (not WSL), first [enable symlink creation](#enabling-git-symlinks),
51+
including the Developer Mode registry check.** Complete that setup before
52+
running the clone command.
53+
54+
From the directory where you want to create the checkout, run:
55+
56+
```console
57+
$ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules https://github.com/NVIDIA/cuda-python.git
58+
$ cd cuda-python
59+
```
60+
61+
This recipe sets up the repository for source builds and development:
62+
63+
- `core.symlinks=true` materializes symlinks during checkout, including the
64+
build-critical `cuda_core/_build_shared.py`.
65+
- `--recurse-submodules` initializes the CCCL headers needed to build `cuda.core`.
66+
- `submodule.recurse=true` keeps initialized submodules in sync on `git pull`,
67+
`git checkout`, and `git switch`.
68+
- The clone retains history and release tags for correct package versions.
69+
Do not add `--depth` or `--no-tags`.
70+
71+
Both configuration settings are stored in the new clone. Next, follow the
72+
build and test instructions for
73+
[`cuda.core`](https://nvidia.github.io/cuda-python/cuda-core/latest/install.html),
74+
[`cuda.bindings`](https://nvidia.github.io/cuda-python/cuda-bindings/latest/install.html), or
75+
[`cuda.pathfinder`](https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/install.html).
76+
77+
### Updating your clone
78+
79+
From the repository root, run:
80+
81+
```console
82+
$ git pull --recurse-submodules
83+
$ git submodule update --init
84+
```
85+
86+
The recommended clone configures `submodule.recurse=true`, so you can omit
87+
`--recurse-submodules` from `git pull`. The second command initializes any
88+
newly added submodules; it is usually a no-op.
89+
90+
If you work from a fork, periodically fetch release tags from NVIDIA upstream
91+
so package versions stay current:
92+
93+
```console
94+
$ git fetch --tags https://github.com/NVIDIA/cuda-python.git
95+
```
96+
97+
### Why the clone matters
5398

5499
Every package in this repository derives its version from git tags using
55100
[`setuptools-scm`](https://setuptools-scm.readthedocs.io/), so **how you clone
@@ -79,59 +124,6 @@ working build therefore needs all of the following:
79124
4. **The CCCL submodule** when building `cuda.core`. That package compiles
80125
against the headers pinned in `cuda_core/third_party/cccl`.
81126

82-
### Recommended clone
83-
84-
Clone the repository with its submodules:
85-
86-
```console
87-
$ git clone --recurse-submodules https://github.com/NVIDIA/cuda-python.git
88-
```
89-
90-
To keep initialized submodules in sync on `git pull`, `git checkout`, and
91-
`git switch`, set this default once per clone:
92-
93-
```console
94-
$ git config --local submodule.recurse true
95-
```
96-
97-
### Fixing an existing clone
98-
99-
If you already have a shallow clone:
100-
101-
```console
102-
$ git fetch --unshallow --tags
103-
```
104-
105-
If you cloned without submodules:
106-
107-
```console
108-
$ git submodule update --init cuda_core/third_party/cccl
109-
```
110-
111-
If you are working from a personal fork, your fork's tags stop tracking upstream
112-
the moment new releases are cut, which silently yields a stale version. Fetch
113-
tags from upstream directly:
114-
115-
```console
116-
$ git remote add upstream https://github.com/NVIDIA/cuda-python.git
117-
$ git fetch --tags upstream
118-
```
119-
120-
Keep doing this periodically — a fork that was correct when you created it will
121-
drift.
122-
123-
### Updating your clone
124-
125-
To update your clone and initialize any newly added submodules, run:
126-
127-
```console
128-
$ git pull --recurse-submodules && git submodule update --init
129-
```
130-
131-
You can omit `--recurse-submodules` if you have already run
132-
`git config --local submodule.recurse true`. The second command is usually a
133-
no-op, but ensures that newly added submodules are initialized.
134-
135127
### Symptoms of a bad clone
136128

137129
Only case 3 below reports an error. The first two fail *silently*, producing a
@@ -171,38 +163,34 @@ document.
171163

172164
### Enabling git symlinks
173165

174-
The repository still contains documentation and metadata symlinks, including
166+
The repository contains documentation and metadata symlinks, including
175167
`CLAUDE.md`, `cuda_python/README.md`, and the per-package `.git_archival.txt`
176-
files. With `core.symlinks=false`, Git checks them out as plain text files
177-
containing the target path. This does not affect source builds or tests.
178-
179-
If you want these links materialized as symlinks:
180-
181-
1. **[Activate Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development#activate-developer-mode)**
182-
so Git can create symlinks without Administrator privileges.
168+
files. It also currently tracks the build-critical
169+
`cuda_core/_build_shared.py` as a symlink to the canonical
170+
`cuda_bindings/_build_shared.py`. The core path may instead be maintained as a
171+
byte-for-byte identical copy, but the current tree uses a symlink. With
172+
`core.symlinks=false`, Git checks it out as a plain text file containing the
173+
target path, and `cuda-core` source builds and tests fail.
183174

184-
2. **Enable Git symlink support globally** so newly-cloned repositories inherit
185-
the setting:
175+
[Activate Developer Mode](https://learn.microsoft.com/en-us/windows/advanced-settings/developer-mode)
176+
so Git can create symlinks without Administrator privileges. Then verify
177+
that Windows recorded Developer Mode in the machine-wide registry:
186178

187-
```console
188-
$ git config --global core.symlinks true
189-
```
190-
191-
Then clone as usual (see [Cloning the repository](#cloning-the-repository)).
179+
```console
180+
$ reg.exe query "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /v AllowDevelopmentWithoutDevLicense
181+
```
192182

193-
If you already cloned with `core.symlinks=false`, the repository-local
194-
setting overrides the global setting. Enable it locally, then rematerialize
195-
all tracked symlinks. For example:
183+
The output must show `AllowDevelopmentWithoutDevLicense` as a `REG_DWORD`
184+
with value `0x1`. If the value is missing or differs, Git may report
185+
`unable to create symlink ...: Permission denied` even when Windows Settings
186+
shows Developer Mode as enabled. In that case, run the following command
187+
once from an Administrator shell:
196188

197189
```console
198-
$ git config core.symlinks true
199-
$ git rm --cached cuda_python/README.md
200-
$ git checkout HEAD -- cuda_python/README.md
190+
$ reg.exe add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /v AllowDevelopmentWithoutDevLicense /t REG_DWORD /d 1 /f
201191
```
202192

203-
Repeat the last two commands for every other tracked symlink. Re-cloning after
204-
enabling Developer Mode and setting the global option is simpler if you want
205-
all links restored.
193+
Then return to [Recommended clone](#recommended-clone).
206194

207195
### Pre-commit lychee workaround
208196

‎cuda_bindings/docs/source/install.rst‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,12 @@ published from the corresponding backport branch.
115115
Installing from Source
116116
~~~~~~~~~~~~~~~~~~~~~~
117117

118+
First clone the repository using `Recommended clone
119+
<https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md#recommended-clone>`_.
120+
On native Windows outside WSL, complete its Windows setup before cloning.
121+
The recipe preserves release tags and configures symlinks and submodule
122+
updates for development.
123+
118124
Requirements
119125
^^^^^^^^^^^^
120126

@@ -126,7 +132,12 @@ Requirements
126132

127133
[^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.
128134

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.
135+
[^3]: The version is derived from git tags via ``setuptools-scm``, so the clone
136+
must include tags reaching back to at least the latest ``v*`` tag. Do not use
137+
``--depth`` or ``--no-tags``: a clone without reachable tags can build with a
138+
bogus version such as ``0.1.dev1+g0d22cb444``. See `Cloning the repository
139+
<https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md#cloning-the-repository>`_
140+
for details.
130141

131142
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:
132143

@@ -143,10 +154,11 @@ See :doc:`Environment Variables <environment_variables>` for a description of ot
143154
Editable Install
144155
^^^^^^^^^^^^^^^^
145156

146-
You can use:
157+
From the repository root, run:
147158

148159
.. code-block:: console
149160
161+
$ cd cuda_bindings
150162
$ pip install -v -e .
151163
152-
to install the module as editable in your current Python environment (e.g. for testing of porting other libraries to use the binding).
164+
This installs the module as editable in your current Python environment (e.g. for testing or porting other libraries to use the bindings).

0 commit comments

Comments
 (0)