Developers¶
Libera Suite is a Python host around upstream editors. Most of the work is in the integration points: what the editor expects from a desktop host, how the payload is built, and how our changes to upstream are kept reviewable.
- Architecture: the pieces and how they talk.
- Build the payload: building the editors and the native binaries.
- The patch queue: how our changes to upstream are kept.
- How this is tested: the pyramid, and what each level is allowed to trust.
- Cutting a release: which machine makes what, and in what order.
- Roadmap: what is next and what we have decided against.
The lb command, which builds, packages and releases, is on one page to print (PDF).
In six slides¶
Getting the source¶
On Linux, the virtualenv has to see the system's PyGObject
The window is GTK and WebKit, whose Python half is not a wheel: it is python3-gi, which your distribution installs into /usr/lib/python3/dist-packages. A plain virtualenv never has it on sys.path, so uv run libera FILE will tell you it needs GTK even on a machine that has it.
Make the environment on the distribution's own Python, with its packages in reach:
uv keeps --system-site-packages through every later uv sync and uv run, as long as it does not rebuild the environment. It rebuilds when the interpreter differs from the 3.12 in .python-version, so on a distribution whose Python is newer, which Fedora's is, set UV_PYTHON=/usr/bin/python3 before both commands and keep it set: uv reads it ahead of that file. Without it the next uv run rebuilds the environment on 3.12, where a gi built for 3.14 cannot be imported however the environment was made.
libera prints these commands, with your own paths in them, when it cannot reach GTK.
The test suite does not need this. It drives the editor through libera --serve and a headless browser, never opening a window. Only running the application does.
Point the application at a payload you have built, and run it:
Seeing what it is doing¶
libera FILE # warnings and errors only
libera -v FILE # what it is doing: opening, saving, windows
libera -vv FILE # and how: HTTP routes, x2t command lines
libera -vvv FILE # and every request, as it starts and finishes
libera -q FILE # errors only
-vv is usually the one you want when something is wrong: it prints the exact x2t command line, which you can then run by hand.
What there is to run¶
The Makefile holds what any Python project has, plus make payload and make ship. Everything else is lb (uv run lb outside the virtualenv), a group per job (payload, toolchain, app, linux, release, components, container), plus on, tidy, bench and fidelity, and --help at every level lists the options with examples, each naming the environment variable it sets. The steps of make payload are each a command, to resume a build that failed in the middle: lb payload --help.
lb tidy removes every build on this machine: the repository's (mostly the Flatpak's builddir, ostree store and cache, 1.4 GB on the laptop this was written on) and $BUILD_ROOT, which holds the sources, the payload and the native core (44 GB there), so the next payload build starts from the fetch. It lists them with their sizes and asks before removing anything; --dry-run lists and stops, --yes does not ask.
Running the checks¶
uv run pytest # everything
uv run pytest -m unit # fast and isolated
uv run pytest -m integration # the host, against a real payload
uv run pytest -m e2e # the editor, in a real browser
The suite is a pyramid, one directory per level, and the marker comes from the directory. The two upper levels skip themselves when they have nothing to run against: no payload, or no Chromium (set CHROMIUM=/path/to/browser if yours is somewhere unusual). A skip and a pass look the same in pytest's summary line, so the run names the payload it found before anything executes.
How this is tested is the whole picture: what each level may trust, why the e2e tier measures pixels, and which checks only exist on the builders.
To look at the editor by hand, with devtools, a real browser and no window toolkit in the way, run libera --serve, which prints the URL it is listening on: