docs: add Windows-specific setup instructions for beginners (closes #…#1629
Conversation
📝 WalkthroughWalkthroughThis PR improves contributor onboarding by adding comprehensive Windows-specific setup instructions to CONTRIBUTING.md. It introduces a new subsection covering required tools and installation order, includes a PowerShell-based dependency check, and updates the Platform notes section to direct Windows developers to the new guidance. ChangesWindows Contributor Setup Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CONTRIBUTING.md`:
- Around line 55-57: Replace the generic environment variable example with a
PowerShell-specific example to match the rest of the "Quick dependency check"
section: update the code block showing LIBCLANG_PATH to use the PowerShell
$env:LIBCLANG_PATH syntax and add the markdown code fence language identifier
"powershell"; optionally include a second example showing how to persist the
variable using [System.Environment]::SetEnvironmentVariable with 'User' scope
for permanence.
- Around line 47-49: The sentence "This is the full Visual Studio installer, not
the VS Code lightweight editor" is misleading; update the CONTRIBUTING.md text
around the Visual Studio C++ Build Tools section to state that rustup-init
option 1 installs the Visual Studio Build Tools (which include MSVC v143 and the
Windows 11 SDK needed for linking) rather than the full Visual Studio IDE, and
make clear this is distinct from VS Code; keep the note about disk usage and
that the installed tools are for command-line builds only.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| **1. Visual Studio C++ Build Tools** | ||
|
|
||
| Rust's `cargo` needs a linker on Windows. The easiest way to get one is during `rustup-init`: select option **1** (Default installation) when prompted, which includes MSVC v143 and the Windows 11 SDK. This is the full Visual Studio installer, not the VS Code lightweight editor — it lives only on `C:` and consumes ~5.4 GB. |
There was a problem hiding this comment.
Clarify the distinction between VS Build Tools and the full Visual Studio IDE.
The text states "This is the full Visual Studio installer, not the VS Code lightweight editor," which is misleading. When rustup-init option 1 triggers the MSVC installation, it installs Visual Studio Build Tools, not the full Visual Studio IDE. The Build Tools package contains only the compilers and libraries needed for command-line builds, whereas the full Visual Studio installer includes the IDE and is significantly larger.
📝 Proposed clarification
-Rust's `cargo` needs a linker on Windows. The easiest way to get one is during `rustup-init`: select option **1** (Default installation) when prompted, which includes MSVC v143 and the Windows 11 SDK. This is the full Visual Studio installer, not the VS Code lightweight editor — it lives only on `C:` and consumes ~5.4 GB.
+Rust's `cargo` needs a linker on Windows. The easiest way to get one is during `rustup-init`: select option **1** (Default installation) when prompted, which will install Visual Studio Build Tools (including MSVC v143 and the Windows 11 SDK). Note: this is the Build Tools package (compilers and libraries only), not VS Code or the full Visual Studio IDE — it installs to `C:\Program Files (x86)\Microsoft Visual Studio\` and consumes ~5.4 GB.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| **1. Visual Studio C++ Build Tools** | |
| Rust's `cargo` needs a linker on Windows. The easiest way to get one is during `rustup-init`: select option **1** (Default installation) when prompted, which includes MSVC v143 and the Windows 11 SDK. This is the full Visual Studio installer, not the VS Code lightweight editor — it lives only on `C:` and consumes ~5.4 GB. | |
| **1. Visual Studio C++ Build Tools** | |
| Rust's `cargo` needs a linker on Windows. The easiest way to get one is during `rustup-init`: select option **1** (Default installation) when prompted, which will install Visual Studio Build Tools (including MSVC v143 and the Windows 11 SDK). Note: this is the Build Tools package (compilers and libraries only), not VS Code or the full Visual Studio IDE — it installs to `C:\Program Files (x86)\Microsoft Visual Studio\` and consumes ~5.4 GB. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CONTRIBUTING.md` around lines 47 - 49, The sentence "This is the full Visual
Studio installer, not the VS Code lightweight editor" is misleading; update the
CONTRIBUTING.md text around the Visual Studio C++ Build Tools section to state
that rustup-init option 1 installs the Visual Studio Build Tools (which include
MSVC v143 and the Windows 11 SDK needed for linking) rather than the full Visual
Studio IDE, and make clear this is distinct from VS Code; keep the note about
disk usage and that the installed tools are for command-line builds only.
| ``` | ||
| LIBCLANG_PATH=C:\Program Files\LLVM\bin | ||
| ``` |
There was a problem hiding this comment.
Use consistent PowerShell syntax for environment variable.
The code block shows generic environment variable syntax without the PowerShell $env: prefix, which is inconsistent with line 91 where you correctly use $env:LIBCLANG_PATH. Since the "Quick dependency check" section uses PowerShell, this guidance should also show PowerShell syntax for consistency. Additionally, the code block is missing a language identifier (flagged by markdownlint).
🔧 Proposed fix for consistency
-```
-LIBCLANG_PATH=C:\Program Files\LLVM\bin
-```
+```powershell
+$env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin"
+```If you want to set it permanently (persist across terminal sessions), add guidance to use:
[System.Environment]::SetEnvironmentVariable('LIBCLANG_PATH', 'C:\Program Files\LLVM\bin', 'User')🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 55-55: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CONTRIBUTING.md` around lines 55 - 57, Replace the generic environment
variable example with a PowerShell-specific example to match the rest of the
"Quick dependency check" section: update the code block showing LIBCLANG_PATH to
use the PowerShell $env:LIBCLANG_PATH syntax and add the markdown code fence
language identifier "powershell"; optionally include a second example showing
how to persist the variable using [System.Environment]::SetEnvironmentVariable
with 'User' scope for permanence.
graycyrus
left a comment
graycyrus
left a comment
There was a problem hiding this comment.
PR Review — docs: add Windows-specific setup instructions for beginners
Walkthrough
Adds a "Windows-specific setup" section to CONTRIBUTING.md covering VS Build Tools, LLVM/Clang, CMake, Node/pnpm, a recommended install order, and a PowerShell verification snippet. Also adds a "Windows desktop builds" bullet to the Platform notes. Content is clearly written and based on a real Windows 11 setup walkthrough. A few accuracy gaps remain that would trip up contributors.
Changes
| File | Summary |
|---|---|
CONTRIBUTING.md |
Adds Windows-specific setup subsection (lines 43–93) + Windows bullet in Platform notes |
Verified / looks good
- Node.js version (
24+) and pnpm (10.10.0) matchapp/package.jsonandpackage.json - Rust toolchain version matches
rust-toolchain.toml - Anchor
#windows-specific-setupin Platform notes resolves correctly winget install Kitware.CMakeis the correct package identifierwhisper-rs-sysdoes depend onlibclang— confirmed inCargo.toml
See inline comments for actionable items.
|
|
||
| **1. Visual Studio C++ Build Tools** | ||
|
|
||
| Rust's `cargo` needs a linker on Windows. The easiest way to get one is during `rustup-init`: select option **1** (Default installation) when prompted, which includes MSVC v143 and the Windows 11 SDK. This is the full Visual Studio installer, not the VS Code lightweight editor — it lives only on `C:` and consumes ~5.4 GB. |
There was a problem hiding this comment.
[major] Missing rustup target add x86_64-pc-windows-msvc. The Recommended install order has Rust at step 2, but never tells the contributor to add the MSVC target. gitbooks/developing/building-rust-core.md explicitly calls this out — without it, cargo build on Windows will fail.
Suggest adding after the Rust install step:
rustup target add x86_64-pc-windows-msvc| pnpm --version | ||
|
|
||
| # Verify libclang is accessible (needed by whisper-rs-sys) | ||
| $env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin" |
There was a problem hiding this comment.
[major] This $env:LIBCLANG_PATH assignment only lasts for the current terminal session. A contributor who followed step 2 and skipped the PATH option will close the terminal, reopen, run cargo build, and hit libclang not found again.
Suggest clarifying this is session-only and pointing to the permanent fix:
# Session-only workaround. For a permanent fix, add LIBCLANG_PATH
# via System Properties > Environment Variables > System variables > New
$env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin"|
|
||
| **2. LLVM / Clang** | ||
|
|
||
| `whisper-rs-sys` depends on `libclang`. Download the Windows x86_64 release from [github.com/llvm/llvm-project/releases](https://github.com/llvm/llvm-project/releases) (~822 MB). During install, check **"Add LLVM to system PATH for all users"**. If you see a "PATH too long" warning, skip the PATH step and set the environment variable manually: |
There was a problem hiding this comment.
[minor] No cross-link to gitbooks/developing/building-rust-core.md. The Linux Platform notes bullet links to GitBook for deeper troubleshooting — consider adding an equivalent pointer here:
For deeper Windows build troubleshooting, see [`gitbooks/developing/building-rust-core.md`](gitbooks/developing/building-rust-core.md).|
|
||
| **2. LLVM / Clang** | ||
|
|
||
| `whisper-rs-sys` depends on `libclang`. Download the Windows x86_64 release from [github.com/llvm/llvm-project/releases](https://github.com/llvm/llvm-project/releases) (~822 MB). During install, check **"Add LLVM to system PATH for all users"**. If you see a "PATH too long" warning, skip the PATH step and set the environment variable manually: |
There was a problem hiding this comment.
[minor] Stray unclosed parenthesis: ~822 MB). should be (~822 MB).
3 participants
Summary
Added Windows-specific setup instructions to CONTRIBUTING.md based on a real first-time contributor experience on Windows.
Changes
Testing
Walked through the entire setup process from scratch on Windows 11, verified all steps from
git clonethroughcargo buildandpnpm dev.Closes #1600
Summary by CodeRabbit