Use conda-forge LLVM on Windows

Author: ciaranra

.github/workflows/julia-release.yml

@@ -153,17 +153,20 @@ jobs:
         if: runner.os == 'Windows'
         shell: pwsh
         run: |
-          $llvmPrefix = Join-Path $env:USERPROFILE ".pecos\deps\llvm-21.1"
-          Write-Host "Installing LLVM 21.1 development archive..."
-          ./scripts/ci/install-llvm-21-windows.ps1 -InstallDir $llvmPrefix -Version ${{ env.LLVM_RELEASE_VERSION }}
+          $llvmRoot = Join-Path $env:USERPROFILE ".pecos\deps\llvm-21.1"
+          $llvmPrefix = Join-Path $llvmRoot "Library"
+          Write-Host "Installing conda-forge LLVM 21.1..."
+          ./scripts/ci/install-llvm-21-windows.ps1 -InstallDir $llvmRoot -Version ${{ env.LLVM_RELEASE_VERSION }}
 
           Write-Host "Setting LLVM environment variables..."
           $env:PECOS_LLVM = $llvmPrefix
           $env:LLVM_SYS_211_PREFIX = $env:PECOS_LLVM
+          $env:LIBCLANG_PATH = Join-Path $llvmPrefix "bin"
           cargo run --locked -p pecos-cli --release -- llvm configure "$env:PECOS_LLVM"
 
           "PECOS_LLVM=$env:PECOS_LLVM" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
           "LLVM_SYS_211_PREFIX=$env:LLVM_SYS_211_PREFIX" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+          "LIBCLANG_PATH=$env:LIBCLANG_PATH" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
 
           Write-Host "Verifying LLVM installation..."
           cargo run --locked -p pecos-cli --release -- llvm check

.github/workflows/python-release.yml

@@ -281,19 +281,19 @@ jobs:
             pipx run abi3audit --strict --report {wheel}
           # Windows configuration - CUDA via Jimver/cuda-toolkit (installed before cibuildwheel)
           CIBW_ENVIRONMENT_WINDOWS: >
-            PATH="C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\bin;C:\\Users\\runneradmin\\.pecos\\deps\\cmake-${{ env.PECOS_CMAKE_VERSION }}\\bin;$PATH"
-            LLVM_SYS_211_PREFIX="C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1"
-            LIBCLANG_PATH="C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\bin"
+            PATH="C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\Library\\bin;C:\\Users\\runneradmin\\.pecos\\deps\\cmake-${{ env.PECOS_CMAKE_VERSION }}\\bin;$PATH"
+            LLVM_SYS_211_PREFIX="C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\Library"
+            LIBCLANG_PATH="C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\Library\\bin"
             CMAKE="C:\\Users\\runneradmin\\.pecos\\deps\\cmake-${{ env.PECOS_CMAKE_VERSION }}\\bin\\cmake.exe"
             MATURIN_PEP517_ARGS="--locked --features=extension-module,mwpf"
           CIBW_BEFORE_ALL_WINDOWS: >
-            echo "=== Installing LLVM 21.1 development archive ===" &&
+            echo "=== Installing conda-forge LLVM 21.1 ===" &&
             rustup update &&
             powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\ci\install-llvm-21-windows.ps1 -InstallDir "C:\Users\runneradmin\.pecos\deps\llvm-21.1" -Version ${{ env.LLVM_RELEASE_VERSION }} &&
-            cargo run --locked --release -p pecos-cli -- llvm configure "C:\Users\runneradmin\.pecos\deps\llvm-21.1" &&
+            cargo run --locked --release -p pecos-cli -- llvm configure "C:\Users\runneradmin\.pecos\deps\llvm-21.1\Library" &&
             cargo run --locked --release -p pecos-cli -- install cmake --force &&
             echo "=== Checking LLVM installation ===" &&
