native-packages 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef21c207476e3d19df85ebdb463eb0ccfb020ab8a4fd8ead551a22c4c2d4de62
-  data.tar.gz: 1648f4ffa1698dfdccea0d3693943e696b2810c69f595bf48fa01c386346808d
+  metadata.gz: 7991d9fd47977d5eda80c98ee460ef7c401b4db6eae41a74d285c58576bbb089
+  data.tar.gz: 943a2ff5686edd0cfaa7f09fd9a213d797f4a628cf5eff9331127f84840c06c8
 SHA512:
-  metadata.gz: f3cea3ca8d3d79956a0cca4ca779955b901795b1000a4ef57cad97abebfc32721d678df435ba8a46c2e226a210fdcb92f6c7cac586f81cc416ed5e8028ee300f
-  data.tar.gz: 2e6c2eaffc5cdab5cb3ef8ad3969b7058880cabb155f56170955f309d7b2e11701a384ac291f889cc5717d565b7073f1ec75edd51984b25554bad00e2564ec20
+  metadata.gz: 2ac16d8c7b639da77db270af088839ab3e6ecbb6b913086208f26dc95db69b843df11c887ad556c744f493b5fe8ea85660095b9a5eff8425821daabb7b850330
+  data.tar.gz: '094cba93dda2a8dbb0442d3b88d0efe5039ec28f715fdd85763e6dcdd56fde1b2a013813fbcf514930240dc874b31fcc562381c304c8e710a303e3bbe1d1e255'

data/CONTRIBUTING.md

@@ -18,7 +18,7 @@ To check the packaged gem and standalone command:
 
 ```sh
 gem build native-packages.gemspec
-ruby test/gem_install.rb native-packages-0.8.1.gem
+ruby test/gem_install.rb native-packages-0.10.0.gem
 ```
 
 See [Releasing the gem](docs/releasing.md) for publication and
@@ -49,6 +49,10 @@ path dependency. To test changes from a local theme checkout, use Bundler's
 temporary path configuration or a separate Gemfile, and keep that local setup
 out of the committed lockfile.
 
+Social previews use the launch-film poster, configured under
+`jekyll_vitepress.seo.image` in `docs/_config.yml`. Keep it a JPEG or PNG with
+matching width, height, and alt text; the SVG logo is for the site itself.
+
 ### Writing a guide
 
 Put tutorials in `docs/_guides/` and reference pages in `docs/_reference/`.

data/README.md

@@ -13,6 +13,8 @@ Homebrew casks.
 
 You bring the compiled app. native-packages handles packaging and release updates.
 
