Handbook
Powered by

Packages and deployment

XUI release assets support Windows x64 and ARM64. The tag release/1.2.3 produces package version 1.2.3. No extra build number is necessary. GitHub releases remain drafts until a maintainer publishes them. The workflow does not publish packages to a package registry.

XUI uses the MIT license. Both NuGet packages and both Cargo crates declare MIT in their package metadata. Each package, sample ZIP, and Designer ZIP contain the root LICENSE file. Third-party components retain their own license terms.

Each release includes Xui and Xui.Templates NuGet packages, xui-sys and xui Cargo crates, sample and Designer ZIPs, and SHA-256 checksums. The Xui download contains both native architectures, headers, static libraries, the C ABI runtime, .NET bindings, and the .xui compiler. Native C++ deployment does not include managed assemblies. The compiler is a build-time dependency, not part of release application output.

Create a project with dotnet new

The Xui.Templates package supplies the xui project template. The template requires Windows x64 or ARM64 and the .NET 10 SDK. It creates a C# desktop application with a declarative counter and Debug hot reload.

Download Xui.Templates.<version>.nupkg and Xui.<version>.nupkg from the same release. Place both files in D:\packages\xui. Replace 1.2.3 with the downloaded version:

dotnet nuget add source D:\packages\xui --name XuiLocal
dotnet new install D:\packages\xui\Xui.Templates.1.2.3.nupkg
dotnet new xui -n MyApp
cd MyApp
dotnet run

If the local source already exists, omit the dotnet nuget add source command. The release workflow does not publish either package to NuGet.org. After a maintainer publishes both packages to a configured feed, dotnet new install Xui.Templates::<version> can replace the local installation command.

dotnet new xui uses the current directory name. -n MyApp creates a MyApp directory, and -o <directory> selects an explicit destination. Project names also replace the C# and .xui namespaces. The template does not restore packages during generation. The first build or run restores the exact Xui version that matches the template package.

The project selects the host Windows architecture. dotnet run -r win-x64 or dotnet run -r win-arm64 overrides that selection. Counter.xui contains the layout, state, and click handler. Program.cs creates the window and selects the Debug hot-reload host.

Use dotnet watch for development. Use dotnet publish -c Release -r win-x64 --self-contained true for a self-contained x64 deployment. Replace win-x64 with win-arm64 for ARM64. The package supplies the application manifest and native runtime without repository imports. Release builds exclude the development host. XuiHotReload=false also disables the host in Debug builds.

To remove the template:

dotnet new uninstall Xui.Templates

.NET applications

The package requires the .NET 10 SDK. After download, place the .nupkg in a local NuGet source:

dotnet nuget add source D:\packages\xui --name XuiLocal
dotnet add package Xui --version 1.2.3

A minimal application project uses:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Xui" Version="1.2.3" />
  </ItemGroup>
</Project>

win-arm64 selects ARM64 instead. The SDK copies the matching native DLL into build and publish output. No repository checkout or XUI entry in PATH is necessary. The package processes .xui files and supplies the native-control manifest. An explicit ApplicationManifest overrides that manifest.

Managed Debug builds include Xui.Development and define XUI_HOT_RELOAD. XuiHotReload=false disables that integration. Release and NativeAOT builds exclude the development host. The language guide describes component authoring and reload behavior.

Native C++ applications

The native NuGet targets support Visual C++ projects with platform x64 or ARM64. The default XuiNativeLinkage=Static links xui_windows.lib and xui_core.lib. It selects C++20, Unicode definitions, the application manifest, and the static MSVC runtime (/MT). Only the application and its own dependencies belong in deployment. Neither .NET nor xui.dll is necessary for this mode.

The package supplies Release static libraries only. Debug applications can build XUI from source or use XuiNativeLinkage=CAbi. The C ABI mode links xui.lib and copies xui.dll beside the executable. It does not expose the C++ class API through that DLL. The binding reference describes the C ABI contract. The shared-styling consolidation requires ABI version 2 (0x00020000). Rebuild applications and deploy matching managed/Rust bindings and the native DLL together; a version-1 runtime is not a compatible substitute.

For CMake, extract the NuGet archive and use its package configuration:

