Sparkles

Appearance

Application-Packaging Concepts ​

The shared vocabulary for the survey. Packaging discussions become ambiguous when “build,” “package,” “installer,” and “release” are used as synonyms; this page assigns each operation a narrow meaning and connects it to concrete platform contracts.

Last reviewed: July 12, 2026

The verbs ​

Build ​

Build transforms source and declared inputs into target binaries/resources. It is compiler/linker work, not packaging: the output may still depend on paths or shared libraries unavailable on an end-user machine. Cross-platform orchestrators such as cargo-dist, GoReleaser, and JReleaser can drive or consume builds; CPack ordinarily consumes an install tree produced by the build system.

Stage ​

Stage materializes the exact filesystem tree a later package will consume, normally under a disposable root: executable, libraries, resources, license, completions, icons, and metadata at their final relative paths. Staging is where permissions and symlink targets become reviewable without yet invoking an installer database. An AppImage AppDir (linuxdeploy/appimagetool), a macOS .app directory (macOS bundles), and CMake's component install tree (CPack) are concrete stage trees.

Package and bundle ​

Package serializes a staged payload plus install metadata into a defined artifact format. A .deb, .rpm, MSI, MSIX, or PKG carries package-manager semantics, not only compression (Linux native packages, WiX/MSI, MSIX, macOS containers).

Bundle collects an application and selected runtime dependencies into a layout meant to execute together. Bundling answers “what travels with the program?”; packaging answers “what format and install contract contains it?” A .app is a bundle directory that may then be transported in a DMG or installed by a PKG (macOS bundles, macOS containers). AppImage, Python freezers, Electron tools, and jpackage combine both operations (AppImage, Briefcase, cx_Freeze, electron-builder, jpackage).

Sign ​

Sign computes a cryptographic signature over designated bytes and binds them to a publisher identity recognized by the verifier. Signing is format-specific and layered: Authenticode signs Windows executables/MSI/MSIX; Apple Code Signing seals nested code and the outer bundle/container; Linux repositories sign metadata and may also sign package files. Signing is not equivalent to transport encryption, malware review, or notarization (WiX/MSI, MSIX, macOS signing, Linux repositories). Because signatures cover bytes, signing must follow every byte-changing transformation it is meant to authenticate.

Notarize and staple ​

On macOS, notarize means submit a signed artifact to Apple's notary service for asynchronous automated checks and receive a ticket associated with its digest. It does not replace Developer ID signing. Staple means attach that ticket to a supported artifact so Gatekeeper can validate without reaching the service. The order is therefore bundle nested code → sign inside-out → package the submission → notarize → staple the accepted ticket; exact supported containers and commands belong to macOS signing/notarization. Stapling changes the outer artifact and must precede final checksums.

Publish and promote ​

Publish copies an immutable artifact and its metadata to a release host, repository, store, or catalog endpoint. Uploading a GitHub asset, pushing repository objects, and submitting a winget manifest are different publication operations (cargo-dist, Linux repositories, winget).

Promote changes channel/index reachability without rebuilding the payload—for example, advancing an already-verified digest from candidate to stable. Promotion preserves the “same bytes, more users” invariant; rebuilding for each channel destroys that property. Repository-native systems and updater feeds make this distinction explicit (Flatpak, Snap, Velopack, Conveyor).

Payload and manifest ​

A payload is the content delivered to the target: executables, dynamic libraries, resources, notices, and sometimes a runtime. A manifest is structured control data: identity, version, architecture, dependencies, install destinations, capabilities, entry points, checksums, and URLs. Formats vary in where they store it—Debian control members, RPM headers, AppImage desktop metadata, Flatpak manifests, MSI tables, MSIX AppxManifest.xml, macOS Info.plist, winget YAML—but payload and manifest remain separate conceptual layers (Linux native, AppImage, Flatpak, WiX/MSI, MSIX, macOS bundles, winget). A catalog manifest may contain no payload at all; winget, Scoop, and Homebrew casks commonly reference upstream artifacts (winget, scoop, homebrew).

Four delivery models ​

