Packaging

This guide gets your app ready for the Microsoft Store ↗, which lists your app, installs it for users, and delivers every update you publish. The Store accepts desktop apps in a single format, MSIX ↗: an archive holding your executable, its assets, and a manifest describing the app to Windows.

Note

MSIX also works outside the Store, but it isn’t the only option. WiX ↗ and other MSI authoring tools, installers such as Inno Setup ↗ and NSIS ↗, and a plain .zip all distribute a Windows app. Packaging your application in these formats is outside the scope of this documentation.

Prerequisites

Install the Windows SDK ↗. It comes with makeappx, which builds the package, and makepri, which builds the resource index it needs.

The Manifest

An AppxManifest.xml at the root of the package describes it. This is the smallest manifest that you need for a Slint app:

<?xml version="1.0" encoding="utf-8"?>
<Package
    xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
    xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
    xmlns:uap10="http://schemas.microsoft.com/appx/manifest/uap/windows10/10"
    xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
    IgnorableNamespaces="uap uap10 rescap"
>
  <Identity
      Name="YourOrganization.YourApp"
      Publisher="CN=YourOrganization"
      Version="1.0.0.0"
      ProcessorArchitecture="x64"
  />
  <Properties>
    <DisplayName>Your App</DisplayName>
    <PublisherDisplayName>Your Organization</PublisherDisplayName>
    <Logo>Assets\StoreLogo.png</Logo>
  </Properties>
  <Dependencies>
    <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26100.0" />
  </Dependencies>
  <Resources>
    <Resource Language="en-us" />
  </Resources>
  <Applications>
    <Application
        Id="YourApp"
        Executable="your-app.exe"
        uap10:TrustLevel="mediumIL"
        EntryPoint="Windows.FullTrustApplication"
    >
      <uap:VisualElements
          DisplayName="Your App"
          Description="What your app does"
          BackgroundColor="transparent"
          Square150x150Logo="Assets\Square150x150Logo.png"
          Square44x44Logo="Assets\Square44x44Logo.png"
      />
    </Application>
  </Applications>
  <Capabilities>
    <rescap:Capability Name="runFullTrust" />
  </Capabilities>
</Package>

xml

Full Trust

A packaged app runs in an app container by default, in a sandbox, with its own storage and all of its capabilities. In contrast, a full trust app runs on a user level, with the same access as an unpackaged app.

Slint apps need full trust so that they can access files that the user selects, access the GPU to render, and call Win32 APIs.

In your manifest, the following three parts are necessary to declare full trust:

• EntryPoint="Windows.FullTrustApplication" marks the app as an ordinary executable.
• uap10:TrustLevel="mediumIL" runs the process as the user.
• runFullTrust is the required capability.

Asset Paths

Every path in the manifest is relative within the package.

The Visual C++ Runtime

Binaries built with the MSVC toolchain link the C runtime dynamically, and the Skia renderer adds the C++ standard library on top. Both ship with the Visual C++ redistributable ↗. If you are working with a fresh Windows installation, make sure that you have the Visual C++ runtime installed.

Declare a dependency on the framework package that carries the libraries, and Windows installs the runtime alongside your app:

<Dependencies>
  <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26100.0" />
  <PackageDependency
      Name="Microsoft.VCLibs.140.00.UWPDesktop"
      MinVersion="14.0.30704.0"
      Publisher="CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US"
  />
</Dependencies>

xml

Tip

dumpbin /dependents your-app.exe lists everything your executable imports. MSVCP140.dll and VCRUNTIME140.dll come from the redistributable, while the api-ms-win-crt-* entries are part of Windows.

Building the Package

Create a directory that has what your package needs, then pack it:

# layout/
#   AppxManifest.xml
#   your-app.exe
#   Assets/...

makeappx pack /d layout /p YourApp_1.0.0.0_x64.msix /o

powershell

This completes a single architecture. The result is unsigned, as the Store requires, and can’t be installed yet.

Supporting Both x64 and arm64

Windows on Arm runs x64 binaries through emulation. A native arm64 build is faster and takes little effort. Build the executable for each architecture, assemble one layout per architecture with ProcessorArchitecture set accordingly in each manifest, pack each one, then combine them:

makeappx bundle /d slices /p YourApp_1.0.0.0_arm64_x64.msixbundle /bv 1.0.0.0 /o

powershell

Everything except ProcessorArchitecture must be identical between the slices; we recommend generating each manifest from one template.

Icons

The manifest names one file per logo, and Windows selects among variants of that file by the size required and the context.

To produce the icon variants, follow these steps:

1. Render the small logo at each size Windows uses: 16, 24, 32, 48, and 256. Name each one with a targetsize qualifier.

2. Add an unplated variant of every size. These hold the bare mark on transparency, and Windows draws them without a plate: altform-unplated ↗ on dark taskbars, altform-lightunplated on light ones.

Assets/Square44x44Logo.png                                      # named in the manifest
Assets/Square44x44Logo.targetsize-48.png
Assets/Square44x44Logo.targetsize-48_altform-unplated.png       # dark backgrounds
Assets/Square44x44Logo.targetsize-48_altform-lightunplated.png  # light backgrounds

plaintext

Those suffixes are resource qualifiers ↗: a . separates the file name from the first qualifier, and _ separates any further ones.

3. Build a resource index, which is what resolves those qualifiers.

makepri createconfig /cf priconfig.xml /dq en-US /o
makepri new /pr layout /cf priconfig.xml /of resources.pri /o
Copy-Item resources.pri layout\resources.pri

powershell

Keep priconfig.xml outside the layout, otherwise it’s indexed and packaged with everything else.

Signing

The Store re-signs your package with a Microsoft certificate, so leave a package destined for it unsigned. You don’t need a code signing certificate to publish there.

For distribution outside the Store, Windows won’t install a package it doesn’t trust, and the certificate’s subject must match Identity/Publisher in your manifest exactly. For more information, see signing a package with SignTool ↗.

Testing Without Signing

You don’t need a certificate during development. With Developer Mode ↗ enabled, Windows registers a package directly from a directory:

Add-AppxPackage -Register layout\AppxManifest.xml

powershell

The app appears in the Start menu and runs with its real package identity. That matters for testing: framework dependencies such as the C++ runtime reach the DLL search path only when the app starts through its identity. Remove it again with:

Get-AppxPackage YourOrganization.YourApp | Remove-AppxPackage

powershell

Tip

You may run into two types of issues.

• 0x80070005 (access denied) usually means the deployment service can’t read your layout. Grant it access:

icacls layout /grant "*S-1-15-2-1:(OI)(CI)(RX)" /T

powershell

• 0x80073D2C means the publisher isn’t in the unsigned namespace. Add-AppxPackage -AllowUnsigned only accepts packages whose Publisher carries a special OID ↗ marking them as unsigned, so you can’t use it with a real publisher identity. Register the layout as above, or sign the package.