-            if exist "C:\Users\runneradmin\.pecos\deps\llvm-21.1\bin\llvm-config.exe" (echo LLVM directory exists) else (echo ERROR: LLVM directory not found! && exit /b 1)
+            if exist "C:\Users\runneradmin\.pecos\deps\llvm-21.1\Library\bin\llvm-config.exe" (echo LLVM directory exists) else (echo ERROR: LLVM directory not found! && exit /b 1)
           # Install delvewheel and patch it to ignore ext-ms-win-* API sets
           # (delvewheel ignores api-ms-win-* but not ext-ms-win-* which are also Windows API sets)
           CIBW_BEFORE_BUILD_WINDOWS: >
@@ -302,7 +302,7 @@ jobs:
           # Note: --no-dll excludes Windows system DLLs that should not be bundled
           # combase.dll and rmclient.dll are core Windows components that fail when bundled
           CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: >
-            delvewheel repair -v --add-path "C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\bin" --no-dll "combase.dll;rmclient.dll" -w {dest_dir} {wheel} &&
+            delvewheel repair -v --add-path "C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\Library\\bin" --no-dll "combase.dll;rmclient.dll" -w {dest_dir} {wheel} &&
             pipx run abi3audit --strict --report {wheel}
 
       - name: Upload pecos-rslib wheels
@@ -375,18 +375,18 @@ jobs:
             PATH=$HOME/.pecos/bin:$PATH DYLD_LIBRARY_PATH=$HOME/.pecos/deps/llvm-21.1/lib delocate-wheel --require-archs {delocate_archs} -w {dest_dir} -v {wheel} &&
             pipx run abi3audit --strict --report {wheel}
           CIBW_ENVIRONMENT_WINDOWS: >
-            PATH="C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\bin;$PATH"
-            LLVM_SYS_211_PREFIX="C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1"
-            LIBCLANG_PATH="C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\bin"
+            PATH="C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\Library\\bin;$PATH"
+            LLVM_SYS_211_PREFIX="C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\Library"
+            LIBCLANG_PATH="C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\Library\\bin"
           CIBW_BEFORE_ALL_WINDOWS: >
             rustup update &&
-            if not exist "C:\Users\runneradmin\.pecos\deps\llvm-21.1\bin\llvm-config.exe" (powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\ci\install-llvm-21-windows.ps1 -InstallDir "C:\Users\runneradmin\.pecos\deps\llvm-21.1" -Version ${{ env.LLVM_RELEASE_VERSION }}) else (echo LLVM already installed from pecos-rslib build) &&
-            cargo run --locked --release -p pecos-cli -- llvm configure "C:\Users\runneradmin\.pecos\deps\llvm-21.1"
+            if not exist "C:\Users\runneradmin\.pecos\deps\llvm-21.1\Library\bin\llvm-config.exe" (powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\ci\install-llvm-21-windows.ps1 -InstallDir "C:\Users\runneradmin\.pecos\deps\llvm-21.1" -Version ${{ env.LLVM_RELEASE_VERSION }}) else (echo LLVM already installed from pecos-rslib build) &&
+            cargo run --locked --release -p pecos-cli -- llvm configure "C:\Users\runneradmin\.pecos\deps\llvm-21.1\Library"
           CIBW_BEFORE_BUILD_WINDOWS: >
             pip install delvewheel &&
             python -c "import delvewheel._dll_list as d,inspect,re as r;p=inspect.getfile(d);c=open(p).read();n=chr(10);open(p,'w').write(c.replace(r\"re.compile('api-.*'),\",r\"re.compile('api-.*'),\"+n+r\"    re.compile('ext-.*'),\")) if 'ext-.*' not in c else None"
           CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: >
-            delvewheel repair -v --add-path "C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\bin" --no-dll "combase.dll;rmclient.dll" -w {dest_dir} {wheel} &&
+            delvewheel repair -v --add-path "C:\\Users\\runneradmin\\.pecos\\deps\\llvm-21.1\\Library\\bin" --no-dll "combase.dll;rmclient.dll" -w {dest_dir} {wheel} &&
             pipx run abi3audit --strict --report {wheel}
 
       - name: Upload pecos-rslib-llvm wheels

.github/workflows/rust-test.yml

