Skip to content

Latest commit

 

History

History
244 lines (187 loc) · 12.6 KB

README.md

File metadata and controls

244 lines (187 loc) · 12.6 KB

Flatpak packaging

photos.ansel.Ansel.json is the Flatpak manifest. build-flatpak.sh builds it from the local working tree.

The app id is photos.ansel.Ansel — see "The app id was decided" below for where it is load-bearing and why it is spelled that way. Because CMake installs the desktop and appdata files under that name already, the manifest needs no rename-desktop-file / rename-appdata-file — only rename-icon, since the icon is installed as ansel. The script reads the id back out of the manifest rather than keeping its own copy; three independent copies of it is how they drifted apart before.

Building

packaging/flatpak/build-flatpak.sh

Requires flatpak, flatpak-builder, git and jq on the host. The GNOME SDK and the Flathub-hosted dependencies are pulled on first run, so the first build is long and needs a few GB of free disk.

It produces, in build/flatpak/:

Output Purpose
repo/ An OSTree repository. Serve it over HTTP and it is a Flatpak remote — this is what gives users flatpak update.
Ansel-<version>-x86_64.flatpak A single-file bundle, for one-off installs. Installs with flatpak install --user Ansel-*.flatpak. A bundle carries no remote, so it never updates itself.

Useful environment variables: SOURCE_DIR (tree to build, defaults to the repository root), BUILD_DIR, REPO_DIR, BUNDLE_NAME, VERSION, and the signing pair below.

libsoup: the manifest says nothing, and that is deliberate

There is no -DLIBSOUP_FORCE_VERSION in the app module's config-opts, and adding one back would be a regression. Ansel reaches libsoup twice over: common/http_server.c links it directly, and the map and geotagging panels link it through osm-gps-map. libsoup 2 and libsoup 3 abort on sight of each other — libsoup3 symbols detected. Using libsoup2 and libsoup3 in the same process is not supported.

cmake/modules/FindLibSoup.cmake used to prefer libsoup 3 whenever its development files were present, which the GNOME SDK has and osm-gps-map 1.2.0 does not support. That produced a libansel.so on libsoup 3 and lighttable plugins on libsoup 2: it built, exported and installed cleanly, and aborted on the first plugin it loaded. It now asks osm-gps-map which libsoup it was built against and follows it, so the flatpak lands on libsoup 2 by itself. Watch for this line in the configure output:

-- LibSoup: osm-gps-map is built against libsoup2, matching it

The manifest is not where this belongs, because the hazard is not specific to Flatpak: any build with libsoup 3's .pc file installed next to a libsoup-2 osm-gps-map produced the same binary. It goes unnoticed wherever libsoup 3's development package simply is not installed.

Signing

Signing is opt-in and off by default:

GPG_KEY_ID=<key-id> GPG_HOMEDIR=~/.gnupg packaging/flatpak/build-flatpak.sh

Both the repository and the bundle are then signed. An unsigned repository still works, but every client has to add it with --no-gpg-verify, which is not something to ask of users.

Publishing an updatable repository

The nightly workflow (.github/workflows/flatpak-nightly.yml) attaches the bundle to the month's nightly-YYYY-MM pre-release, next to the AppImage. That covers installation but not updates — the repository section above does.

For updates, build/flatpak/repo has to be rsynced to a static HTTP host (it is a plain directory tree; no server-side software is involved) and advertised through a .flatpakrepo file:

[Flatpak Repo]
Title=Ansel
Url=https://<host>/flatpak/
Homepage=https://ansel.photos/
Comment=Nightly builds of Ansel
Icon=https://<host>/ansel.svg
GPGKey=<base64 of the exported public key, single line>

with GPGKey produced by gpg --export <key-id> | base64 -w0. Users then run flatpak remote-add --if-not-exists ansel https://<host>/ansel.flatpakrepo once.

build-update-repo --prune already runs at the end of each build, so a repository republished every night does not accumulate objects no ref points at any more. GitHub Pages is not a viable host for this: a full repository runs to the better part of a gigabyte, against a 1 GB per-site limit.

The nightly repository on R2

flatpak-nightly.yml publishes build/flatpak/repo to a Cloudflare R2 bucket after every build (objects first, summary last, so a client never fetches a summary naming objects that are not there yet) and writes ansel.flatpakrepo beside it, generated by make-flatpakrepo.sh with the signing key's public half embedded. The step is skipped when the R2_* secrets are absent. Setup, secrets and the user-side command are in doc/nightly-distribution.md.

The bundle on the monthly release stays: it is the one-shot install for someone who does not want a remote. The repository is what gives flatpak update.

Flathub

Checked against Flathub's own requirements rather than assumed, because the rules tightened when flatpak-builder-lint became mandatory.

The nightly can never go there, on either repo. Flathub's requirements say in as many words that "Nightly releases, development snapshots, or any software requiring daily updates must not be published to either repo" — stable and beta. The rolling v0.0.0 tag is excluded by name, and no manifest work changes that. Whatever this directory produces every night belongs on our own repository; Flathub would be a second, slower channel beside it, never a replacement.

But a stable release is not the entry price. Flathub's beta repo is for "releases that have some level of testing and are expected to mostly work for non-developer end-users", and an app may debut there with no stable version behind it: asked directly on their Discourse, a maintainer confirmed that a normal submission "will be merged to the beta branch directly". The other bar in the requirements — "sustained commit history and standard release practices such as tagged versions" — is met on the first half already.

