Skip to content

GettingStarted.md

Latest commit

 

History

History
282 lines (220 loc) · 11.3 KB

GettingStarted.md

File metadata and controls

282 lines (220 loc) · 11.3 KB

Getting started with building WinUI from GitHub

Important

The WinUI OSS effort is still in progress. See the WinUI OSS Update post to check the latest status. Also see Current limitations.

Preparing your environment

To build WinUI, you need to set up your development environment and clone the WinUI repository. Follow these steps:

  1. Install Git for Windows from git-scm.com, if you don't already have it.

  2. Clone the WinUI repository. It is recommended to clone into a short path, such as C:\winui3:

    git clone https://github.com/microsoft/microsoft-ui-xaml.git C:\winui3
cd C:\winui3

  3. Switch to the winui3/main branch:

    git checkout winui3/main

  4. Install the necessary MSBuild / Visual Studio 2022 dependencies. If you already have VS 2022 (see notes) installed, this command will ensure you have the required components:

    cd C:\winui3\src
.\OneTimeSetup.cmd -Install MSBuild

    Click the various "Yes", "Continue", and "Modify"/"Install" buttons as needed to complete the installation. When installation completes, close the Visual Studio Installer window.

Building WinUI

Starting with a command prompt or PowerShell at the root of your WinUI repo:

  1. Switch into the src directory:

    cd src

  2. Initialize to build (details):

    init.cmd

    Or, for PowerShell:

    .\init.ps1

    Note: Package restore errors are currently expected for a few projects: Microsoft.UI.DCPP.Dependencies.Edge, Microsoft.Taef, and Microsoft.Windows.TestInProduction. These packages are not required to build the WinUI product binaries. You can ignore these errors for now. They will be addressed in future changes. See the WinUI OSS Update post for more details and updates on the OSS rollout.

  3. Build the project:

    .\build.cmd

If the build was successful, the output should show this at the end:

---
BUILD SUCCEEDED.
---

See below for more information on investigating build failures.

To do a clean build, you can run add a /c parameter:

.\build.cmd /c

Build output

After a successful build, you can find the product binaries in the output packaging folder %BuildArtifactsDir%\packaging\%Configuration%\runtimes\win10-%Platform%\native. For example:

C:\winui3\src>dir %BuildArtifactsDir%\packaging\%Configuration%\runtimes\win10-%Platform%\native
 Directory of C:\winui3\src\BuildOutput\packaging\Debug\runtimes\win10-x64\native

Microsoft.Internal.FrameworkUdk.dll
Microsoft.UI.Xaml
Microsoft.UI.Xaml.Controls.dll
Microsoft.UI.Xaml.Controls.pri
Microsoft.ui.xaml.dll
...

Using the built WinUI binaries in your own project

To use the built WinUI binaries in your own project, you can either copy the built binaries into your project's output folder after building your project, or you can build against the component package built as part of the WinUI build.

Option 1: Copying built binaries into your project output folder

In this option, you would copy the built WinUI binaries from the output packaging folder to your project's output folder after building your project. To do this, start with an app which is both unpackaged and self-contained. This can be done by setting the following properties in your app's project file:

  <PropertyGroup>
    <WindowsPackageType>None</WindowsPackageType>
    <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
  </PropertyGroup>

Build the project using WindowsAppSDK 2.0-experimental3, then replace the WinUI binaries in the output folder of your app with the ones you built from source. You can then just run your app as normal to use the WinUI binaries you built.

You could also set up a post-build step in your app project to do this copy automatically. For example, you could add a target to your project file that runs after the build completes:

  <Target Name="CopyWinUIBinaries" AfterTargets="Build">
    <ItemGroup>
      <WinUIBinaries Include="C:\winui3\src\BuildOutput\packaging\Debug\runtimes\win10-$(Platform)\native\**\*.*" />
    </ItemGroup>
    <Copy SourceFiles="@(WinUIBinaries)" DestinationFolder="$(OutputPath)" />
  </Target>

Update the path in the Include attribute to point to your WinUI build output folder.

Option 2: Referencing the built Microsoft.WindowsAppSDK.WinUI package

In this option, you would reference the Microsoft.WindowsAppSDK.WinUI NuGet package built as part of the WinUI build process. To do this, start with any app (either packaged or unpackaged), and add this nuget.config file to the root of your app project (next to your .csproj or .vcxproj file):

<configuration>
  <config>
    <clear />
    <add key="globalPackagesFolder" value="$\..\packages" />
    <add key="repositoryPath" value="$\..\packages" />
  </config>
  <packageSources>
    <add key="packagestore" value="C:\winui3\src\PackageStore" />
  </packageSources>
</configuration>

Update the path in the packagestore value to point to the PackageStore folder in your WinUI repo.