@@ -297,23 +297,4 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          # Windows CI uses the official LLVM development archive, which is
-          # static-only for MSVC. Keep this lane targeted so it still exercises
-          # LLVM without fanning out many static HUGR linker jobs at once.
-          cargo test --locked --workspace --release \
-            --exclude pecos-rslib \
-            --exclude pecos-rslib-cuda \
-            --exclude pecos-julia-ffi \
-            --exclude pecos-go-ffi \
-            --exclude pecos-rslib-exp \
-            --exclude pecos-rslib-llvm \
-            --exclude pecos-cuquantum \
-            --exclude pecos-cli \
-            --exclude pecos-decoders \
-            --exclude pecos-gpu-sims \
-            --exclude pecos-hugr-qis \
-            --exclude pecos-llvm
-          cargo test --locked -p pecos-cli --features=runtime --release
-          cargo test --locked -p pecos-llvm --release
-          cargo test --locked -p pecos-qis --no-default-features --features=llvm --release
-          cargo test --locked -p pecos-hugr-qis --release
+          cargo run --locked -p pecos-cli --release -- rust test

Justfile

@@ -71,8 +71,9 @@ ci-env: _msvc-bootstrap
             {{pecos}} llvm configure "$(brew --prefix llvm@21)"
             ;;
         Windows*|MINGW*|MSYS*|CYGWIN*)
-            LLVM_PREFIX="${USERPROFILE:-$HOME}\\.pecos\\deps\\llvm-21.1"
-            powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/ci/install-llvm-21-windows.ps1 -InstallDir "$LLVM_PREFIX" -Version "$LLVM_RELEASE_VERSION"
+            LLVM_ENV_ROOT="${USERPROFILE:-$HOME}\\.pecos\\deps\\llvm-21.1"
+            LLVM_PREFIX="${LLVM_ENV_ROOT}\\Library"
+            powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/ci/install-llvm-21-windows.ps1 -InstallDir "$LLVM_ENV_ROOT" -Version "$LLVM_RELEASE_VERSION"
             {{pecos}} llvm configure "$LLVM_PREFIX"
             ;;
         *)

crates/pecos-build/src/llvm.rs

