Skip to main content

Packaging and releases

Packaging/ contains the maintained release entry points. Each publisher creates packages from one self-contained publish containing the Hyprism Launcher and the separate Local Node apphost

The Desktop project keeps Hyprism.Desktop as its assembly identity for Avalonia resource URIs. Ordinary dotnet build, dotnet run, and dotnet publish use the SDK's default apphost name, Hyprism.Desktop (Hyprism.Desktop.exe on Windows)

The platform publishers rename the published native apphost to Hyprism Launcher (Hyprism Launcher.exe on Windows) before signing or creating packages. The Nix flake exposes the launcher under that name after creating its executable wrappers. These packaging steps leave the managed assembly and embedded resource paths unchanged

Platform targets​

HostRuntimeTargets
Linuxlinux-x64deb, rpm, appimage, flatpak, tar, nix
Windowswin-x64zip, msi, exe
macOSosx-arm64dmg

Use a matching host for packaging. Native publishers accept all and --output; output defaults to dist

Linux​

Install the tools needed by your selected targets: dpkg-deb, rpmbuild, appimagetool, flatpak, and flatpak-builder

./Packaging/publish-linux.sh deb rpm tar --output dist
./Packaging/publish-linux.sh all --output dist

The all target builds DEB, RPM, AppImage, Flatpak, and tar.xz artifacts. Build the Nix target explicitly because it is supplied by the flake and stored in /nix/store

AppImage tooling can be selected with --appimagetool or APPIMAGETOOL. Flatpak exports and bundles use the stable branch

The Flatpak bundle currently uses Avalonia's X11 backend through XWayland, so its manifest grants --socket=x11 and does not grant the conditional fallback-x11 or native wayland sockets. This keeps KDE Plasma Wayland launches working until native Wayland is enabled in the desktop host

Linux packages preserve the source artwork from logo.svg and publish it in a square SVG viewport required by application icon validators

Nix​

The repository contains a flake for the native x86_64-linux package. Install Nix with flakes enabled, then build or run Hyprism from the repository root or from a release tag

nix build ./Packaging/linux/flake#hyprism
nix run ./Packaging/linux/flake#hyprism
./Packaging/publish-linux.sh nix

The flake pins nixpkgs and restores NuGet dependencies from Packaging/linux/flake/nix/deps.json. Update that file when .NET package references change

The package exposes hyprism as its stable command name and includes both the Hyprism Launcher and separate Hyprism.LocalNode executables in the result

Nix stores the result in /nix/store; the --output option applies only to native package targets

To regenerate the NuGet dependency lockfile, build the helper exposed by the package and run it with the lockfile path

nix build ./Packaging/linux/flake#hyprism.fetch-deps
./result ./Packaging/linux/flake/nix/deps.json

Windows​

The publisher installs pinned WiX tooling in a temporary directory for MSI and EXE packaging

pwsh Packaging/publish-windows.ps1 all --output dist

It verifies Hyprism Launcher.exe and the separate Hyprism.LocalNode.exe before producing artifacts. ZIP contains the same application payload as the installers

The MSI installs into Program Files\Hyprism for all users and owns the shared desktop and Start menu shortcuts. Both shortcuts target Hyprism Launcher.exe, use the installation directory as their working directory, and are removed by Windows Installer during uninstall. The EXE bootstrapper chains the same MSI. The launcher executable is authored explicitly in Packaging/windows/Hyprism.msi.wxs and excluded from wildcard file harvesting so it is packaged only once.

The Windows build workflow runs Scripts/test-windows-installers.ps1 after packaging. It installs and uninstalls both MSI and EXE packages, checks that both shared shortcuts resolve to the installed launcher, and verifies cleanup. Installer logs are uploaded as a separate artifact. To repeat this check, use an elevated PowerShell session on a disposable Windows machine without an existing Hyprism installation.

pwsh Scripts/test-windows-installers.ps1 -ArtifactDirectory dist

The Windows apphost uses the multi-size Sources/Hyprism.Desktop/Assets/Images/Hyprism.ico resource. WiX uses the same icon for the MSI entry in Apps and Features and the EXE bootstrapper

macOS​

The macOS app bundle includes the generated Packaging/macos/Hyprism.icns icon derived from logo.svg and uses Hyprism Launcher as its executable and display name. The macOS publisher uses plutil, hdiutil, codesign, and file

./Packaging/publish-macos.sh dmg --output dist

It builds an Apple Silicon app bundle, checks both the Hyprism Launcher and Local Node apphost architectures, applies an ad hoc signature, verifies it, and creates a DMG. Ad hoc signing is not notarization

Version source​

Version in Sources/Hyprism.Desktop/Hyprism.Desktop.csproj is the release version source. Publishers query it through MSBuild

dotnet msbuild Sources/Hyprism.Desktop/Hyprism.Desktop.csproj \
-nologo -getProperty:Version

A release tag must equal v<Version>. The release workflow rejects a mismatched tag before packaging

Release assets and integrity​

The release workflow uploads platform packages and version.json for the auto-updater. GitHub calculates each uploaded asset's SHA-256 digest and returns it in the digest field of the release assets API. The workflow does not publish separate checksum files.

The command-line installers fetch the latest release metadata from the GitHub API, select the package by its exact filename, and verify its SHA-256 digest before extracting or mounting it. The download URL uses the version from the same API response. A missing or invalid digest or a hash mismatch stops installation. Linux and macOS installers use awk to extract the release tag and asset fields; Windows uses PowerShell's built-in JSON support. No additional JSON tool is required.

CI ownership​

WorkflowResponsibility
ci.ymlCore, Desktop, Local Node, and Packaging check groups
test-core.yml, test-desktop.yml, test-local-node.ymlSeparate Ubuntu, Windows, and macOS test matrices
build.ymlPlatform dispatcher
build-linux.yml, build-windows.yml, build-macos.ymlPlatform dependencies, Nix validation, and publisher calls
release.ymlVersion validation, shared package builds, release assets
docs-pages.ymlDocumentation validation and GitHub Pages deployment
reuse.ymlLicense headers and REUSE compliance

The separate Flathub workflow and Scripts/update-flathub-manifest.sh contain legacy Electron/frontend paths. They are not the maintained native packaging entry point and require migration before reuse

The Linux build workflow publishes the native Linux packages and runs nix flake check --print-build-logs for the Nix package in the same job. In ci.yml, the Packaging group waits for the Core, Desktop, and Local Node test workflows

Source: Packaging, GitHub Actions

Edit this page on GitHub