Adding this config does two things. First, it adds the location of the 'PackageStore' directory from your local WinUI repo to the list of locations that nuget.exe will search for packages. This will allow the Visual Studio project to target this local build.

Second, it updates nuget to cache all its packages in the app folder instead of using the global package cache from the machine (e.g. C:\Users\alias\.nuget\packages). This makes it easier to update the package and avoids caching it globally where it may affect other projects.

Update the Package References

In Visual Studio, use Tools -> Nuget Package Manager -> Manage Nuget Packages for Solution. Make sure you have the Include prerelease checkbox checked to ensure that the local package shows up. Select and uninstall all Microsoft.WindowsAppSDK.* packages other than Base, Foundation, InteractiveExperiences, and WinUI. Select Microsoft.WindowsAppSDK.WinUI and install your local package, which should be version 3.0.0-dev.

If you prefer, instead of using the UI, you can also do this by modifying the .csproj to remove any <PackageReference> element for the full Microsoft.WindowsAppSDK package and then add or update a <PackageReference> element for Microsoft.WindowsAppSDK.WinUI, like this:

  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK.WinUI" Version="3.0.0-dev" />
  </ItemGroup>

Rebuild and launch your app with F5.

Picking up new WinUI builds

Each time you do a new build of WinUI from source, you will need to delete the packages\microsoft.windowsappsdk.winui folder from your app project folder to force NuGet to restore the updated package.

Current limitations

The WinUI OSS effort is still in progress. Phase 2 of the plan outlined in the WinUI OSS Update post is now complete and Phase 3 is underway. Current limitations include:

  • Only the product binaries1 can be built. No tests or samples can be built yet, including the test code already in the repo in the controls\ subtree.
  • Related to the previous, various sln files and project files in the repo cannot yet be built, including Microsoft.UI.Xaml.sln (Microsoft.UI.Xaml.OSS.sln is available instead) and MUXControls.sln.
  • The product binaries built from source cannot yet be easily used during an app build without manually replacing the binaries in the app output folder as described above.
  • The XAML Compiler is not yet fully shared and therefore isn't buildable. The build uses a prebuilt version instead.
  • Most unittest and integration test code is not yet open sourced, so cannot be built or run.
  • There is no support yet to run any builds/tests in a CI system.

Additional Info

Initialize CMD or PowerShell with support for VS build tools

At the CMD prompt, in the src\ folder off the root of the repo, run (for an x64chk build):

init.cmd

Or in PowerShell, run:

.\init.ps1

Note: If you get an error saying it can't find msbuild, this is likely due to a pending Visual Studio update. To see if this is the case, try launching Visual Studio -- you may see a message saying it needs to reboot to finish updating. If so, try that first, then retry the init command.

This script restores NuGet packages and initializes your build environment with the proper environment variables for specifying which platform and configuration you are building.

Any time you do a git pull you also need to re-run init.cmd

The default environment is x64 Debug. Below is a list of other possible Platform/Configuration combinations and the init command that sets them up.

Platform Configuration Init command
x86 Debug init.cmd x86chk
x86 Release init.cmd x86fre
x64 Debug init.cmd
x64 Debug init.cmd x64chk
x64 Release init.cmd x64fre
arm64 Debug init.cmd arm64chk
arm64 Release init.cmd arm64fre

Build failures

Build output prints to screen, as well as to a .binlog file. To see this output in a more human readable form, use the MSBuild Log Viewer.

error C1076: compiler limit: internal heap limit reached / error C1060: compiler is out of heap space

These errors occasionally happen during the build of Microsoft.UI.Xaml.Controls.vcxproj:

error C1076: compiler limit: internal heap limit reached
error C1060: compiler is out of heap space

One option is to simply retry an incremental build by running build.cmd again. This simple approach often works, but it may take multiple attempts.

Another option, which is more reliable, is to limit the number of parallel compiler processes by setting the CL environment variable before building. For example, in CMD:

set CL=/MP2

And then run the build again with build.cmd.

Install MSBuild Log Viewer

When investigating build failures, the MSBuild Structure Log Viewer can be very helpful. This tool makes the build output (logs, errors, etc) much more readable, by presenting the .binlog produced by the build in a human readable way. The link above provides a download link as well as some basics of how to use the tool. Or you can install the tool by running the following command at the root of the repo:

.\OneTimeSetup.cmd -Install LogViewer

Other notes

  • WinUI currently still assumes Visual Studio 2022. This project has not yet been tested with Visual Studio 2026.

Footnotes

  1. The product binaries built by this repo are the Microsoft.UI.Xaml.*.dll files, excluding Microsoft.UI.Xaml.Internal.dll (which will not be OSS). ↩