Skip to content

Building WPR

Jump to bottom
Bubbleshum edited this page May 22, 2026 · 2 revisions

Building WPR

Warning

Alpha software. The main branch is not guaranteed to build cleanly at any given checkpoint — active work happens on per-feature branches. If main won't build, check the recent feature branches before opening an issue.

Requirements

Tool Version Why
.NET 8 SDK 8.0.x Target framework net8.0-windows10.0.17763.0
Rider, or VS 2022 17.8+ latest Recommended IDE — handles transitive project refs better than CLI
Git any recent Repo + submodules
Windows 10 (1809) or 11 — Desktop target's TPM is 17763
Android SDK + .NET Android workload platforms 35 or 36 Only if building the Android target — see Android Setup for the SDK version pitfalls

WPR's runtime backend is FNA + SDL2 + FAudio + FNA3D + FFmpeg, all shipped next to the executable. There is no system Vulkan / DirectX prerequisite — FNA3D picks an available backend (D3D11 on Windows by default).

Clone

git clone https://github.com/Bubbleshum/WPR.git
cd WPR

Build & run from Rider (recommended)

  1. Open Src/WPR.sln.
  2. Set the startup project to WPR.UI.Desktop.
  3. Build → Run.

Rider uses the system .NET MSBuild and handles transitive project references the way the CLI doesn't (see the CLI build section below for why this matters).

CLI build — quick edit-verify

The full-solution dotnet build hits NU1202 on Avalonia.Android when the Android workload version doesn't line up with the system SDK (very common on this dev box). To verify a small edit on a single project:

dotnet build <project>.csproj -c Debug `
    -f net8.0-windows10.0.17763.0 `
    -maxcpucount:1 -nodeReuse:false --nologo

What each flag does:

Flag Why
-f net8.0-windows10.0.17763.0 Skips the broken Android leg
-maxcpucount:1 Avoids an MSBuild CS0006 "metadata file not found" race in parallel builds
-nodeReuse:false Prevents stale MSBuild nodes from carrying broken state across invocations
--nologo Quieter output

Build leaf projects first (e.g. WPR.SilverlightCompability, FNA.Core, or Microsoft.Xna.Framework.GamerServices) — they have no project deps to stage and give the fastest yes/no on a shim edit.

Building WPR / WPR.UI / WPR.UI.Desktop from CLI sometimes fails with spurious "namespace not found" cascades because the CLI doesn't restage transitive project references the way Rider does. Treat a successful leaf build as sufficient validation; defer the full chain to Rider.

Release build

dotnet build Src/UI/WPR.UI.Desktop/WPR.UI.Desktop.csproj `
    -c Release `
    -f net8.0-windows10.0.17763.0 `
    -maxcpucount:1 -nodeReuse:false --nologo

Release builds elide all [wpr-trace] diagnostics via WprDebugTrace's #if DEBUG gates — no log spam, no per-frame cost. Use Debug for compat work.

Android target

net8.0-android resolves to TargetPlatformVersion=36.0 on the system .NET 10 SDK with the Android workload 36.1.43/10.0.100. See Android Setup for the workload-version pitfalls and the current state of the Android target (it builds, but launches to a white screen on this fork).

Common build problems

NETSDK1141 / error : The reference assemblies … were not found

Two .NET SDKs visible to your shell? dotnet --info and check the active SDK. Don't pin to a user-local SDK via global.json — Rider's MSBuild uses the system SDK, and a global.json pointing at a user-local one will make Rider fail with NETSDK1141.

NU1202 on Avalonia.Android

Android workload version mismatch. Either install a matching workload (dotnet workload install android) or pass -f net8.0-windows10.0.17763.0 to skip the Android leg.

CS0006: metadata file not found

Parallel-build race. Re-run with -maxcpucount:1 -nodeReuse:false.

CS0246 / namespace not found for our own types

CLI didn't restage a project reference. Build the leaf project that defines the missing type first, then re-run the full build — or build from Rider.

Spurious build noise from obj/ or bin/

Leave these directories alone. They're normal incremental build artifacts; removing them forces a full rebuild you didn't ask for.

Where the build outputs

Target Output dir
Desktop Debug Src/UI/WPR.UI.Desktop/bin/Debug/net8.0-windows10.0.17763.0/
Desktop Release Src/UI/WPR.UI.Desktop/bin/Release/net8.0-windows10.0.17763.0/
Android Debug Src/UI/WPR.UI.Android/bin/Debug/net8.0-android/

The desktop output drops FNA.dll, FNA3D.dll, SDL2.dll, FAudio.dll, FNWP72.dll, ffmpeg.exe, and all the WPR shim DLLs next to WPR.UI.Desktop.exe. Distribute as a directory.

Repository conventions

A few rules of the road for anyone touching the code — full detail in CLAUDE.md:

  • Shim file layout in WPR.SilverlightCompability mirrors upstream namespaces. System.Windows.Shapes.Rectangle → System/Windows/Shapes/Rectangle.cs. See Architecture for the convention.
  • Patcher table changes need a reinstall of affected games — the IL rewrite happens once at install time. See Architecture.
  • Don't commit build logs / scratch global.json / obj/ / bin/.

Next steps

Clone this wiki locally