cmake_minimum_required(VERSION 3.24)
project(MyApp LANGUAGES C CXX)
set(CMAKE_MSVC_RUNTIME_LIBRARY MultiThreaded)
find_package(Xui CONFIG REQUIRED)
add_executable(my_app WIN32 main.cpp)
target_link_libraries(my_app PRIVATE Xui::Windows)
target_compile_options(my_app PRIVATE /utf-8 /EHsc)
target_link_options(my_app PRIVATE "/MANIFEST:EMBED" "/MANIFESTINPUT:${Xui_MANIFEST}")

Xui_DIR must identify the extracted build\native directory. Xui::Core, Xui::Windows, and Xui::CAbi are imported targets. The C++ static targets require Release-compatible MSVC runtime and iterator-debug settings. For the C ABI target, copy $<TARGET_FILE:Xui::CAbi> beside the executable.

Rust applications

xui supplies the safe wrapper. xui-sys supplies the C ABI declarations. The crates use the same version, and the wrapper requires that exact xui-sys version. Release xui-sys archives contain the native DLL and import library for both Windows MSVC targets. An extracted crate selects its native files from Cargo's target triple. XUI_LIB_DIR explicitly overrides that selection. No native download occurs during a consumer build.

The release attaches crates but does not register them on crates.io. For local consumption, extract both archives into a vendor directory:

[dependencies]
xui = { path = "vendor/xui-1.2.3" }

[patch.crates-io]
xui-sys = { path = "vendor/xui-sys-1.2.3" }

Both extracted crates retain the release version. The application must deploy the selected xui.dll beside its executable. Cargo does not provide a general transitive DLL-copy hook for arbitrary application outputs. The release script copies the DLL for the repository's Rust sample. The binding guide describes the API and ownership rules.

Source development

Repository .NET samples copy the native DLL from this checkout's build\<architecture>\Release directory. The sample architecture defaults to the host Windows architecture. RuntimeIdentifier selects win-x64 or win-arm64. XuiNativeConfiguration selects another native configuration, and XuiNativeDir overrides the complete directory. A missing DLL causes a build error instead of a runtime loader failure. Build and publish use the same native source.

The DLL remains a separate native build. A managed rebuild copies its latest output but does not compile native sources. The contributor guide contains the commands.

Sample archives

The release supplies Xui.Samples.<version>.win-x64.zip and Xui.Samples.<version>.win-arm64.zip. Each ZIP contains only its named architecture, with native, dotnet, and rust directories at the archive root. The .NET samples are Sample, DeclarativeSample, FileExplorer, and Minesweeper. TaskCard remains a source tutorial but does not ship in the archives.

The .NET samples use size-optimized NativeAOT executables, so a separate .NET installation is unnecessary. Each executable contains its required runtime code instead of a separate copy of the full .NET runtime. The archives omit .NET debug symbols and development tools. Each sample retains its own directory and native DLL, so it can run independently. Each .NET sample also includes the .NET license and third-party notices from its resolved runtime and compiler packages.

The native and Rust builds use the static C runtime. The package excludes optional WebView2 support.

Each application runs from its extracted directory without an XUI entry in PATH. Windows system components remain prerequisites. Each archive includes a versioned file manifest with SHA-256 hashes. Release procedures are in CONTRIBUTING.

Designer archives

The release supplies Xui.Designer.<version>.win-x64.zip and Xui.Designer.<version>.win-arm64.zip. Each archive contains Designer.exe, the matching XUI native runtime, the .NET runtime, and the compiler for live previews. No separate .NET runtime or SDK installation is necessary. The archive also includes the XUI and .NET licenses, third-party notices, and a versioned file manifest with SHA-256 hashes.

Extract the complete archive for your Windows architecture. Run Designer.exe from the extracted directory. Keep all supplied files and directories beside the executable. Open only trusted .xui files.

The Designer compiles and runs authored C# in its own process. It is not a sandbox. Its deployment uses managed, untrimmed, multi-file output instead of NativeAOT. These separate archives do not add the Designer or its runtime to the NativeAOT sample ZIPs. The Designer guide describes its editor and preview behavior.