ModelPayload locationInstallation ownershipExemplars
Portablearchive/directory travels wholeuser or app; little/no system registrationWindows portable, archive releases from cargo-dist and GoReleaser
Bundlingapp carries selected runtime/depsbundle may run directly or sit inside an installerAppImage, macOS .app, Briefcase, cx_Freeze, jpackage
Native packagepackage payload installed into OS-defined locationspackage database owns files, repair/uninstall/upgrade.deb/.rpm/Arch, MSI, MSIX, PKG
Fetching installerbootstrap resolves payload at install/update timeinstaller/feed jointly own acquisition and stateConveyor, updater systems in Velopack

These models are not quality levels. Portable artifacts minimize installation side effects but cannot automatically supply a system package database's dependency, transaction, or policy semantics; native packages gain those semantics by accepting platform-specific metadata and review (artifact formats).

Identity, version, and upgrades ​

An artifact's filename is not its identity. Package managers compare a stable identifier and a format-specific version; installers also retain upgrade lineage:

  • Debian/RPM/Arch have distinct package names, epochs/releases, dependency grammars, and version comparators (Linux native).
  • MSI distinguishes ProductCode, PackageCode, component GUIDs, and UpgradeCode; changing the wrong identity can turn an upgrade into a side-by-side install or break servicing (WiX/MSI).
  • MSIX uses manifest identity and package-family semantics; signatures and publisher identity participate in trust and update compatibility (MSIX).
  • macOS bundles use a reverse-DNS CFBundleIdentifier and version keys; the signing designated requirement identifies code independently of the DMG filename (macOS bundles, macOS signing).

An upgrade replaces an installed identity according to that system's ordering and compatibility rules. An update channel is a named stream such as nightly, beta, or stable; it controls which signed metadata and versions a client sees. A rollback is an explicit move to an older known artifact, not merely “install a lower version,” which some systems reject. Repository/store clients own this most naturally; portable archives need a separate updater or manual replacement (Flatpak, Snap, Velopack, Conveyor).

Signing layers and trust boundaries ​

A release may need several independent signatures:

  1. Code/object signature — executable, library, .app, MSI/MSIX, or installer EXE.
  2. Container signature — the outer package/image where the format supports it.
  3. Repository metadata signature — authenticates the index that maps identity/version to payload digest and URL (Linux repositories).
  4. Transparency/provenance signature — authenticates a build statement or attestation, not installability itself (release pipeline).

Each answers a different question. A signed executable downloaded through an unsigned mutable index is still vulnerable to substitution unless the client verifies the object signature; a signed repository does not prove who compiled the binary; notarization is an external service verdict layered over Apple signing (macOS signing).

Key custody is part of the architecture: CI secrets, hardware/cloud signing services, short-lived identity, and platform credentials have different blast radii. The survey's orchestrators vary in whether they merely call platform signers or model the whole trust stage (cargo-dist, electron-builder, JReleaser, Conveyor).

Target triples, host triples, and universal binaries ​

A target triple identifies the machine/OS/ABI for generated code—commonly architecture-vendor-os-environment, though ecosystems normalize spellings differently. A host is the system running the build/package command. Cross-compilation answers whether host and target may differ; packaging adds a second constraint because native installer builders, SDKs, signers, and validators may require the target OS even when the compiler does not (comparison, platform gotchas).

A universal binary contains multiple architecture slices in one Mach-O file, commonly arm64 and x86_64; every nested executable/library must have compatible slices before an application is signed. A universal .app is not made by putting two unrelated app directories beside one another (macOS bundles, macOS signing). Windows multi-architecture delivery normally uses separate payloads or an MSIX bundle (MSIX); Linux repositories index architecture-specific packages (Linux repositories).

Checksums, SBOM, provenance, and reproducibility ​

A checksum detects byte changes and gives indexes a stable content identifier; it does not identify the producer unless delivered through an authenticated channel. An SBOM inventories components in a format such as SPDX or CycloneDX. Provenance records how an artifact was produced—source/material digests, builder identity, command or workflow context—often using an in-toto/SLSA statement. They are complementary: checksums bind bytes, SBOMs describe contents, provenance describes production (release pipeline, cargo-dist, GoReleaser, JReleaser).

A reproducible build yields bit-identical output for the same declared inputs. Determinism is format-sensitive: timestamps, file ordering, compression metadata, absolute paths, code signatures, notarization tickets, and installer database fields can all vary. “Built in Nix” means inputs are unusually well pinned; it does not by itself prove that a signed MSI, DMG, or AppImage is bit-reproducible. Reproducibility must be measured per final artifact (Sparkles baseline, platform gotchas).

Sources ​