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.
packaging/flatpak/build-flatpak.shRequires 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.
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 is opt-in and off by default:
GPG_KEY_ID=<key-id> GPG_HOMEDIR=~/.gnupg packaging/flatpak/build-flatpak.shBoth 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.
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.
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.
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.
Exactly one thing, and it is not a packaging task.
-
Cut a tag, and add a matching
<release>todata/photos.ansel.Ansel.appdata.xml.in. It does not have to be1.0.0— a beta version is a release as far as Flathub is concerned. What it must not be isv0.0.0, which is a moving pointer. -
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.
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.
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.
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.
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.
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.
exiftoolandperl. Nothing in Ansel calls exiftool — the only occurrence in the tree is a documentation URL in a comment insrc/imageio/format/png.c.perlexisted solely to build it. Between them they were the longest part of the build, and theexiftoolmodule was unbuildable anyway: it sourced anexiftool-sources.jsonthat was never vendored into this repository.- The
lensfunmodule's database refresh. Itspost-installpip-installed lxml and ran alensfun_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 fromlenses.db, built at configure time from the XML the previous section describes. The module is now built purely for its headers and its.pcfile.