build: require symlinks on Windows; move lychee excludes to lychee.toml

.github/workflows/build-docs.yml

@@ -309,10 +309,6 @@ jobs:
         if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
         uses: lycheeverse/lychee-action@6da1d14f3a43098a294b7696d93d938aa8d20fc0  # unreleased: supports v0.24.x archive layout
         with:
-          # PR-preview canonical URLs are checked by the preview deployment workflow.
-          # The cuda-bindings #id links are docutils "problematic" anchors from generated API docs.
-          # TODO: Remove this exclusion after cybind stops emitting those problematic anchors.
-          # Preferred Networks rejects hosted-runner GETs, but the URL is browser reachable.
           args: >-
             --files-from ${{ github.workspace }}/lychee-rendered-html-files.txt
             --include-fragments=full
@@ -325,9 +321,7 @@ jobs:
             --retry-wait-time 5
             --timeout 30
             --no-progress
-            --exclude '^https://nvidia\.github\.io/cuda-python/pr-preview/pr-[0-9]+/'
-            --exclude '^file://.*/cuda-bindings/latest/module/(driver|runtime)\.html#id[0-9]+$'
-            --exclude '^https://www\.preferred\.jp/en/?$'
+            --config ${{ github.workspace }}/lychee.toml
           fail: true
           failIfEmpty: true
           format: markdown

.github/workflows/build-wheel.yml

@@ -67,6 +67,10 @@ jobs:
                  (inputs.host-platform == 'win-64' && 'windows-2022') ||
                  (inputs.host-platform == 'win-arm64' && 'windows-11-arm') }}
     steps:
+      - name: Enable Git symlinks (Windows, must precede checkout)
+        if: ${{ startsWith(inputs.host-platform, 'win') }}
+        run: git config --global core.symlinks true
+
       - name: Checkout ${{ github.event.repository.name }}
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:

.github/workflows/test-sdist-windows.yml

@@ -43,6 +43,9 @@ jobs:
     timeout-minutes: 60
     runs-on: windows-2022
     steps:
+      - name: Enable Git symlinks (Windows, must precede checkout)
+        run: git config --global core.symlinks true
+
       - name: Checkout ${{ github.event.repository.name }}
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:

.github/workflows/test-wheel-windows.yml

@@ -105,6 +105,9 @@ jobs:
     continue-on-error: ${{ startsWith(matrix.PY_VER, '3.15') }}
     runs-on: "windows-${{ matrix.ARCH }}-gpu-${{ matrix.GPU }}-${{ matrix.RUNNER_DRIVER }}-${{ matrix.GPU_COUNT }}"
     steps:
+      - name: Enable Git symlinks (Windows, must precede checkout)
+        run: git config --global core.symlinks true
+
       - name: Checkout ${{ github.event.repository.name }}
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:

CONTRIBUTING.md

