How to Compile Viridithas on Windows

1) What you are building (and why the toolchain matters)

1.1 Rust version requirement

Viridithas declares a minimum Rust toolchain requirement. Before you start, make sure your rustc/cargo versions satisfy the project’s declared rust-version. If your Rust toolchain is older, update it with rustup (see section 4).

1.2 Why MSYS2 + Clang is relevant on Windows

When you enable syzygy, Viridithas builds Fathom probing code written in C. On Windows, the project’s build script forces clang for that C compilation step. In practical terms: clang.exe must be on PATH at build time.

1.3 Why the bindgen feature needs libclang.dll

Bindgen generates Rust bindings from C headers via libclang. On Windows, you typically fix bindgen/libclang issues by ensuring:

• LIBCLANG_PATH points to a directory containing libclang.dll
• That same directory is also present in PATH so Windows can load dependent DLLs

1.4 The NNUE network file is required at build time

Viridithas expects a zstd-compressed network file in the project root named viridithas.nnue.zst. If it is missing, the build script will warn and/or fail. You can also set an EVALFILE environment variable to a different file path; the build script will copy it into place.

2) Configure MSYS2 properly (packages and environment choice)

MSYS2 provides multiple environments (MINGW64, UCRT64, CLANG64, etc.). Choose one and stay consistent. The simplest approach is: use UCRT64 or MINGW64, install clang + clang runtime libraries, then expose the environment bin directory to PowerShell during the build.

3) Install MSYS2 packages you’ll need

3.1 Update MSYS2

pacman -Syu

If core updates require closing the terminal, do it, reopen the same MSYS2 environment, then run the update again.

pacman -Syu

3.2 Install required packages

Pick the set matching your MSYS2 shell:

pacman -S --needed git \
  mingw-w64-ucrt-x86_64-clang \
  mingw-w64-ucrt-x86_64-clang-libs

pacman -S --needed git \
  mingw-w64-x86_64-clang \
  mingw-w64-x86_64-clang-libs

4) Install/Update Rust for Windows

In PowerShell, verify your current Rust toolchain:

rustc --version
cargo --version

If your Rust is older than the project requirement, update:

rustup update
rustup show

Ensure you are using stable:

rustup default stable
rustc --version

5) Clone Viridithas “from Clang” (MSYS2 shell)

Open your MSYS2 shell (UCRT64 or MINGW64) and clone the repository. You can clone anywhere; this example uses your MSYS2 home directory:

cd ~
git clone https://github.com/cosmobobak/viridithas.git
cd viridithas

Once the source is cloned, the remainder of this workflow will be driven from PowerShell for a clean Windows build.

6) Download the NNUE network (two reliable methods)

Networks are hosted in a separate release repository. The engine expects a file named viridithas.nnue.zst in the Viridithas repo root.

Method A (MSYS2) — use the “latest network” command

cd ~/viridithas
curl -s "https://api.github.com/repos/cosmobobak/viridithas-networks/releases/latest" \
  | grep -o '"browser_download_url": "[^"]*' \
  | awk -F'"' '{print $4}' \
  | xargs -L 1 wget -O viridithas.nnue.zst

Method B (PowerShell) — download latest network via GitHub API

# Run this from the viridithas repo directory
$ErrorActionPreference = "Stop"

$api = "https://api.github.com/repos/cosmobobak/viridithas-networks/releases/latest"
$release = Invoke-RestMethod -Uri $api -Headers @{ "User-Agent" = "PowerShell" }

# Try to pick an asset ending in .nnue.zst
$asset = $release.assets | Where-Object { $_.name -match '\.nnue\.zst$' } | Select-Object -First 1

if (-not $asset) {
  # Fallback: take the first asset if naming differs
  $asset = $release.assets | Select-Object -First 1
}

if (-not $asset) {
  throw "No assets found in the latest viridithas-networks release."
}

Write-Host "Downloading network:" $asset.name
Invoke-WebRequest -Uri $asset.browser_download_url -OutFile "viridithas.nnue.zst"
Write-Host "Saved as viridithas.nnue.zst in repo root."

7) Build Viridithas from PowerShell (main workflow)

The upstream Windows build command is: set RUSTFLAGS="-C target-cpu=native" and run cargo build -r --features syzygy,bindgen. We do that below, but we also ensure PowerShell can find clang and libclang.dll.

7.1 Choose the MSYS2 bin directory you will expose to PowerShell

• UCRT64: C:\msys64\ucrt64\bin
• MINGW64: C:\msys64\mingw64\bin
• CLANG64: C:\msys64\clang64\bin

7.2 One-shot PowerShell build script (copy/paste)

