Unify & document flatpak distribution workflow (for local/release)

assets/flatpak/org.wezfurlong.wezterm.LOCAL-TESTING.json

@@ -18,14 +18,12 @@
         "--talk-name=org.freedesktop.Notifications",
         "--share=network"
     ],
-    "build-options": {
-        "append-path" : "/usr/lib/sdk/rust-stable/bin"
-    },
     "modules": [
         {
             "name": "wezterm",
             "buildsystem": "simple",
             "build-options": {
+                "append-path" : "/usr/lib/sdk/rust-stable/bin",
                 "env": {
                     "CARGO_HOME": "/run/build/wezterm/cargo"
                 }
@@ -33,12 +31,9 @@
             "build-commands": [
                 "cargo --offline fetch --manifest-path Cargo.toml --verbose",
                 "cargo --offline build --release --verbose",
-                "mkdir -p /app/share/icons/hicolor/128x128/apps/",
-                "cp ./assets/icon/terminal.png /app/share/icons/hicolor/128x128/apps/org.wezfurlong.wezterm.png",
-                "mkdir -p /app/share/metainfo/",
-                "cp ./assets/wezterm.appdata.xml /app/share/metainfo/org.wezfurlong.wezterm.appdata.xml",
-                "mkdir -p /app/share/applications/",
-                "cp ./assets/wezterm.desktop /app/share/applications/org.wezfurlong.wezterm.desktop",
+                "install -Dm644 ./assets/icon/terminal.png /app/share/icons/hicolor/128x128/apps/org.wezfurlong.wezterm.png",
+                "install -Dm644 ./assets/wezterm.appdata.xml /app/share/metainfo/org.wezfurlong.wezterm.appdata.xml",
+                "install -Dm644 ./assets/wezterm.desktop /app/share/applications/org.wezfurlong.wezterm.desktop",
                 "install -Dm755 ./target/release/wezterm -t /app/bin/",
                 "install -Dm755 ./target/release/wezterm-gui -t /app/bin/",
                 "install -Dm755 ./target/release/wezterm-mux-server -t /app/bin/",

assets/wezterm.appdata.xml

@@ -70,7 +70,8 @@
   <developer_name>Wez Furlong</developer_name>
 
   <releases>
-    <release version="20220807-113146-c2fee766" date="2022-08-07">
+    <!-- NOTE: This release should only be used for local builds (e.g. for the flatpak package) -->
+    <release version="20260000-000000-local-build" date="2026-07-31">
       <description>
         <p>
           Featuring more powerful key and mouse bindings, new lua functions for

ci/flatpak-build.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -xeu
+
+if ! [[ -f Cargo.lock ]]; then
+  >&2 echo "ERROR: This script should be called from repo root!"
+  exit 1
+fi
+
+# Add flathub repo if not available
+flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
+
+# Install SDK & Platform flatpak components
+# NOTE: We install specific version of those components, make sure it corresponds with the
+# runtime-version used in ../assets/flatpak/org.wezfurlong.wezterm.LOCAL-TESTING.json
+flatpak install --user --noninteractive flathub \
+  org.freedesktop.Platform//23.08 \
+  org.freedesktop.Sdk//23.08 \
+  org.freedesktop.Sdk.Extension.rust-stable//23.08
+
+# Disabled for now: seems like it has an OpenSSL problem and fails to use SSL when
+# validating the screenshot URLs
+#flatpak install --user --noninteractive org.freedesktop.appstream-glib
+#flatpak run --env=G_DEBUG=fatal-criticals org.freedesktop.appstream-glib validate assets/wezterm.appdata.xml
+
+# Generate list of cargo dependencies for the isolated flatpak build
+if command -v flatpak-cargo-generator &>/dev/null; then
+  fcg_bin=(flatpak-cargo-generator)
+else
+  python3 -m pip install toml aiohttp
+  curl -L 'https://github.com/flatpak/flatpak-builder-tools/raw/master/cargo/flatpak-cargo-generator.py' > /tmp/flatpak-cargo-generator.py
+  fcg_bin=(python3 /tmp/flatpak-cargo-generator.py)
+fi
+"${fcg_bin[@]}" Cargo.lock -o assets/flatpak/generated-sources.json
+
+# Build & install the flatpak locally
+# NOTE: Disabled in CI
+if [ "${CI:-}" != "yes" ] ; then
+  flatpak-builder \
+    --state-dir /var/tmp/wezterm-flatpak-builder \
+    --install /var/tmp/wezterm-flatpak-repo \
+    assets/flatpak/org.wezfurlong.wezterm.LOCAL-TESTING.json \
+    --user --force-clean -y
+fi

ci/flatpak.sh

@@ -1,23 +0,0 @@
-#!/bin/bash
-set -xe
-
-flatpak remote-add --if-not-exists --user flathub https://flathub.org/repo/flathub.flatpakrepo
-flatpak install --noninteractive --user flathub org.freedesktop.Platform//23.08 org.freedesktop.Sdk//23.08 org.freedesktop.Sdk.Extension.rust-stable//23.08
-
-flatpak install --noninteractive --user org.freedesktop.appstream-glib
-
-# Disabled for now: seems like it has an OpenSSL problem and fails to use SSL when
-# validating the screenshot URLs
-#flatpak run --env=G_DEBUG=fatal-criticals org.freedesktop.appstream-glib validate assets/wezterm.appdata.xml
-
-python3 -m pip install toml aiohttp
-curl -L 'https://github.com/flatpak/flatpak-builder-tools/raw/master/cargo/flatpak-cargo-generator.py' > /tmp/flatpak-cargo-generator.py
-python3 /tmp/flatpak-cargo-generator.py Cargo.lock -o assets/flatpak/generated-sources.json
-
-if [ "${CI}" != "yes" ] ; then
-  flatpak-builder \
-    --state-dir /var/tmp/wezterm-flatpak-builder \
-    --install /var/tmp/wezterm-flatpak-repo \
-    assets/flatpak/org.wezfurlong.wezterm.json \
-    --force-clean --user -y
-fi

ci/make-flathub-pr.sh

@@ -1,10 +1,22 @@
-#!/bin/bash
-set -xe
+#!/usr/bin/env bash
+set -xeu
+
+if ! [[ -f Cargo.lock ]]; then
+  >&2 echo "ERROR: This script should be called from repo root!"
+  exit 1
+fi
+
 TAG_NAME=$(ci/tag-name.sh)
 
-python3 -m pip install toml aiohttp
-curl -L 'https://github.com/flatpak/flatpak-builder-tools/raw/master/cargo/flatpak-cargo-generator.py' > /tmp/flatpak-cargo-generator.py
-python3 /tmp/flatpak-cargo-generator.py Cargo.lock -o flathub/generated-sources.json
+# Generate list of cargo dependencies for the isolated flatpak build
+if command -v flatpak-cargo-generator &>/dev/null; then
+  fcg_bin=(flatpak-cargo-generator)
+else
+  python3 -m pip install toml aiohttp
+  curl -L 'https://github.com/flatpak/flatpak-builder-tools/raw/master/cargo/flatpak-cargo-generator.py' > /tmp/flatpak-cargo-generator.py
+  fcg_bin=(python3 /tmp/flatpak-cargo-generator.py)
+fi
+"${fcg_bin[@]}" Cargo.lock -o assets/flatpak/generated-sources.json
 
 URL="https://github.com/wezterm/wezterm/releases/download/${TAG_NAME}/wezterm-${TAG_NAME}-src.tar.gz"
 
@@ -12,10 +24,10 @@ URL="https://github.com/wezterm/wezterm/releases/download/${TAG_NAME}/wezterm-${
 # in the current dir. This is handled by actions/download-artifact in CI
 SHA256=$(sha256sum wezterm*-src.tar.gz | cut -d' ' -f1)
 
-sed -e "s,@URL@,$URL,g" -e "s/@SHA256@/$SHA256/g" < assets/flatpak/org.wezfurlong.wezterm.template.json > flathub/org.wezfurlong.wezterm.json
+sed -e "s,@URL@,$URL,g" -e "s/@SHA256@/$SHA256/g" < assets/flatpak/org.wezfurlong.wezterm.RELEASE-TEMPLATE.json > flathub/org.wezfurlong.wezterm.json
 
 RELEASE_DATE=$(git -c "core.abbrev=8" show -s "--format=%cd" "--date=format:%Y-%m-%d")
-sed -e "s,@TAG_NAME@,$TAG_NAME,g" -e "s/@DATE@/$RELEASE_DATE/g" < assets/flatpak/org.wezfurlong.wezterm.appdata.template.xml > flathub/org.wezfurlong.wezterm.appdata.xml
+sed -e "s,@TAG_NAME@,$TAG_NAME,g" -e "s/@DATE@/$RELEASE_DATE/g" < assets/flatpak/org.wezfurlong.wezterm.appdata.RELEASE-TEMPLATE.xml > flathub/org.wezfurlong.wezterm.appdata.xml
 
 cd flathub
 git config user.email wez@wezfurlong.org

docs-internal/flatpak-distribution.md

@@ -0,0 +1,36 @@
+# Flatpak distribution
+
+## Release build
+
+For a release build, the flatpak definition is
+`assets/flatpak/org.wezfurlong.wezterm.RELEASE-TEMPLATE.json` with metadata in
+`assets/flatpak/org.wezfurlong.wezterm.appdata.RELEASE-TEMPLATE.xml`.
+
+A GHA workflow runs the `ci/flathub-prepare-pr.sh` script from repo root to prepare a few metadata
+files, followed by opening a PR on the [flathub repo][flathub-repo] for the new version.
+
+Once merged, flathub builders will auto-schedule the actual build for later inclusion in the flathub
+app catalog. This can be followed on <https://builds.flathub.org/>.
+
+[flathub-repo]: https://github.com/flathub/org.wezfurlong.wezterm
+
+## Local build
+
+For a local build, the flatpak definition is in
+`assets/flatpak/org.wezfurlong.wezterm.LOCAL-TESTING.json`. It is basically the same as the
+release one but uses the local repo instead of a specific release from github.
+
+The script needs the following dependencies:
+
+- flatpak-cargo-generator (auto-downloaded if not in `$PATH`, needs python3 with pip)
+- flatpak-builder
+- appstreamcli
+
+> [!NOTE]
+> If using Nix, `nix develop` gives you these automatically.
+
+Run `ci/flatpak-build.sh` from the repo root to prepare, build & install the flatpak for the current
+user. Then run the built flatpak with `flatpak run org.wezfurlong.wezterm`.
+
+> [!NOTE]
+> The script stores tmp data in `/var/tmp/wezterm-flatpak-*` directories.

nix/flake.lock

@@ -71,11 +71,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1783816212,
-        "narHash": "sha256-2aZisVTVGSFEk3MYcOiWQp3zvwyzbqpktB69Rcfp150=",
+        "lastModified": 1785602060,
+        "narHash": "sha256-z7D96eESRM4CPV/XtwpwFn8IDdfLAmxz6lVWrGYXvR4=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "3b32825de172d0bc85664f495edb096b10862524",
+        "rev": "a5cbcfe954791221bfffe2307f7d1a1bf61a871e",
         "type": "github"
       },
       "original": {

nix/flake.nix

@@ -255,6 +255,11 @@
 
                 nightly.latest.rustfmt
                 nightly.latest.rust-analyzer
+
+                # For local flatpak build
+                pkgs.flatpak-builder
+                pkgs.flatpak-builder-tools # for flatpak-cargo-generator
+                pkgs.appstream
               ]);
 
             LD_LIBRARY_PATH = libPath;