+https://github.com/user-attachments/assets/e3157514-570d-47b3-a2e9-aca70042a138
+
 [Documentation](https://native-packages.dev/)
 
 ## Get started
@@ -50,10 +52,10 @@ record. Local builds work without a GitHub release or credentials.
 | --- | --- |
 | Linux | DEB, RPM, AppImage, Arch Linux packages, Alpine APK, IPK, and source RPM |
 | macOS | DMG, using your packaging script; optional Apple signing and notarization |
-| Windows | MSIX, or Inno Setup installers using your packaging script |
+| Windows | MSIX, or MSI and Inno Setup installers using your packaging script |
 
-Each target needs files built for that platform. DMG and Inno builds run on
-macOS and Windows respectively. See [supported platforms](docs/_reference/platforms.md)
+Each target needs files built for that platform. DMG builds run on macOS;
+MSI and Inno builds run on Windows. See [supported platforms](docs/_reference/platforms.md)
 for prerequisites and distribution recipes.
 
 ## Guides

data/docs/_guides/getting-started.md

@@ -17,7 +17,7 @@ own compiled executable, or build the tiny example below.
 You need Ruby 3.2 or later. Install the version used by these guides:
 
 ```sh
-gem install native-packages --version 0.8.1
+gem install native-packages --version 0.10.0
 ```
 
 For Linux packages, install **nFPM 2.47.0**, the helper native-packages uses to
@@ -79,7 +79,7 @@ Open the generated `native-packages.yaml` and replace its contents with:
 ```yaml
 schema: 1
 tool:
-  version: '0.8.1'
+  version: '0.10.0'
   nfpm: '2.47.0'
 
 nfpm:

data/docs/_guides/github-actions.md

@@ -24,7 +24,7 @@ packaging:
   needs: release
   permissions:
     contents: write
-  uses: crmne/native-packages/.github/workflows/package.yml@v0.8.1
+  uses: crmne/native-packages/.github/workflows/package.yml@v0.10.0
   with:
     version: ${{ github.ref_name }}
     publish: true
@@ -39,7 +39,7 @@ The configuration must include `release.repository` and a `release_asset`
 for each selected target. See [Publishing a release](publishing.md).
 
 Use the same native-packages release for the workflow and `tool.version`.
-For an immutable workflow reference, replace `v0.8.1` with that release's
+For an immutable workflow reference, replace `v0.10.0` with that release's
 full commit SHA.
 
 ## Build without publishing
@@ -57,7 +57,7 @@ permissions:
   contents: read
 jobs:
   packaging:
-    uses: crmne/native-packages/.github/workflows/package.yml@v0.8.1
+    uses: crmne/native-packages/.github/workflows/package.yml@v0.10.0
 ```
 
 Validation does not compile the app or check that future release inputs exist.
@@ -72,7 +72,7 @@ packaging:
   needs: build
   permissions:
     contents: write
-  uses: crmne/native-packages/.github/workflows/package.yml@v0.8.1
+  uses: crmne/native-packages/.github/workflows/package.yml@v0.10.0
   with:
     version: '1.2.3'
     source-artifact: linux-binaries
@@ -101,7 +101,7 @@ The workflow passes the same target selection to build and publication.
 It requires every format declared for those targets. An empty selection
 means all configured targets.
 
-Build DMG and Inno targets in your own macOS and Windows jobs with the CLI.
+Build DMG, MSI and Inno targets in your own macOS and Windows jobs with the CLI.
 See [Building across platforms](multi-platform.md) for combining their outputs
 and generating recipes after all packages are available.
 

data/docs/_guides/native-recipes.md

@@ -1,17 +1,17 @@
 ---
 title: macOS and Windows installers
-description: Connect your DMG or Inno Setup script to the same build and publication process as your Linux packages.
+description: Connect your DMG, MSI or Inno Setup script to the same build and publication process as your Linux packages.
 nav_order: 5
 ---
 
 # macOS and Windows installers
 
-This guide shows how to connect an existing DMG or Inno Setup script to
+This guide shows how to connect an existing DMG, MSI or Inno Setup script to
 native-packages. You supply a built app and a packaging script. The build
 command checks the app, runs your script, and records the finished installer's
 checksum.
 
-Build **DMGs on macOS** and **Inno installers on Windows**. These targets use
+Build **DMGs on macOS** and **MSI or Inno installers on Windows**. These targets use
 your native tools and do not need an nFPM executable.
 
 ## Prepare your app
@@ -31,7 +31,7 @@ Here is a complete configuration for an ARM64 Mac app and an x86-64 Windows app:
 ```yaml
 schema: 1
 tool:
-  version: '0.8.1'
+  version: '0.10.0'
   nfpm: '2.47.0'
 nfpm:
   name: hello
@@ -54,15 +54,18 @@ targets:
   windows-amd64:
     platform: windows
     arch: amd64
-    formats: [inno]
+    formats: [msi]
     input:
       kind: directory
       local: dist/windows
     native:
-      command: [ruby, packaging/setup.rb, '@PAYLOAD@', '@PACKAGE@', '@VERSION@']
-      output: 'hello-@TAG@-windows-setup.exe'
+      command: [ruby, packaging/msi.rb, '@PAYLOAD@', '@PACKAGE@', '@VERSION@']
+      output: 'hello-@TAG@-windows-amd64.msi'
 ```
 
+For an Inno Setup installer instead, use `formats: [inno]` and an `.exe`
+output. A Windows target builds one installer format.
+
 The `nfpm` section still holds shared package metadata, and `tool.nfpm` keeps
 mixed-platform configurations consistent. Native targets use `native.command`
 to create their output.
@@ -110,6 +113,47 @@ abort "DMG verification failed" unless system("hdiutil", "verify", output)
 This places the app and an Applications shortcut inside a compressed disk
 image. Adapt the volume name and app name to your project.
 
+### A Windows Installer (MSI) project
+
+Keep your installer's WiX source in the repository. This minimal
+`packaging/hello.wxs` (WiX Toolset 5) installs everything in the payload
+for all users and replaces earlier versions on upgrade:
+
+```xml
+<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
+  <Package Name="Hello" Manufacturer="Your Name" Version="$(Version)"
+    UpgradeCode="{00000000-0000-0000-0000-000000000000}" Scope="perMachine" Compressed="yes">
+    <MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is already installed." />
+    <MediaTemplate EmbedCab="yes" />
+    <StandardDirectory Id="ProgramFiles64Folder">
+      <Directory Id="INSTALLFOLDER" Name="Hello" />
+    </StandardDirectory>
+    <Files Include="$(SourceDir)\**" Directory="INSTALLFOLDER" />
+  </Package>
+</Wix>
+```
+
+Generate your own `UpgradeCode` once and never change it: it is how Windows
+recognizes an upgrade. Then have `packaging/msi.rb` build it:
+
+```ruby
+payload, output, version = ARGV
+# Windows Installer versions are numeric: 1.2.3-beta.1 installs as 1.2.3.
+numeric = version.split("-").first
+success = system("wix", "build", File.join(__dir__, "hello.wxs"), "-arch", "x64",
+  "-d", "Version=#{numeric}", "-d", "SourceDir=#{payload}", "-pdbtype", "none", "-o", output)
+abort "MSI build failed" unless success
+```
+
+`-pdbtype none` stops WiX writing a `.wixpdb` debug file next to the MSI;
+the recipe may create only the declared output.
+
+Install WiX with `dotnet tool install --global wix --version 5.0.2`. Windows
+compares only the first three version fields, each at most 255.255.65535, so
+release candidates of one version upgrade each other in place. Per-user
+installs, shortcuts, file associations, and closing a running app are part of
+your WiX project; see the [WiX documentation](https://docs.firegiant.com/wix/).
+
 ### An Inno Setup script
 
 Keep your app's `.iss` recipe in the repository. Have `packaging/setup.rb`
@@ -143,11 +187,11 @@ native-packages build --version 1.2.3 --target windows-amd64 --output dist/windo
 ```
 
 `doctor` checks the host and the command's executable. Your script checks its
-additional tools, such as the Inno compiler. `validate` and `build --dry-run`
+additional tools, such as WiX or the Inno compiler. `validate` and `build --dry-run`
 do not execute it.
 
 The build checks Mach-O or PE architecture, runs the script, and checks that
-it produced exactly the declared DMG or EXE. Test installation, startup,
+it produced exactly the declared DMG, MSI or EXE. Test installation, startup,
 upgrades, and removal separately for your app.
 
 ## Preserve the prepared input

data/docs/_guides/publishing.md

@@ -71,7 +71,7 @@ The command downloads the inputs, verifies their published hashes, and builds
 packages in `dist/packages/1.2.3/`. It skips `before_build` hooks. Every binary
 release input needs a matching checksum.
 
-DMG and Inno targets use prepared local directories. Download and unpack their
+DMG, MSI and Inno targets use prepared local directories. Download and unpack their
 inputs in the native build job, then use `--version`. See
 [macOS and Windows installers](native-recipes.md).
 

data/docs/_guides/release-signing.md

@@ -67,7 +67,7 @@ Package publication's separate `packaging-checksums.txt` is also unchanged.
 
 ## Attest in the application's build job
 
-The examples use `v0.8.1` for readability. For release workflows, replace it
+The examples use `v0.10.0` for readability. For release workflows, replace it
 with that release's reviewed full commit SHA, not a mutable branch.
 After producing the final package, before uploading it, add this step to the
 job that built it:
@@ -79,7 +79,7 @@ permissions:
   attestations: write
 steps:
   # Existing checkout, build, platform signing and packaging steps go here.
-  - uses: crmne/native-packages/.github/actions/attest@v0.8.1
+  - uses: crmne/native-packages/.github/actions/attest@v0.10.0
     with:
       subject-path: dist/*.tar.gz
 ```
@@ -108,7 +108,7 @@ and install Ruby 3.2 or later with Ed25519-capable OpenSSL before the signing
 step. Then call:
 
 ```yaml
-- uses: crmne/native-packages/.github/actions/sign-release@v0.8.1
+- uses: crmne/native-packages/.github/actions/sign-release@v0.10.0
   with:
     directory: dist/release
     public-key: assets/update-public-key.hex

data/docs/_reference/commands.md

@@ -193,7 +193,7 @@ If several gem versions are installed, RubyGems lets you select the one required
 by the configuration:
 
 ```sh
-native-packages _0.8.1_ build --version 1.2.3
+native-packages _0.10.0_ build --version 1.2.3
 ```
 
 Bundler also works if you prefer to manage the gem in a Gemfile.

data/docs/_reference/configuration.md

@@ -28,7 +28,7 @@ expressions. Use the replacement values listed below.
 | Field | Purpose |
 | --- | --- |
 | `schema` | Required. Set to `1`. |
-| `tool.version` | Required. Exact native-packages version, such as `'0.8.1'`. |
+| `tool.version` | Required. Exact native-packages version, such as `'0.10.0'`. |
 | `tool.nfpm` | Required. Set to `'2.47.0'`, including in native-only configurations. |
 | `nfpm` | Shared package metadata and installed-file mappings, or a relative YAML filename. Requires `name`. |
 | `targets` | Required. Named build targets; use `{}` for recipe-only projects. |
@@ -48,7 +48,7 @@ command needed to install and select the configured gem.
 
 `nfpm` is named after the helper that writes Linux packages and MSIX files.
 It holds the package's metadata, files, dependencies, and package-manager
-settings. Native DMG and Inno targets also read the shared metadata.
+settings. Native DMG, MSI and Inno targets also read the shared metadata.
 
 Every target needs nonempty `maintainer`, `description`, and `license` values.
 Non-native targets need a `contents` list. The shared package name may contain
@@ -95,13 +95,14 @@ letters, digits, and hyphens, starting with a letter or digit.
 | `compiler_target` | Optional value for `@TARGET@`; otherwise it is the target ID. |
 | `before_build` | Command arguments run before copying a local input. |
 | `after_package` | Command arguments run on each package before its hash is recorded. |
-| `native` | Required for DMG/Inno. Contains `command` and `output`. |
+| `native` | Required for DMG, MSI and Inno. Contains `command` and `output`. |
+| `appimage` | Optional for AppImage targets: `update_information`, embedded with a `.zsync` file beside the AppImage. See [AppImage](platforms.md#update-information). |
 
 Formats are `deb`, `rpm`, `archlinux`, `apk`, `ipk`, `appimage`, `srpm`,
-`msix`, `dmg`, and `inno`. See [Supported platforms](platforms.md) for their requirements.
+`msix`, `dmg`, `msi`, and `inno`. See [Supported platforms](platforms.md) for their requirements.
 
-Windows targets select only `[msix]` or `[inno]`; macOS targets select `[dmg]`.
-DMG and Inno each require a separate binary target. SRPM requires a separate
+Windows targets select only `[msix]`, `[msi]` or `[inno]`; macOS targets select `[dmg]`.
+DMG, MSI and Inno each require a separate binary target. SRPM requires a separate
 `kind: source` target with only `[srpm]`.
 
 ### Inputs

data/docs/_reference/platforms.md

@@ -19,14 +19,15 @@ libraries.
 | `archlinux` | Linux | Arch-compatible files and explicit dependencies. | nFPM, `readelf` for binaries. |
 | `apk` | Linux | Suitable Alpine files, usually musl or static binaries, and dependencies. | nFPM, `readelf` for binaries. |
 | `ipk` | Linux | Files for the device/distribution baseline, dependencies, and an `abi` label. | nFPM, `readelf` for binaries. |
-| `appimage` | Linux | The same files as the DEB/RPM, including one desktop entry and its icon. | `mksquashfs` (squashfs-tools), `curl`, `readelf`. |
+| `appimage` | Linux | The same files as the DEB/RPM, including one desktop entry and its icon. | `mksquashfs` (squashfs-tools), `curl`, `readelf`; `zsyncmake` (zsync) with update information. |
 | `srpm` | Linux source target | RPM spec and source files. | nFPM; native RPM tooling for rebuild tests. |
 | `msix` | Windows | Windows binaries, identity, application assets, and capabilities. | nFPM; Windows tools for signing and installation tests. |
 | `dmg` | macOS | Complete app and a DMG script. | macOS, `lipo`, and your script's tools, such as `hdiutil`. |
+| `msi` | Windows | Complete app and a Windows Installer recipe/wrapper, such as a WiX project. | Windows and your installed MSI toolset, such as WiX. |
 | `inno` | Windows | Complete app and an Inno Setup recipe/wrapper. | Windows and your installed Inno compiler. |
 
 The supported nFPM version is **2.47.0**. It writes package files from your
-prepared contents. Native DMG and Inno targets call your scripts instead.
+prepared contents. Native DMG, MSI and Inno targets call your scripts instead.
 Archive inputs also require `bsdtar`; release downloads require `curl`.
 
 ## Linux compatibility
@@ -83,7 +84,41 @@ DEB and RPM do, and `build.json` lists what the binary links under
 `required_libraries` with `"libraries": "host"`. It therefore runs where your
 binary's glibc floor and those libraries are met, not on every Linux system.
 Build on the oldest distribution you support, or link statically, to widen
-that. The AppImage carries no update information and is not signed.
+that. The AppImage is not signed.
+
+### Update information
+
+AppImageUpdate, AppImageLauncher, AM, Gear Lever and other updaters find a
+newer AppImage through the update information embedded in it, and download
+only the blocks that changed through a `.zsync` file published beside it.
+Give the target an `appimage.update_information`:
+
+```yaml
+linux-amd64:
+  platform: linux
+  arch: amd64
+  libc: glibc
+  formats: [appimage]
+  appimage:
+    update_information: gh-releases-zsync|owner|app|latest|app-*-x86_64.AppImage.zsync
+```
+
+The string goes into the runtime's `.upd_info` section, and the build reads
+it back from the finished AppImage. `zsyncmake` then writes
+`NAME-VERSION-ARCH.AppImage.zsync` beside it, with the AppImage's file name
+as its relative URL, and the build checks the file's name, length and SHA-1
+against the AppImage. `build.json` records the `.zsync` file with its
+package, and `publish --to github` attaches both. The same inputs give the
+same bytes for both files.
+
+Two forms are accepted: `gh-releases-zsync|OWNER|REPOSITORY|TAG|PATTERN`,
+where `TAG` is usually `latest` (the newest stable release), and
+`zsync|https://URL.zsync`. A GitHub string must name `release.repository`,
+and its pattern must match the target's `.zsync` file name, so validation
+fails before a release could ship an AppImage whose updaters look for a file
+that is not there. Each architecture needs its own target with its own
+pattern. An `after_package` hook must leave the AppImage as it is, or the
+`.zsync` file no longer describes it and the build fails.
 
 Running an AppImage needs FUSE on the user's system, or
 `./App.AppImage --appimage-extract-and-run`.
@@ -105,7 +140,7 @@ project's Windows acceptance tests do. Those tests found that Windows rejected
 nFPM 2.47.0's built-in signature with `0x80096010`. An MSIX file built
 successfully is not yet evidence that Windows will accept and install it.
 
-## DMG and Inno Setup
+## DMG, MSI and Inno Setup
 
 These formats run on their native host and each require a separate binary
 target with a local directory input. macOS inspection supports `amd64`,
@@ -127,7 +162,7 @@ An Arch package file and an AUR recipe are separate outputs: the former can
 be installed directly; the latter tells Arch tooling how to obtain and package
 your app.
 
-There is no Flatpak or Snap build/publication adapter, no NSIS/WiX adapter, and no
+There is no Flatpak or Snap build/publication adapter, no NSIS adapter, and no
 hosted APT/DNF index service. Keep those workflows in your app's release
 process if you need them.
 

data/docs/_reference/troubleshooting.md

@@ -23,8 +23,8 @@ working on with `doctor --target ID` and `build --target ID --dry-run`.
 Install and select the version named in the error:
 
 ```sh
-gem install native-packages --version 0.8.1
-native-packages _0.8.1_ doctor
+gem install native-packages --version 0.10.0
+native-packages _0.10.0_ doctor
 ```
 
 `tool.version` is an exact match. In CI, use the matching released reusable
@@ -36,7 +36,7 @@ Linux and MSIX packaging require nFPM 2.47.0. Linux binary inspection needs
 `readelf`; archive extraction needs `bsdtar`. Install these using the
 [setup instructions](../_guides/getting-started.md#1-install-the-tools).
 
-DMG and Inno targets do not require an nFPM executable. If you only intend to
+DMG, MSI and Inno targets do not require an nFPM executable. If you only intend to
 build a native target, select it explicitly so `doctor` does not check Linux
 targets from the same configuration.
 

data/docs/cli-design.md

@@ -3,7 +3,7 @@
 The owner approved compatible shared support for RekordFlash's native alpha
 packaging on 2026-09-13. Version 0.3's [native recipe and prerelease policy](native-recipes.md)
 extends the original stable-only policy explicitly; published 0.2 consumers stay
-pinned. DMG/Inno adapters coordinate existing app scripts and retain their
+pinned. DMG/MSI/Inno adapters coordinate existing app scripts and retain their
 signing/version decisions, without adding a compiler or plugin framework.
 
 Status: accepted, 2026-09-13. Publishing was subsequently aligned with RubyLLM: GitHub release publication triggers the workflow, using `RUBYGEMS_AUTH_TOKEN`. The original Trusted Publishing proposal below is superseded by that decision. The v0.2 implementation follows this design. See the current [configuration reference](configuration.md) and [release setup](releasing.md) for the implemented interface and publication requirements. This document records the original design; it does not describe v0.1.0.

data/docs/index.md

@@ -28,7 +28,7 @@ features:
     details: Create DEB, RPM, AppImage, Arch, Alpine, and IPK packages from your compatible Linux builds.
   - icon: 🖥️
     title: Native installers
-    details: Connect your macOS DMG and Windows Inno Setup scripts, or package Windows apps as MSIX.
+    details: Connect your macOS DMG script and your Windows MSI or Inno Setup script, or package Windows apps as MSIX.
   - icon: 🚀
     title: Release automation
     details: Build from local files or release assets. Add packaging to GitHub Actions and upload the finished packages.
@@ -39,3 +39,47 @@ features:
     title: Verified builds
     details: Check binary architecture and library requirements. Record file hashes and verify them before publishing.
 ---
+
+<video class="hero-film" controls muted loop playsinline preload="metadata" poster="{{ '/assets/images/launch-film-poster.jpg' | relative_url }}" aria-label="native-packages in under a minute: ZapFast, then seventeen packaging files become one configuration" hidden>
+  <source src="{{ '/assets/videos/launch-film.mp4' | relative_url }}" type="video/mp4">
+</video>
+
+<style>
+  /* The theme sizes its hero for a square logo; the film is 16:9. */
+  .VPHero .hero-film {
+    display: block;
+    width: 100%;
+    max-width: 560px;
+    height: auto;
+    aspect-ratio: 16 / 9;
+    margin: 0 auto;
+    border-radius: 12px;
+    background: #0d0e1a;
+  }
+  .VPHero .image-container:has(.hero-film) {
+    width: 100%;
+    height: auto;
+    padding: 0 24px;
+    transform: none;
+  }
+  @media (max-width: 959px) {
+    .VPHero .image:has(.hero-film) {
+      margin: 0 0 32px;
+    }
+  }
+</style>
+
+<script>
+  // The theme's hero takes a picture; the film takes its place where
+  // scripts run, and the logo stays where they do not.
+  (function () {
+    var film = document.querySelector(".hero-film");
+    var slot = document.querySelector(".VPHero .image-container");
+    if (!film || !slot) return;
+    slot.replaceChildren(film);
+    film.hidden = false;
+    if (!window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+      film.play().catch(function () {});
+    }
+  })();
+</script>

data/docs/releasing.md

@@ -23,7 +23,7 @@ Update the gemspec, `NativePackages::VERSION`, example/version references and ch
 Create a GitHub release for that commit:
 
 ```sh
-gh release create v0.8.1 --target main --title 'native-packages 0.8.1' --notes-file release-notes.md
+gh release create v0.10.0 --target main --title 'native-packages 0.10.0' --notes-file release-notes.md
 ```
 
 Adding `--draft` permits review before publication and does not trigger the publisher. The tag must match the exact gem version and point to a commit on `main`. Set `--prerelease` only for a prerelease gem version.
@@ -36,7 +36,7 @@ If the workflow itself needs a correction, fix it on `main` and dispatch the
 corrected release workflow against the existing published tag:
 
 ```sh
-gh workflow run release.yml --ref main -f tag=v0.8.1
+gh workflow run release.yml --ref main -f tag=v0.10.0
 ```
 
 Validation resolves the original tag to an exact commit, requires it to be on

data/examples/native-packages-all-formats.yaml

@@ -1,7 +1,7 @@
 # Supply the listed build outputs before running this example.
 schema: 1
 tool:
-  version: '0.8.1'
+  version: '0.10.0'
   nfpm: '2.47.0'
 nfpm:
   name: example-app

data/examples/native-packages.yaml

@@ -1,6 +1,6 @@
 schema: 1
 tool:
-  version: '0.8.1'
+  version: '0.10.0'
   nfpm: '2.47.0'
 nfpm:
   name: example-app

data/lib/native_packages/appimage.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module NativePackages
   # Builds a type 2 AppImage from the same contents nFPM packages: the files
   # are laid out in an AppDir, packed with mksquashfs and appended to a pinned
@@ -17,6 +19,13 @@ module NativePackages
       "arm7" => ["armhf", "e9060d37577b8a29914ec12d8740add24e19ff29012fb1fa0f60daf62db0688d"]
     }.freeze
     ICON_DIRECTORIES = %w[usr/share/icons usr/share/pixmaps].freeze
+    # The runtime's ELF section that AppImageUpdate and the other updaters
+    # read: a NUL-terminated string in a fixed 1024 bytes.
+    UPDATE_SECTION = ".upd_info"
+    # AppImage's update information formats, without the `bintray-zsync`
+    # and `pling-v1-zsync` services that no longer exist.
+    GITHUB_UPDATE = /\Agh-releases-zsync\|([A-Za-z0-9_.-]+)\|([A-Za-z0-9_.-]+)\|([^|\s]+)\|([^|\s]+\.zsync)\z/
+    URL_UPDATE = %r{\Azsync\|https://[^|\s]+\.zsync\z}
     attr_reader :root
 
     def initialize(root)
@@ -29,10 +38,81 @@ module NativePackages
 
     def self.filename(name, version, target) = "#{name}-#{version}-#{architecture(target)}.AppImage"
 
-    def doctor(target)
+    # The target's update information, checked against the AppImage it
+    # describes: a GitHub string must name the release repository, and its
+    # file pattern must match this target's `.zsync` file, so a release
+    # never ships an AppImage whose updaters look for a file that is not
+    # there. Returns nil when the target has none.
+    def self.update_information(target, name:, version:, repository:)
+      settings = target["appimage"]
+      return nil if settings.nil?
+      raise Error, "appimage: expected a mapping" unless settings.is_a?(Hash)
+      unknown = settings.keys - %w[update_information]
+      raise Error, "appimage: unknown fields #{unknown.join(', ')}" unless unknown.empty?
+      value = settings["update_information"]
+      raise Error, "appimage.update_information: expected a string" unless value.is_a?(String) && !value.empty?
+      raise Error, "appimage.update_information: at most 1023 bytes" if value.bytesize > 1023
+      if (match = GITHUB_UPDATE.match(value))
+        owner, project, _tag, pattern = match.captures
+        unless "#{owner}/#{project}".casecmp?(repository.to_s)
+          raise Error, "appimage.update_information names #{owner}/#{project}, but release.repository is #{repository.inspect}"
+        end
+        zsync = "#{filename(name, version, target)}.zsync"
+        unless File.fnmatch?(pattern, zsync, File::FNM_PATHNAME)
+          raise Error, "appimage.update_information: #{pattern} does not match #{zsync}"
+        end
+      elsif !URL_UPDATE.match?(value)
+        raise Error, "appimage.update_information: use gh-releases-zsync|OWNER|REPOSITORY|TAG|FILE.zsync or zsync|https://URL.zsync"
+      end
+      value
+    end
+
+    # The file offset and size of the ELF section `name` in `bytes`, or nil.
+    # Every AppImage runtime is a little-endian ELF file, 32 or 64 bits.
+    def self.section(bytes, name)
+      raise Error, "AppImage runtime is not a little-endian ELF file" unless bytes.start_with?("\x7fELF".b) && bytes.getbyte(5) == 1
+      wide = { 1 => false, 2 => true }.fetch(bytes.getbyte(4)) { raise Error, "AppImage runtime has an unknown ELF class" }
+      offset = wide ? bytes.byteslice(0x28, 8).unpack1("Q<") : bytes.byteslice(0x20, 4).unpack1("V")
+      size, count, names = bytes.byteslice(wide ? 0x3A : 0x2E, 6).unpack("v3")
+      header = lambda do |index|
+        entry = bytes.byteslice(offset + (index * size), size)
+        raise Error, "AppImage runtime has a truncated section table" unless entry && entry.bytesize == size
+        wide ? [entry.unpack1("V"), *entry.byteslice(0x18, 16).unpack("Q<2")] : [entry.unpack1("V"), *entry.byteslice(0x10, 8).unpack("V2")]
+      end
+      _, strings, = header.call(names)
+      count.times do |index|
+        label, start, length = header.call(index)
+        found = bytes.byteslice(strings + label, name.bytesize + 1)
+        return [start, length] if found == "#{name}\0".b
+      end
+      nil
+    end
+
+    # `runtime` with `information` in its update section.
+    def self.embed(runtime, information)
+      start, length = section(runtime, UPDATE_SECTION) || raise(Error, "AppImage runtime has no #{UPDATE_SECTION} section")
+      raise Error, "update information exceeds the runtime's #{length}-byte #{UPDATE_SECTION} section" if information.bytesize >= length
+      raise Error, "AppImage runtime's #{UPDATE_SECTION} section is outside the file" if start + length > runtime.bytesize
+      runtime = runtime.b
+      runtime[start, length] = information.b + ("\0".b * (length - information.bytesize))
+      runtime
+    end
+
+    # The update information an AppImage carries, or nil when it has none.
+    def self.read_update_information(path)
+      bytes = File.binread(path)
+      start, length = section(bytes, UPDATE_SECTION)
+      return nil unless start
+      value = bytes.byteslice(start, length)[/\A[^\0]*/n]
+      value.empty? ? nil : value
+    end
+
+    def doctor(target, update: false)
       self.class.architecture(target)
-      missing = %w[mksquashfs curl].reject { |tool| available?(tool) }
-      raise Error, "install required AppImage tools: #{missing.join(', ')} (mksquashfs is in squashfs-tools)" unless missing.empty?
+      tools = %w[mksquashfs curl]
+      tools << "zsyncmake" if update
+      missing = tools.reject { |tool| available?(tool) }
+      raise Error, "install required AppImage tools: #{missing.join(', ')} (mksquashfs is in squashfs-tools, zsyncmake in zsync)" unless missing.empty?
     end
 
     def runtime(target)
@@ -46,9 +126,11 @@ module NativePackages
       path
     end
 
-    # Returns the AppImage's path and what was put at the AppDir's root.
-    def build(package, target, destination, name:, version:, epoch:)
-      doctor(target)
+    # Returns the AppImage's path, what was put at the AppDir's root, and
+    # the `.zsync` file beside it when the AppImage carries update
+    # information (nil otherwise).
+    def build(package, target, destination, name:, version:, epoch:, update: nil)
+      doctor(target, update: !update.nil?)
       output = destination / self.class.filename(name, version, target)
       Dir.mktmpdir("native-packages-appimage-") do |directory|
         appdir = Pathname.new(directory) / "AppDir"
@@ -59,14 +141,43 @@ module NativePackages
         image = Pathname.new(directory) / "filesystem.squashfs"
         run "mksquashfs", appdir, image, "-root-owned", "-noappend", "-no-xattrs", "-no-progress", "-quiet", "-comp", "zstd",
           env: { "SOURCE_DATE_EPOCH" => epoch.to_s }
+        bytes = runtime(target).binread
+        bytes = self.class.embed(bytes, update) if update
         File.open(output, "wb") do |file|
-          file.write(runtime(target).binread)
+          file.write(bytes)
           IO.copy_stream(image.to_s, file)
         end
         output.chmod(0o755)
         check(output)
-        [output, entry.merge("runtime" => RUNTIME, "libraries" => "host")]
+        details = entry.merge("runtime" => RUNTIME, "libraries" => "host")
+        return [output, details, nil] unless update
+        raise Error, "AppImage lost its update information: #{output}" unless self.class.read_update_information(output) == update
+        [output, details.merge("update_information" => update), zsync(output, epoch)]
+      end
+    end
+
+    # Writes `<AppImage>.zsync` beside the AppImage, for updaters that fetch
+    # only the blocks that changed. Its URL is the AppImage's file name,
+    # relative to the `.zsync` file, so it works from wherever both are
+    # published. The AppImage's time is the build's, which zsyncmake records.
+    def zsync(path, epoch)
+      File.utime(epoch, epoch, path)
+      output = Pathname.new("#{path}.zsync")
+      run "zsyncmake", "-u", path.basename.to_s, "-o", output, path, chdir: path.dirname
+      check_zsync(output, path)
+      output
+    end
+
+    # Fails unless `zsync` describes the AppImage at `path` as it is now.
+    def check_zsync(zsync, path)
+      header = zsync.binread.split("\n\n".b, 2).first.to_s.force_encoding(Encoding::UTF_8).lines.to_h do |line|
+        key, value = line.chomp.split(": ", 2)
+        [key, value]
       end
+      expected = { "Filename" => path.basename.to_s, "URL" => path.basename.to_s, "Length" => path.size.to_s,
+        "SHA-1" => Digest::SHA1.file(path).hexdigest }
+      wrong = expected.reject { |key, value| header[key] == value }.keys
+      raise Error, "#{zsync.basename} does not describe #{path.basename}: #{wrong.join(', ')}" unless wrong.empty?
     end
 
     def check(path)

data/lib/native_packages/build.rb

@@ -33,7 +33,9 @@ module NativePackages
       configuration.validate
       selected = configuration.select(ids: ids, formats: formats)
       nfpm_version if selected.values.any? { |target| !(target.fetch("formats") - Configuration::NATIVE_FORMATS - ["appimage"]).empty? }
-      selected.each_value { |target| AppImage.new(root).doctor(target) if target.fetch("formats").include?("appimage") }
+      selected.each_value do |target|
+        AppImage.new(root).doctor(target, update: !target["appimage"].nil?) if target.fetch("formats").include?("appimage")
+      end
       selected.each do |id, target|
         next unless target["native"]
         metadata = configuration.target_tokens(configuration.tokens("9.8.7"), id, target, "/payload").merge("PACKAGE" => "/output/package", "FORMAT" => target.fetch("formats").first)
@@ -160,11 +162,12 @@ module NativePackages
                 elsif format == "appimage"
                   package = render_tree(configuration.package(target), configuration.target_tokens(info, id, target, payload))
                   inspection = Inspection.new(root, configuration.data.fetch("libraries")).check(package, target, format)
-                  package_path, details = AppImage.new(root).build(package, target, destination, name: configuration.name, version: number,
-                    epoch: info.fetch("SOURCE_DATE_EPOCH"))
+                  package_path, details, zsync = AppImage.new(root).build(package, target, destination, name: configuration.name, version: number,
+                    epoch: info.fetch("SOURCE_DATE_EPOCH"), update: configuration.update_information(target, number))
                   inspection["appimage"] = details
-                  packages = files(destination)
-                  raise Error, "AppImage build must create only its package" unless packages == [package_path]
+                  outputs = [package_path, zsync].compact.sort
+                  raise Error, "AppImage build must create only its package and .zsync file" unless files(destination) == outputs
+                  packages = [package_path]
                 else
                   package = render_tree(configuration.package(target), configuration.target_tokens(info, id, target, payload))
                   if number.include?("-") && (package.fetch("version_schema", "semver") != "semver" || %w[prerelease version_metadata].any? { |key| package.key?(key) && !package[key].to_s.empty? })
@@ -180,19 +183,23 @@ module NativePackages
                   packages = files(destination)
                   raise Error, "nFPM did not create exactly one #{format} package" unless packages.length == 1
                 end
+                outputs ||= packages
                 if target["after_package"]
                   hook_tokens = configuration.target_tokens(info, id, target, payload).merge("PACKAGE" => packages.first.to_s, "FORMAT" => format)
                   run(*render_tree(target.fetch("after_package"), hook_tokens), env: { "NATIVE_PACKAGES_TARGET" => id, "NATIVE_PACKAGES_VERSION" => number })
-                  raise Error, "after_package must preserve the package path and output set" unless files(destination) == packages
+                  raise Error, "after_package must preserve the package path and output set" unless files(destination) == outputs
                   AppImage.new(root).check(packages.first) if format == "appimage"
+                  AppImage.new(root).check_zsync(zsync, packages.first) if format == "appimage" && zsync
                 end
                 if native
                   native.check_output(packages.first, format)
                   raise Error, "native recipes/signing must not change their input payload" unless native.digest(payload) == payload_digest
                 end
                 inspection["apple"] = signing.notarize(packages.first) if signing
-                records << { "target" => id, "format" => format, "path" => packages.first.relative_path_from(staging).to_s,
+                record = { "target" => id, "format" => format, "path" => packages.first.relative_path_from(staging).to_s,
                   "sha256" => sha256(packages.first), "validation" => inspection }
+                record["zsync"] = zsync.relative_path_from(staging).to_s if format == "appimage" && zsync
+                records << record
               end
             end
           end
@@ -381,7 +388,7 @@ module NativePackages
       end
       destinations.each do |destination|
         if destination == "github"
-          paths = manifest.fetch("packages").map { |entry| output / entry.fetch("path") }
+          paths = manifest.fetch("packages").flat_map { |entry| [entry.fetch("path"), entry["zsync"]].compact.map { |path| output / path } }
           paths += manifest.fetch("files").keys.grep(/-packaging\.tar\.xz\z/).map { |path| output / path }
           names = paths.map { |path| path.basename.to_s }
           raise Error, "duplicate release asset names; give variants distinct nFPM names/releases" unless names.uniq == names

data/lib/native_packages/configuration.rb

@@ -6,7 +6,7 @@ require_relative "appimage"
 module NativePackages
   class Configuration
     include Support
-    NATIVE_FORMATS = %w[dmg inno].freeze
+    NATIVE_FORMATS = %w[dmg inno msi].freeze
     FORMATS = (%w[deb rpm archlinux apk ipk msix srpm appimage] + NATIVE_FORMATS).freeze
     NFPM_VERSION = "2.47.0"
     NAMES = %w[native-packages.yaml native-packages.yml].freeze
@@ -60,8 +60,8 @@ module NativePackages
     def check_prerelease(version, selected, defer_recipes: false)
       return unless version.include?("-")
       raise Error, "prerelease builds require release.prereleases: true" unless data.fetch("release")["prereleases"] == true
-      unless selected.values.all? { |target| (target.fetch("formats") - %w[deb rpm appimage dmg inno]).empty? } && (defer_recipes || data.fetch("templates").empty?)
-        raise Error, "prereleases support deb, rpm, appimage, dmg and inno only, without downstream recipes"
+      unless selected.values.all? { |target| (target.fetch("formats") - %w[deb rpm appimage dmg inno msi]).empty? } && (defer_recipes || data.fetch("templates").empty?)
+        raise Error, "prereleases support deb, rpm, appimage, dmg, inno and msi only, without downstream recipes"
       end
     end
 
@@ -86,7 +86,7 @@ module NativePackages
       metadata = tokens("9.8.7", epoch: 1_767_225_600)
       targets.each do |id, target|
         raise Error, "invalid target name: #{id}" unless /\A[a-z0-9][a-z0-9-]*\z/.match?(id)
-        unknown = target.keys - %w[platform arch libc abi kind formats input nfpm before_build after_package compiler_target native]
+        unknown = target.keys - %w[platform arch libc abi kind formats input nfpm before_build after_package compiler_target native appimage]
         raise Error, "targets.#{id}: unknown fields #{unknown.join(', ')}" unless unknown.empty?
         formats = target.fetch("formats")
         unless formats.is_a?(Array) && !formats.empty? && formats.uniq == formats && (formats - FORMATS).empty?
@@ -97,11 +97,11 @@ module NativePackages
         kind = target.fetch("kind", "binary")
         raise Error, "targets.#{id}.kind: use binary, data or source" unless %w[binary data source].include?(kind)
         raise Error, "#{id}: MSIX requires a Windows target with only msix format" if formats.include?("msix") && (target["platform"] != "windows" || formats != ["msix"])
-        raise Error, "#{id}: Windows targets require msix or inno" if target["platform"] == "windows" && ![["msix"], ["inno"]].include?(formats)
+        raise Error, "#{id}: Windows targets require msix, inno or msi" if target["platform"] == "windows" && ![["msix"], ["inno"], ["msi"]].include?(formats)
         raise Error, "#{id}: macOS targets require dmg" if target["platform"] == "macos" && formats != ["dmg"]
         native = !(formats & NATIVE_FORMATS).empty?
         if native
-          expected = { "dmg" => "macos", "inno" => "windows" }[formats.first]
+          expected = { "dmg" => "macos", "inno" => "windows", "msi" => "windows" }[formats.first]
           raise Error, "#{id}: native formats require a separate binary target on their native platform" unless formats.length == 1 && expected == target["platform"] && kind == "binary"
           recipe = mapping(target.fetch("native"), "#{id}.native")
           raise Error, "#{id}.native: expected command and output" unless recipe.keys.sort == %w[command output]
@@ -110,13 +110,13 @@ module NativePackages
             raise Error, "#{id}.native.command: use command arguments including @PACKAGE@"
           end
           filename = render(recipe.fetch("output"), target_tokens(metadata, id, target, "/payload"))
-          extension = formats == ["dmg"] ? ".dmg" : ".exe"
+          extension = { "dmg" => ".dmg", "inno" => ".exe", "msi" => ".msi" }.fetch(formats.first)
           unless /\A[a-zA-Z0-9][a-zA-Z0-9._+-]*\z/.match?(filename) && filename.end_with?(extension)
             raise Error, "#{id}.native.output: expected a safe #{extension} filename"
           end
           render_tree(command, target_tokens(metadata, id, target, "/payload").merge("PACKAGE" => "/output/#{filename}", "FORMAT" => formats.first))
         elsif target.key?("native")
-          raise Error, "#{id}: native commands require a dmg or inno target"
+          raise Error, "#{id}: native commands require a dmg, inno or msi target"
         end
         raise Error, "#{id}: SRPM requires a separate source target" if (formats.include?("srpm") && (kind != "source" || formats != ["srpm"])) || (kind == "source" && formats != ["srpm"])
         if kind == "binary" && target["platform"] == "linux"
@@ -125,6 +125,13 @@ module NativePackages
         if formats.include?("appimage")
           raise Error, "#{id}: AppImage requires a Linux binary target" unless target["platform"] == "linux" && kind == "binary"
           AppImage.architecture(target)
+        elsif target.key?("appimage")
+          raise Error, "#{id}.appimage: only for targets that build an AppImage"
+        end
+        begin
+          update_information(target, "9.8.7")
+        rescue Error => error
+          raise Error, "#{id}.#{error.message}"
         end
         raise Error, "#{id}: IPK needs an explicit abi (device/distribution baseline)" if formats.include?("ipk") && target.fetch("abi", "").empty?
         input = mapping(target.fetch("input"), "#{id}.input")
@@ -162,6 +169,12 @@ module NativePackages
       true
     end
 
+    # The AppImage update information for `target`, checked against the
+    # AppImage `version` builds, or nil.
+    def update_information(target, version)
+      AppImage.update_information(target, name: name, version: version, repository: data.fetch("release")["repository"])
+    end
+
     def tokens(version, epoch: nil)
       epoch ||= Integer(ENV.fetch("SOURCE_DATE_EPOCH", Time.now.to_i.to_s))
       result = { "NAME" => name, "VERSION" => version, "TAG" => "v#{version}", "DATE" => Time.at(epoch).utc.iso8601,

data/lib/native_packages/native_recipe.rb

@@ -76,6 +76,9 @@ module NativePackages
           next false if file.size < 512
           file.seek(-512, IO::SEEK_END)
           file.read(4) == "koly"
+        elsif format == "msi"
+          # Windows Installer databases are OLE compound files.
+          file.size >= 512 && file.read(8) == "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b
         else
           next false unless file.size >= 64 && file.read(2) == "MZ"
           file.seek(0x3c)

data/lib/native_packages/support.rb

@@ -12,7 +12,7 @@ require "tmpdir"
 require "yaml"
 
 module NativePackages
-  VERSION = "0.8.1"
+  VERSION = "0.10.0"
   class Error < StandardError; end
 
   module Support

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: native-packages
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.10.0
 platform: ruby
 authors:
 - Carmine Paolino