# ===========================
# Viridithas Windows Build (PowerShell + MSYS2)
# Features: syzygy + bindgen
# ===========================
$ErrorActionPreference = "Stop"

# 1) EDIT THESE PATHS IF NEEDED
$RepoDir   = "C:\msys64\home\YOUR_USER\viridithas"   # <-- set this to your actual clone path
$MsysBin   = "C:\msys64\mingw64\bin"                # <-- or ucrt64\bin, clang64\bin, etc.

# 2) Sanity checks
if (-not (Test-Path $RepoDir)) { throw "Repo directory not found: $RepoDir" }
if (-not (Test-Path $MsysBin)) { throw "MSYS2 bin directory not found: $MsysBin" }

Set-Location $RepoDir

# 3) Ensure clang + libclang are discoverable
$env:PATH = "$MsysBin;$env:PATH"
$env:LIBCLANG_PATH = $MsysBin

Write-Host "clang location:" (Get-Command clang -ErrorAction SilentlyContinue).Source
clang --version

# 4) Confirm the NNUE file exists (required by build script)
if (-not (Test-Path ".\viridithas.nnue.zst")) {
  throw "Missing viridithas.nnue.zst in repo root. Download the network first."
}

# 5) Confirm Rust toolchain
rustc --version
cargo --version

# 6) Build flags (as per upstream README)
$env:RUSTFLAGS = "-C target-cpu=native"

# 7) Build (cargo b == cargo build; we use the full word for clarity)
cargo build -r --features syzygy,bindgen

# 8) Result
$exe = Join-Path $RepoDir "target\release\viridithas.exe"
if (Test-Path $exe) {
  Write-Host "Build OK => $exe"
} else {
  throw "Build finished, but viridithas.exe was not found at: $exe"
}

8) Optional: use final-release instead of listing features manually

Viridithas defines a convenience feature set called final-release (commonly including zstd, bindgen, and syzygy). You can try:

cargo build -r --features final-release

If your environment hits extra native dependencies for zstd, fall back to the simpler upstream line: --features syzygy,bindgen.

9) Post-build verification (quick smoke tests)

9.1 UCI handshake test

.\target\release\viridithas.exe

Then type:

uci
isready
quit

9.2 Bench test

.\target\release\viridithas.exe bench

10) Configure Syzygy tablebases at runtime

Compiling with syzygy enables tablebase probing support, but you still need to set the runtime path to your Syzygy files:

• In your GUI: set SyzygyPath to the folder containing .rtbw/.rtbz files
• In UCI: setoption name SyzygyPath value D:\TB\Syzygy\6-man

11) Troubleshooting (Windows/MSYS2-specific issues)

11.1 “Couldn’t read default net during build script”

Cause: missing viridithas.nnue.zst in the repo root. Fix: download the network into the repo root (exact filename), or set EVALFILE to the network file path.

11.2 bindgen error: “Unable to find libclang” / LoadLibrary failures

Cause: libclang.dll is missing or cannot be loaded. Fix checklist:

• Install the MSYS2 clang runtime libs package for your environment (clang-libs)
• Set LIBCLANG_PATH to your MSYS2 environment bin directory
• Prepend that same directory to PATH in the PowerShell session before running Cargo

11.3 clang not found during build

Cause: PowerShell PATH does not include your MSYS2 toolchain bin directory. Fix: prepend C:\msys64\...\bin (ucrt64/mingw64/clang64) to PATH in the same session that runs the build.

11.4 target-cpu=native builds, but the engine crashes on some machines

Rare but possible on specific CPU/microcode combinations. If you suspect this, rebuild with a safer baseline:

$env:RUSTFLAGS = "-C target-cpu=x86-64"
cargo build -r --features syzygy,bindgen

12) Reproducible build notes (recommended for tournament operators)

For audit-grade reproducibility, record the exact commit and toolchain versions used to produce a binary:

git rev-parse HEAD
rustc --version
cargo --version
clang --version

Also record which MSYS2 environment you used (ucrt64/mingw64/clang64), which feature set you built (syzygy,bindgen or final-release), and whether you used target-cpu=native.

Conclusion

Compiling Viridithas on Windows is straightforward once you treat it as two cooperating layers: MSYS2 provides clang and libclang, while PowerShell runs a clean Cargo build with the documented features enabled. Keep three items consistent—your Rust version, the NNUE network file, and libclang visibility— and you will get stable, repeatable binaries suitable for testing and tournament operations.

If you follow the IJCCRL approach: pin the commit, log the toolchain, and keep your scripts copy-pasteable. That is how “I built it yesterday” becomes “I can rebuild it any time.”