So the blocker is not a release in the sense of a polished 1.0. It is a tag. Cut one, pin a manifest to it, and what gets submitted stops being "software requiring daily updates" while remaining exactly the code the nightly ships.

What is left to do

Exactly one thing, and it is not a packaging task.

  1. Cut a tag, and add a matching <release> to data/photos.ansel.Ansel.appdata.xml.in. It does not have to be 1.0.0 — a beta version is a release as far as Flathub is concerned. What it must not be is v0.0.0, which is a moving pointer.

  2. Generate the manifest and submit it:

    packaging/flatpak/make-flathub-manifest.py --tag v1.0.0 -o photos.ansel.Ansel.json

Everything else on the list is done, and the rest of this section records what was decided so nobody has to decide it twice.

The manifest is generated, not maintained

make-flathub-manifest.py derives the Flathub manifest from the nightly one. The two differ in four places and nowhere else, which is why this is a generator rather than a second manifest to keep in sync: the app module builds a pinned git tag instead of the working directory, it drops --share=network, the payloads it used to fetch become hashed type: file sources, and it is told where they landed with the fetches switched off.

The hashes are read from the manifests the fetches themselves read, so they are never hand-maintained, and the lens database directory is addressed by the schema version the pinned LensSerious reads. Run it again to refresh a submission; there is nothing to edit.

The app id was decided, and it is now final

photos.ansel.Ansel. It was photos.ansel.ansel, which is valid but conventionally wrong — the last segment is the application name, in the application's own capitalisation. Changed here because it is the install path, the dconf path, the D-Bus-ish identity every desktop uses to tie a window to its launcher, and the one thing that cannot be changed after publishing without stranding everyone who installed the old id.

It is load-bearing in five places that must agree, all updated together: the app-id key in the manifest, the <id> and <launchable> in the appdata, the names of the appdata and .desktop files data/CMakeLists.txt installs, and the application://…desktop string src/control/progress.c hands the desktop's progress API.

appstreamcli still emits cid-maybe-not-rdns for it. That is a heuristic complaining that the second and third components look alike; the id genuinely is the reverse of ansel.photos plus the app name, so the note is informational and stays.

--filesystem=host and --device=all, and why

Both are flagged during Flathub review. The case, so it does not have to be reconstructed under time pressure:

--filesystem=host. Ansel is a photo library manager. It imports from wherever the photographs are — an external drive, a NAS mount, a card reader, a directory the user names in a dialog — and it writes XMP sidecars next to the raw files it did not copy, because that is the whole point of a non-destructive editor that leaves originals alone. A portal gives one directory at a time, chosen per session; a library that has to re-ask for every film roll on every launch is not a library. darktable ships --filesystem=host on Flathub for the same reason, and RawTherapee likewise.

--device=all. OpenCL. Ansel's pixel pipeline offloads to the GPU, and OpenCL device enumeration needs the render nodes; --device=dri covers the common case, but not every ICD loader arrangement, and a photo editor that silently falls back to the CPU on some machines is a support burden rather than a feature. If a reviewer pushes back, --device=dri is the concession to offer, and it should be measured against a real GPU before it is agreed to.

Neither is required for the app to start, which is worth saying out loud in the review thread: both degrade gracefully, and both are about not making the user fight the sandbox.

The offline half, which is done

Flathub's hard rule is that "There is no network access during the build process", and their documentation notes specifically that --share=network in build-args does not work as a workaround. That was the real blocker, and it is now a manifest exercise rather than a code change: both payloads Ansel fetches at configure time are hashed, published in a manifest, and switchable off.

"sources": [
    { "type": "file", "url": "https://raw.githubusercontent.com/aurelienpierreeng/LensSerious/main/db/v4/lenses.db",
      "sha256": "...", "dest": "lens-db" },
    { "type": "file", "url": ".../db/v4/lensfun-xml.tar.xz", "sha256": "...", "dest": "lens-db" },
    { "type": "file", "url": ".../ansel-denoise/master/models/denoise-large-multi-v1.anselnn",
      "sha256": "...", "dest": "nn-models" }
],
"config-opts": [
    "-DFETCH_LENS_DB=OFF",   "-DLENS_DB_DIR=/run/build/ansel/lens-db",
    "-DFETCH_NN_MODELS=OFF", "-DNN_MODELS_DIR=/run/build/ansel/nn-models"
]

The hashes live in the manifests the fetches already read — db/v<schema>/manifest.json in LensSerious, models/manifest.json in ansel-denoise — so generating that source list is mechanical. The cost is that such a build ships the payloads pinned in its manifest until someone bumps them, rather than whatever is current; which is the correct trade for a release channel and the wrong one for a nightly, and is why THIS manifest keeps --share=network and fetches.

Sources: requirements, beta without a stable release, how to use flathub-beta.

Inherited from darktable, and removed

The manifest started as Flathub's darktable one, and carried three things Ansel has no use for. They are gone; do not restore them without a reason.

  • exiftool and perl. Nothing in Ansel calls exiftool — the only occurrence in the tree is a documentation URL in a comment in src/imageio/format/png.c. perl existed solely to build it. Between them they were the longest part of the build, and the exiftool module was unbuildable anyway: it sourced an exiftool-sources.json that was never vendored into this repository.
  • The lensfun module's database refresh. Its post-install pip-installed lxml and ran a lensfun_convert_db.py (likewise never vendored here) over a git checkout of the lensfun database, to give darktable current calibrations at run time. Ansel reads none of it: nothing in the pixel pipeline links liblensfun, and the calibrations come from lenses.db, built at configure time from the XML the previous section describes. The module is now built purely for its headers and its .pc file.