@@ -23,9 +23,11 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
     - [Recommended clone](#recommended-clone)
     - [Fixing an existing clone](#fixing-an-existing-clone)
     - [Symptoms of a bad clone](#symptoms-of-a-bad-clone)
+  - [Development on Windows](#development-on-windows)
+    - [Enabling git symlinks](#enabling-git-symlinks)
+    - [Pre-commit lychee workaround](#pre-commit-lychee-workaround)
   - [Type stubs for cuda.core](#type-stubs-for-cudacore)
   - [Pre-commit](#pre-commit)
-    - [Pre-commit on Windows](#pre-commit-on-windows)
   - [Pixi lockfiles](#pixi-lockfiles)
   - [Signing Your Work](#signing-your-work)
   - [Code signing](#code-signing)
@@ -42,6 +44,11 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
 
 ## Cloning the repository
 
+> **Windows contributors (not WSL):** configure Git for symlinks *before*
+> cloning, or the shared PEP 517 build-hook file lands as a text stub instead
+> of a working symlink. See [Enabling git symlinks](#enabling-git-symlinks)
+> under Development on Windows.
+
 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
@@ -128,6 +135,63 @@ hyphens replaced by underscores: `..._FOR_CUDA_BINDINGS`, `..._FOR_CUDA_CORE`,
 genuinely cannot provide tags; it is not a substitute for a correct clone.
 
 
+## Development on Windows
+
+This section collects the Windows-specific setup a contributor needs when
+working outside of WSL. WSL contributors can follow the Linux flow in the rest
+of this document.
+
+### Enabling git symlinks
+
+The `cuda_core` PEP 517 backend shares source-of-truth helper files with
+`cuda_bindings` via symbolic links. Git materializes symlinks by default on
+Linux and macOS, but on Windows it needs to be configured before cloning,
+otherwise the "symlinks" land in your working tree as plain text files that
+contain the target path — enough to look right in `git status`, but not enough
+to actually build.
+
+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.
+
+2. **Enable Git symlink support globally** so newly-cloned repositories inherit
+   the setting:
+
+   ```console
+   $ git config --global core.symlinks true
+   ```
+
+Then clone as usual (see [Cloning the repository](#cloning-the-repository)).
+
+If you already cloned without these settings, note that `git clone` probes
+symlink support at clone time and writes `core.symlinks=false` into the
+repo-local config when the probe fails. Repo-local config overrides
+`--global`, so you must clear it *inside the existing clone* — the global
+setting alone won't take effect:
+
+```console
+$ git config core.symlinks true          # no --global — clears the repo-local override
+$ git rm --cached cuda_core/_build_shared.py
+$ git checkout HEAD -- cuda_core/_build_shared.py
+```
+
+In practice, deleting the checkout and re-cloning after the two steps at
+the top of this section (Developer Mode + `git config --global core.symlinks
+true`) is usually simpler and less error-prone than repairing an existing
+clone in place.
+
+### Pre-commit lychee workaround
+
+For development on Windows (not WSL), the `lychee` pre-commit task will not
+work when running `pre-commit run --all-files`. This problem does not occur
+if you install the pre-commit hook and run it automatically as part of your
+`git commit` workflow. To resolve this, you can either:
+
+1. Run `pre-commit` in Git Bash, rather than directly in PowerShell or cmd
+
+2. Skip it by setting the environment variable `SKIP` to `lychee`. This would
+   be `$env:SKIP = "lychee"` in PowerShell or `set SKIP=lychee` in cmd.
+
+
 ## Type stubs for cuda.core
 
 `cuda.core` is a PEP 561-compliant package: it ships a `py.typed` marker and
@@ -168,17 +232,7 @@ between commits, leaving stale headers or out-of-date stubs in the history.
 If the hook isn't installed, `pre-commit run` (and CI) will print a visible
 warning reminding you to run `pre-commit install`.
 
-### Pre-commit on Windows
-
-For development on Windows (not WSL), the `lychee` pre-commit task will not work
-when running `pre-commit run --all-files`.  This problem does not occur if you
-install the pre-commit hook and run it automatically as part of your `git
-commit` workflow.  To resolve this, you can either:
-
-1. Run `pre-commit` in Git Bash, rather than directly in PowerShell or cmd
-
-2. Skip it by setting the environment variable `SKIP` to `lychee`.  This would
-   be `$env:SKIP = "lychee"` in PowerShell or `set SKIP=lychee` in cmd.
+Windows contributors: see [Pre-commit lychee workaround](#pre-commit-lychee-workaround) under Development on Windows.
 
 ## Pixi lockfiles
 

lychee.toml

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Configuration for lychee, the doc link-checker invoked from
+# .github/workflows/build-docs.yml. See https://lychee.cli.rs/usage/config/.
+
+exclude = [
+    # PR-preview canonical URLs are checked by the preview deployment workflow.
+    '^https://nvidia\.github\.io/cuda-python/pr-preview/pr-[0-9]+/',
+    # The cuda-bindings #id links are docutils "problematic" anchors from generated API docs.
+    # TODO: Remove this exclusion after cybind stops emitting those problematic anchors.
+    '^file://.*/cuda-bindings/latest/module/(driver|runtime)\.html#id[0-9]+$',
+    # Preferred Networks rejects hosted-runner GETs, but the URL is browser reachable.
+    '^https://www\.preferred\.jp/en/?$',
+]