@@ -62,9 +62,9 @@ pub fn is_required_llvm_version(version: &str) -> bool {
 pub fn find_llvm(repo_root: Option<PathBuf>) -> Option<PathBuf> {
     // 1. Check versioned deps path: ~/.pecos/deps/llvm-{version}/
     if let Ok(deps_llvm) = crate::home::get_llvm_dir_path()
-        && is_valid_llvm(&deps_llvm)
+        && let Some(llvm_prefix) = valid_llvm_prefix(&deps_llvm)
     {
-        return Some(deps_llvm);
+        return Some(llvm_prefix);
     }
 
     // 2. Check legacy top-level path: ~/.pecos/llvm/
@@ -74,31 +74,47 @@ pub fn find_llvm(repo_root: Option<PathBuf>) -> Option<PathBuf> {
         #[cfg(target_os = "windows")]
         {
             let user_llvm_new = pecos_dir.join(format!("LLVM-{REQUIRED_VERSION}"));
-            if is_valid_llvm(&user_llvm_new) {
-                crate::home::print_legacy_warning("LLVM", &user_llvm_new);
-                return Some(user_llvm_new);
+            if let Some(llvm_prefix) = valid_llvm_prefix(&user_llvm_new) {
+                crate::home::print_legacy_warning("LLVM", &llvm_prefix);
+                return Some(llvm_prefix);
             }
         }
 
         let user_llvm_legacy = pecos_dir.join("llvm");
-        if is_valid_llvm(&user_llvm_legacy) {
-            crate::home::print_legacy_warning("LLVM", &user_llvm_legacy);
-            return Some(user_llvm_legacy);
+        if let Some(llvm_prefix) = valid_llvm_prefix(&user_llvm_legacy) {
+            crate::home::print_legacy_warning("LLVM", &llvm_prefix);
+            return Some(llvm_prefix);
         }
     }
 
     // 3. Check for project-local LLVM
     if let Some(root) = repo_root {
         let local_llvm = root.join("llvm");
-        if is_valid_llvm(&local_llvm) {
-            return Some(local_llvm);
+        if let Some(llvm_prefix) = valid_llvm_prefix(&local_llvm) {
+            return Some(llvm_prefix);
         }
     }
 
     // 4. Check system installations
     find_system_llvm()
 }
 
+fn valid_llvm_prefix(path: &Path) -> Option<PathBuf> {
+    if is_valid_llvm(path) {
+        return Some(path.to_path_buf());
+    }
+
+    #[cfg(target_os = "windows")]
+    {
+        let conda_library_prefix = path.join("Library");
+        if is_valid_llvm(&conda_library_prefix) {
+            return Some(conda_library_prefix);
+        }
+    }
+
+    None
+}
+
 /// Find the LLVM installation Cargo should use for this project.
 ///
 /// An explicit `.cargo/config.toml` setting takes priority because `cargo`
@@ -405,11 +421,11 @@ pub fn print_llvm_not_found_error() {
 
     #[cfg(target_os = "windows")]
     {
-        eprintln!("Windows MSVC LLVM builds do not provide shared libLLVM.");
-        eprintln!("Use WSL2/Linux for the full HUGR test lane, or configure a full");
-        eprintln!("LLVM 21 package for targeted static LLVM builds:");
+        eprintln!("The official Windows LLVM installer is not sufficient for PECOS.");
+        eprintln!("Use scripts\\ci\\install-llvm-21-windows.ps1 for the conda-forge");
+        eprintln!("LLVM 21.1 toolchain, then configure its Library prefix:");
         eprintln!();
-        eprintln!("    {cmd} llvm configure C:\\path\\to\\llvm");
+        eprintln!("    {cmd} llvm configure %USERPROFILE%\\.pecos\\deps\\llvm-21.1\\Library");
         eprintln!();
     }
 

crates/pecos-build/src/llvm/installer.rs

@@ -37,11 +37,12 @@ pub fn managed_install_unavailable_reason() -> Option<&'static str> {
     #[cfg(target_os = "windows")]
     {
         Some(
-            "PECOS-managed shared LLVM is not available on Windows MSVC because \
-             LLVM does not provide the libLLVM shared-library target there. Use \
-             WSL2/Linux for the full HUGR test lane, or configure a full LLVM 21 \
-             package for targeted static LLVM builds with `pecos llvm configure \
-             C:\\path\\to\\llvm`.",
+            "PECOS-managed LLVM is not implemented in the CLI on Windows yet. \
+             Use `scripts\\ci\\install-llvm-21-windows.ps1` to install the \
+             conda-forge LLVM 21.1 toolchain under `%USERPROFILE%\\.pecos\\deps`, \
+             then run `pecos llvm configure \
+             %USERPROFILE%\\.pecos\\deps\\llvm-21.1\\Library`, or configure \
+             your own full LLVM 21.1 install.",
         )
     }
 

docs/development/dev-tools.md

@@ -121,9 +121,9 @@ large toolchain install. `pecos install llvm` prints what it is about to install
 and asks for confirmation before downloading.
 
 On macOS, install Homebrew LLVM 21 (`brew install llvm@21`) and run
-`pecos llvm configure`. On native Windows MSVC, LLVM does not provide shared
-`libLLVM`; use WSL2/Linux for the full HUGR test lane, or configure a full LLVM
-development package for targeted static builds.
+`pecos llvm configure`. On native Windows MSVC, use
+`scripts\ci\install-llvm-21-windows.ps1` to install the conda-forge LLVM 21.1
+toolchain, then configure `~\.pecos\deps\llvm-21.1\Library`.
 
 `pecos rust test` requires shared LLVM for the workspace HUGR test lane. LLVM
 21.1 static test links can use multiple GB of RAM each, so PECOS fails early
@@ -231,8 +231,8 @@ cargo build -p pecos --features llvm
 ```
 
 On macOS use `brew install llvm@21 && pecos llvm configure`. On native Windows
-MSVC, use WSL2/Linux for the full HUGR test lane or configure a full LLVM 21
-package for targeted static builds.
+MSVC, use `scripts\ci\install-llvm-21-windows.ps1` and configure
+`~\.pecos\deps\llvm-21.1\Library`.
 
 Or using Justfile:
 ```bash

docs/user-guide/llvm-setup.md

@@ -42,10 +42,10 @@ The `install` command automatically:
 This is the **recommended approach** where PECOS can provide a verified shared
 LLVM package. On Debian/Ubuntu-compatible Linux distributions, PECOS downloads
 the apt.llvm.org LLVM 21 packages into `~/.pecos/deps/llvm-21.1/` without using
-`sudo`. On macOS, use Homebrew for LLVM 21. On Windows MSVC, LLVM does not
-provide the shared `libLLVM` target PECOS requires for the full workspace HUGR
-test lane; use WSL2/Linux for that lane, or configure a full LLVM package for
-targeted static LLVM builds.
+`sudo`. On macOS, use Homebrew for LLVM 21. On Windows MSVC, use the
+conda-forge helper in the Windows section below; it installs a full LLVM
+development environment under `~/.pecos/deps/llvm-21.1/` and configures
+`~/.pecos/deps/llvm-21.1/Library` as the LLVM prefix.
 
 This is a developer toolchain install: the CLI prints the install size/behavior
 and asks for confirmation before downloading. Use `--yes` to accept the prompt
@@ -92,11 +92,17 @@ Install LLVM 21.1 using your system's package manager, then configure PECOS:
 
 === "Windows"
     !!! warning "Windows LLVM Requirement"
-        The official LLVM Windows installer (`LLVM-*.exe`) is **toolchain-only** and lacks required development files (`llvm-config.exe` and headers). LLVM's MSVC builds also do not provide shared `libLLVM`, so `pecos rust test` / `just dev` with the full HUGR test lane is not supported on native Windows.
+        The official LLVM Windows installer (`LLVM-*.exe`) is **toolchain-only** and lacks required development files (`llvm-config.exe`, headers, and `libclang.dll`). Use a full LLVM development package built for the MSVC dynamic runtime.
 
-    **Recommended for full development tests:** Use WSL2/Linux and Option 1 above.
+    **Recommended for full development tests:** Use the PECOS conda-forge helper:
 
-    **Alternative for targeted static LLVM builds:** Download a full development package from:
+    ```powershell
+    .\scripts\ci\install-llvm-21-windows.ps1 -InstallDir "$env:USERPROFILE\.pecos\deps\llvm-21.1"
+    cargo run -p pecos-cli -- llvm configure "$env:USERPROFILE\.pecos\deps\llvm-21.1\Library"
+    cargo build --features llvm
+    ```
+
+    **Alternative:** Configure another full LLVM 21.1 development package that includes `llvm-config.exe`, headers, static MSVC libraries built against the dynamic runtime, and `libclang.dll`.
 
     - [bitgate/llvm-windows-full-builds](https://github.com/bitgate/llvm-windows-full-builds) (recommended)
     - [vovkos/llvm-package-windows](https://github.com/vovkos/llvm-package-windows)
@@ -297,13 +303,15 @@ this order:
 
 **Windows:**
 
-- Native Windows LLVM is static-only for PECOS's purposes
-- Use WSL2/Linux for the full HUGR test lane
-- For targeted static LLVM builds, configure a full development package with `pecos llvm configure C:\path\to\llvm`
+- The official LLVM installer is not sufficient for PECOS development builds
+- Use `scripts\ci\install-llvm-21-windows.ps1` for the conda-forge LLVM 21.1 toolchain
+- Configure `~\.pecos\deps\llvm-21.1\Library`, not the conda environment root
 
 ### Security
 
-All downloaded LLVM packages are verified with SHA256 checksums to ensure integrity.
+Linux managed packages are checked against apt metadata hashes. Windows helper
+packages are installed by micromamba from conda-forge, using conda package
+metadata and checksums.
 
 ## Troubleshooting