build: restore _build_shared.py symlink

.pre-commit-config.yaml

@@ -85,16 +85,6 @@ repos:
         language: python
         files: '^cuda_core/tests/.*\.py$'
 
-      - id: check-build-shared-sync
-        name: Check _build_shared.py copies are identical
-        language: system
-        pass_filenames: false
-        files: '^(cuda_bindings|cuda_core)/_build_shared\.py$'
-        entry: bash -c
-        args:
-          - '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; }'
-          - "_" # fake script name, because bash considers $0 (the first argument) to be the script name
-
       - id: no-markdown-in-docs-source
         name: Prevent markdown files in docs/source directories
         entry: bash -c

CONTRIBUTING.md

@@ -21,8 +21,8 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
   - [Table of Contents](#table-of-contents)
   - [Cloning the repository](#cloning-the-repository)
     - [Recommended clone](#recommended-clone)
-    - [Fixing an existing clone](#fixing-an-existing-clone)
     - [Updating your clone](#updating-your-clone)
+    - [Why the clone matters](#why-the-clone-matters)
     - [Symptoms of a bad clone](#symptoms-of-a-bad-clone)
   - [Development on Windows](#development-on-windows)
     - [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
 
 ## Cloning the repository
 
-> **Windows contributors (not WSL):** source builds and tests work with
-> `core.symlinks=false`. Git symlink support is optional and only affects the
-> remaining documentation and metadata links (`CLAUDE.md`,
-> `cuda_python/README.md`, and `.git_archival.txt`). See
-> [Enabling git symlinks](#enabling-git-symlinks) if you want those links materialized.
+### Recommended clone
+
+**On native Windows (not WSL), first [enable symlink creation](#enabling-git-symlinks),
+including the Developer Mode registry check.** Complete that setup before
+running the clone command.
+
+From the directory where you want to create the checkout, run:
+
+```console
+$ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules https://github.com/NVIDIA/cuda-python.git
+$ cd cuda-python
+```
+
+This recipe sets up the repository for source builds and development:
+
+- `core.symlinks=true` materializes symlinks during checkout, including the
+  build-critical `cuda_core/_build_shared.py`.
+- `--recurse-submodules` initializes the CCCL headers needed to build `cuda.core`.
+- `submodule.recurse=true` keeps initialized submodules in sync on `git pull`,
+  `git checkout`, and `git switch`.
+- The clone retains history and release tags for correct package versions.
+  Do not add `--depth` or `--no-tags`.
+
+Both configuration settings are stored in the new clone. Next, follow the
+build and test instructions for
+[`cuda.core`](https://nvidia.github.io/cuda-python/cuda-core/latest/install.html),
+[`cuda.bindings`](https://nvidia.github.io/cuda-python/cuda-bindings/latest/install.html), or
+[`cuda.pathfinder`](https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/install.html).
+
+### Updating your clone
+
+From the repository root, run:
+
+```console
+$ git pull --recurse-submodules
+$ git submodule update --init
+```
+
+The recommended clone configures `submodule.recurse=true`, so you can omit
+`--recurse-submodules` from `git pull`. The second command initializes any
+newly added submodules; it is usually a no-op.
+
+If you work from a fork, periodically fetch release tags from NVIDIA upstream
+so package versions stay current:
+
+```console
+$ git fetch --tags https://github.com/NVIDIA/cuda-python.git
+```
+
+### Why the clone matters
 
 Every package in this repository derives its version from git tags using
 [`setuptools-scm`](https://setuptools-scm.readthedocs.io/), so **how you clone
@@ -79,59 +124,6 @@ working build therefore needs all of the following:
 4. **The CCCL submodule** when building `cuda.core`. That package compiles
    against the headers pinned in `cuda_core/third_party/cccl`.
 
-### Recommended clone
-
-Clone the repository with its submodules:
-
-```console
-$ git clone --recurse-submodules https://github.com/NVIDIA/cuda-python.git
-```
-
-To keep initialized submodules in sync on `git pull`, `git checkout`, and
-`git switch`, set this default once per clone:
-
-```console
-$ git config --local submodule.recurse true
-```
-
-### Fixing an existing clone
-
-If you already have a shallow clone:
-
-```console
-$ git fetch --unshallow --tags
-```
-
-If you cloned without submodules:
-
-```console
-$ git submodule update --init cuda_core/third_party/cccl
-```
-
-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.
-
-### Updating your clone
-
-To update your clone and initialize any newly added submodules, run:
-
-```console
-$ git pull --recurse-submodules && git submodule update --init
-```
-
-You can omit `--recurse-submodules` if you have already run
-`git config --local submodule.recurse true`. The second command is usually a
-no-op, but ensures that newly added submodules are initialized.
-
 ### Symptoms of a bad clone
 
 Only case 3 below reports an error. The first two fail *silently*, producing a
@@ -171,38 +163,34 @@ document.
 
 ### Enabling git symlinks
 
-The repository still contains documentation and metadata symlinks, including
+The repository contains documentation and metadata symlinks, including
 `CLAUDE.md`, `cuda_python/README.md`, and the per-package `.git_archival.txt`
-files. With `core.symlinks=false`, Git checks them out as plain text files
-containing the target path. This does not affect source builds or tests.
-
-If you want these links materialized as symlinks:
-
-1. **[Activate Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development#activate-developer-mode)**
-   so Git can create symlinks without Administrator privileges.
+files. It also currently tracks the build-critical
+`cuda_core/_build_shared.py` as a symlink to the canonical
+`cuda_bindings/_build_shared.py`. The core path may instead be maintained as a
+byte-for-byte identical copy, but the current tree uses a symlink. With
+`core.symlinks=false`, Git checks it out as a plain text file containing the
+target path, and `cuda-core` source builds and tests fail.
 
-2. **Enable Git symlink support globally** so newly-cloned repositories inherit
-   the setting:
+[Activate Developer Mode](https://learn.microsoft.com/en-us/windows/advanced-settings/developer-mode)
+so Git can create symlinks without Administrator privileges. Then verify
+that Windows recorded Developer Mode in the machine-wide registry:
 
-   ```console
-   $ git config --global core.symlinks true
-   ```
-
-Then clone as usual (see [Cloning the repository](#cloning-the-repository)).
+```console
+$ reg.exe query "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /v AllowDevelopmentWithoutDevLicense
+```
 
-If you already cloned with `core.symlinks=false`, the repository-local
-setting overrides the global setting. Enable it locally, then rematerialize
-all tracked symlinks. For example:
+The output must show `AllowDevelopmentWithoutDevLicense` as a `REG_DWORD`
+with value `0x1`. If the value is missing or differs, Git may report
+`unable to create symlink ...: Permission denied` even when Windows Settings
+shows Developer Mode as enabled. In that case, run the following command
+once from an Administrator shell:
 
 ```console
-$ git config core.symlinks true
-$ git rm --cached cuda_python/README.md
-$ git checkout HEAD -- cuda_python/README.md
+$ reg.exe add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /v AllowDevelopmentWithoutDevLicense /t REG_DWORD /d 1 /f
 ```
 
-Repeat the last two commands for every other tracked symlink. Re-cloning after
-enabling Developer Mode and setting the global option is simpler if you want
-all links restored.
+Then return to [Recommended clone](#recommended-clone).
 
 ### Pre-commit lychee workaround
 

cuda_bindings/docs/source/install.rst

@@ -115,6 +115,12 @@ published from the corresponding backport branch.
 Installing from Source
 ~~~~~~~~~~~~~~~~~~~~~~
 
+First clone the repository using `Recommended clone
+<https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md#recommended-clone>`_.
+On native Windows outside WSL, complete its Windows setup before cloning.
+The recipe preserves release tags and configures symlinks and submodule
+updates for development.
+
 Requirements
 ^^^^^^^^^^^^
 
@@ -126,7 +132,12 @@ Requirements
 
 [^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 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.
+[^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. Do not use
+``--depth`` or ``--no-tags``: a clone without reachable tags can build with a
+bogus version such as ``0.1.dev1+g0d22cb444``. See `Cloning the repository
+<https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md#cloning-the-repository>`_
+for details.
 
 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:
 
@@ -143,10 +154,11 @@ See :doc:`Environment Variables <environment_variables>` for a description of ot
 Editable Install
 ^^^^^^^^^^^^^^^^
 
-You can use:
+From the repository root, run:
 
 .. code-block:: console
 
+   $ cd cuda_bindings
    $ pip install -v -e .
 
-to install the module as editable in your current Python environment (e.g. for testing of porting other libraries to use the binding).
+This installs the module as editable in your current Python environment (e.g. for testing or porting other libraries to use the bindings).