Skip to content

Commit 6d6af42

Browse files
juenglinjuenglin
authored
build: require symlinks on Windows; move lychee excludes to lychee.toml (#2992)
* ci: move lychee excludes to lychee.toml Move the link-checker excludes out of build-docs.yml into a repo-root lychee.toml, and point the workflow at it with --config. This keeps the exclude list and its explanatory comments in one place. No behavior change. * ci: enable git symlinks on Windows runners; add Windows dev docs Set core.symlinks=true before checkout in the Windows wheel, wheel-test and sdist-test workflows, and add a "Development on Windows" section to CONTRIBUTING.md covering symlink setup (Developer Mode, core.symlinks). The existing pre-commit lychee workaround moves into that section.
1 parent a1c413f commit 6d6af42

6 files changed

Lines changed: 92 additions & 19 deletions

File tree

‎.github/workflows/build-docs.yml‎

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

‎.github/workflows/build-wheel.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,10 @@ jobs:
6767
(inputs.host-platform == 'win-64' && 'windows-2022') ||
6868
(inputs.host-platform == 'win-arm64' && 'windows-11-arm') }}
6969
steps:
70+
- name: Enable Git symlinks (Windows, must precede checkout)
71+
if: ${{ startsWith(inputs.host-platform, 'win') }}
72+
run: git config --global core.symlinks true
73+
7074
- name: Checkout ${{ github.event.repository.name }}
7175
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
7276
with:

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@ jobs:
4343
timeout-minutes: 60
4444
runs-on: windows-2022
4545
steps:
46+
- name: Enable Git symlinks (Windows, must precede checkout)
47+
run: git config --global core.symlinks true
48+
4649
- name: Checkout ${{ github.event.repository.name }}
4750
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
4851
with:

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,9 @@ jobs:
105105
continue-on-error: ${{ startsWith(matrix.PY_VER, '3.15') }}
106106
runs-on: "windows-${{ matrix.ARCH }}-gpu-${{ matrix.GPU }}-${{ matrix.RUNNER_DRIVER }}-${{ matrix.GPU_COUNT }}"
107107
steps:
108+
- name: Enable Git symlinks (Windows, must precede checkout)
109+
run: git config --global core.symlinks true
110+
108111
- name: Checkout ${{ github.event.repository.name }}
109112
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
110113
with:

‎CONTRIBUTING.md‎

Lines changed: 66 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,11 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
2323
- [Recommended clone](#recommended-clone)
2424
- [Fixing an existing clone](#fixing-an-existing-clone)
2525
- [Symptoms of a bad clone](#symptoms-of-a-bad-clone)
26+
- [Development on Windows](#development-on-windows)
27+
- [Enabling git symlinks](#enabling-git-symlinks)
28+
- [Pre-commit lychee workaround](#pre-commit-lychee-workaround)
2629
- [Type stubs for cuda.core](#type-stubs-for-cudacore)
2730
- [Pre-commit](#pre-commit)
28-
- [Pre-commit on Windows](#pre-commit-on-windows)
2931
- [Pixi lockfiles](#pixi-lockfiles)
3032
- [Signing Your Work](#signing-your-work)
3133
- [Code signing](#code-signing)
@@ -42,6 +44,11 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
4244

4345
## Cloning the repository
4446

47+
> **Windows contributors (not WSL):** configure Git for symlinks *before*
48+
> cloning, or the shared PEP 517 build-hook file lands as a text stub instead
49+
> of a working symlink. See [Enabling git symlinks](#enabling-git-symlinks)
50+
> under Development on Windows.
51+
4552
Every package in this repository derives its version from git tags using
4653
[`setuptools-scm`](https://setuptools-scm.readthedocs.io/), so **how you clone
4754
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`,
128135
genuinely cannot provide tags; it is not a substitute for a correct clone.
129136

130137

138+
## Development on Windows
139+
140+
This section collects the Windows-specific setup a contributor needs when
141+
working outside of WSL. WSL contributors can follow the Linux flow in the rest
142+
of this document.
143+
144+
### Enabling git symlinks
145+
146+
The `cuda_core` PEP 517 backend shares source-of-truth helper files with
147+
`cuda_bindings` via symbolic links. Git materializes symlinks by default on
148+
Linux and macOS, but on Windows it needs to be configured before cloning,
149+
otherwise the "symlinks" land in your working tree as plain text files that
150+
contain the target path — enough to look right in `git status`, but not enough
151+
to actually build.
152+
153+
1. **[Activate Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development#activate-developer-mode)**
154+
so Git can create symlinks without Administrator privileges.
155+
156+
2. **Enable Git symlink support globally** so newly-cloned repositories inherit
157+
the setting:
158+
159+
```console
160+
$ git config --global core.symlinks true
161+
```
162+
163+
Then clone as usual (see [Cloning the repository](#cloning-the-repository)).
164+
165+
If you already cloned without these settings, note that `git clone` probes
166+
symlink support at clone time and writes `core.symlinks=false` into the
167+
repo-local config when the probe fails. Repo-local config overrides
168+
`--global`, so you must clear it *inside the existing clone* — the global
169+
setting alone won't take effect:
170+
171+
```console
172+
$ git config core.symlinks true # no --global — clears the repo-local override
173+
$ git rm --cached cuda_core/_build_shared.py
174+
$ git checkout HEAD -- cuda_core/_build_shared.py
175+
```
176+
177+
In practice, deleting the checkout and re-cloning after the two steps at
178+
the top of this section (Developer Mode + `git config --global core.symlinks
179+
true`) is usually simpler and less error-prone than repairing an existing
180+
clone in place.
181+
182+
### Pre-commit lychee workaround
183+
184+
For development on Windows (not WSL), the `lychee` pre-commit task will not
185+
work when running `pre-commit run --all-files`. This problem does not occur
186+
if you install the pre-commit hook and run it automatically as part of your
187+
`git commit` workflow. To resolve this, you can either:
188+
189+
1. Run `pre-commit` in Git Bash, rather than directly in PowerShell or cmd
190+
191+
2. Skip it by setting the environment variable `SKIP` to `lychee`. This would
192+
be `$env:SKIP = "lychee"` in PowerShell or `set SKIP=lychee` in cmd.
193+
194+
131195
## Type stubs for cuda.core
132196

133197
`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.
168232
If the hook isn't installed, `pre-commit run` (and CI) will print a visible
169233
warning reminding you to run `pre-commit install`.
170234

171-
### Pre-commit on Windows
172-
173-
For development on Windows (not WSL), the `lychee` pre-commit task will not work
174-
when running `pre-commit run --all-files`. This problem does not occur if you
175-
install the pre-commit hook and run it automatically as part of your `git
176-
commit` workflow. To resolve this, you can either:
177-
178-
1. Run `pre-commit` in Git Bash, rather than directly in PowerShell or cmd
179-
180-
2. Skip it by setting the environment variable `SKIP` to `lychee`. This would
181-
be `$env:SKIP = "lychee"` in PowerShell or `set SKIP=lychee` in cmd.
235+
Windows contributors: see [Pre-commit lychee workaround](#pre-commit-lychee-workaround) under Development on Windows.
182236

183237
## Pixi lockfiles
184238

‎lychee.toml‎

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

0 commit comments

Comments
 (0)