version: "1.0.0" name: build description: Build the WinUI repository. Use when asked to build, compile, or rebuild the project after making code changes.

Building WinUI

AI Agent Quick Start

# Always wrap commands with .\initrun.ps1 — it sets up the build environment automatically.
# Default flavor is amd64chk. Override with -Flavor.
 
.\initrun.ps1 .\build.cmd /q                            # full repo build (product + tests) — USE THIS BY DEFAULT
.\initrun.ps1 .\build.cmd /q product                    # product code only (no tests)
.\initrun.ps1 .\build.cmd /q mux                        # MUX only (Microsoft.UI.Xaml.dll)
.\initrun.ps1 msb /q "path\to\project.vcxproj"          # build a single project
.\initrun.ps1 -Flavor arm64fre .\build.cmd /q           # build for a different flavor

Rules:

• Always prefix with .\initrun.ps1, this sets up critical environment variables and sanity-checks the environment
• Always pass /q for quiet output (errors only)
• Set initial_wait to at least 300 seconds — builds take 1-10+ minutes
• When the user asks to "build the repo" or just "build" without specifying a target, use `.\initrun.ps1 .\build.cmd /q` (full build).

Only use mux or a single project when the user asks for a specific component or when you know exactly which files changed.

First-Time Setup

A full init must be run once per flavor to download tools and NuGet packages. initrun.ps1 will fail with "Run a full init first" if this hasn't been done.

When you see that error, run a full init for the needed flavor:

.\init.ps1                # default: amd64chk
.\init.ps1 amd64fre       # specific flavor

Set initial_wait to at least 300 seconds — the first init downloads tools and restores NuGet packages.

Flavors: amd64chk, amd64fre, x86chk, x86fre, arm64chk, arm64fre (chk = debug, fre = release)

After init completes, retry the original initrun.ps1 build command.

If you get build errors that seem to indicate missing dependencies, that might mean you don't have a fresh "init".

Commands

Flags (for .\build.cmd)

What to Build After a Code Change

Test areas: controls, foundation, framework, automation

Terminology

MUX = Microsoft.UI.Xaml.dll (core XAML runtime)

MUXC = Microsoft.UI.Xaml.Controls.dll

Troubleshooting

error C3859: Failed to create virtual memory for PCH / error C1076: compiler limit: internal heap limit reached

Symptom: Build fails with dozens of PCH (precompiled header) virtual memory errors across multiple .cpp files. This typically happens when building with the default /m:4 parallelism on machines with limited memory.

Root Cause: Multiple parallel cl.exe compiler instances each try to allocate large PCH memory regions, exhausting the process address space.

Fix:

1. Use the /b flag in build.cmd which sets /m:2 (2 parallel processes):

``powershell .\initrun.ps1 .\build.cmd /q /b ``

1. If /b still fails, close other memory-intensive applications (browsers, VS instances, etc.).
2. If it keeps failing, stale PCH files from a previous build with a different compiler version may be the cause. Do a clean build:

``powershell .\initrun.ps1 .\build.cmd /q /c /b ``

error C1853: precompiled header file is from a different version of the compiler

Symptom: Build fails saying the .pch file is from a different compiler version.

Root Cause: Stale precompiled header files remain from a previous build with a different compiler (e.g., after a VS update).

Fix: Do a clean build with /c:

.\initrun.ps1 .\build.cmd /q /c /b

Missing Spectre mitigation libs

Symptom: Build errors about missing Spectre mitigation libraries from Visual Studio.

Fix: Tell the user to import the .vsconfig file from the repo root via Visual Studio Installer:

1. Open Visual Studio Installer
2. Click "More" → "Import configuration"
3. Select <repo-root>\.vsconfig
4. Install the missing components

DevEnvDir environment variable not set

Symptom: This message appears at the start of every initrun.ps1 command.

Root Cause: This is informational, not an error. initrun.ps1 automatically runs DevCmd.cmd to set up the VS environment.

Fix: No fix needed — this is normal behavior.