# 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](https://github.com/zadjii-msft/xui/blob/9e6673cffbb2f4fb320da652937729f1b7a03099/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:

```powershell
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:

```powershell
dotnet new uninstall Xui.Templates
```

## .NET applications

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

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

A minimal application project uses:

```xml
<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](xui-language.md) 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](bindings.md) 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
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:

```toml
[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](bindings.md#rust-ownership-and-use) 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](../contribute-and-explore-designs/contributing.md#c-and-declarative-samples) 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](../contribute-and-explore-designs/contributing.md#release-packages).

## 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](../samples/designer.md) describes its editor and preview behavior.