Skip to content

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.

The lb command, which builds, packages and releases, is on one page to print (PDF).

In six slides

Getting the source

git clone https://github.com/abilian/libera-suite
cd libera-suite
uv sync

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 venv --clear --system-site-packages --python /usr/bin/python3
uv sync

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:

export LIBERA_PAYLOAD=/path/to/build/out/payload
uv run libera ~/Documents/note.docx

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

make help             # the standard jobs: lint, test, docs, the wheel
lb help               # building, packaging, releasing

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:

uv run libera --serve ~/Documents/note.docx --port 43110