docs(contributing): document the Linux system libraries just ci requires (#3396)

## Problem

The prerequisites table lists language toolchains (Rust, Node, pnpm,
Flutter, Docker, `just`) but no system libraries. Hermit pins the former
and not the latter, so following the setup section exactly on Linux
still leaves `just ci` unable to run: it fails partway through its first
dependency, `just check`, at `desktop-tauri-clippy`.

```
The system library `gdk-pixbuf-2.0` required by crate `gdk-pixbuf-sys` was not found.
The file `gdk-pixbuf-2.0.pc` needs to be installed and the PKG_CONFIG_PATH environment variable must contain its parent directory.
```

The desktop crates link against GTK and WebKitGTK. CI installs those
packages explicitly, so it never sees this — which is exactly why the
gap is invisible from the maintainer side. Since `check` runs first in
the `ci` chain, the failure also masks everything after it (`test-unit`,
`desktop-test`, `web-build`, `mobile-test` never run), which makes it
read as a broken repo rather than a missing dependency.

## Change

Adds a `#### Linux: Tauri system libraries` subsection under
Prerequisites with:

- The apt list copied from `.github/workflows/ci.yml`, so a local run
matches CI rather than drifting from it
- A pointer to [Tauri's
prerequisites](https://tauri.app/start/prerequisites/) for non-Debian
distributions
- A note that server-side contributors can skip it — `just fmt-check`,
`just clippy`, `just test-unit`, and `just test` need no GTK

Docs only. No TOC entry needed, since the TOC lists `##` headings and
this is a `####` subsection.

## How I hit it

Running `just ci` before pushing #3372, on Ubuntu under WSL2 with the
Hermit toolchain active and all Docker services healthy. Everything the
guide asks for was in place. The four `check` steps before
`desktop-tauri-clippy` (`fmt-check`, `clippy`, `desktop-check`,
`desktop-tauri-fmt-check`) passed, which is what makes the failure point
specific rather than a general build problem.

## Closest existing work

None found. I searched open and closed issues and PRs for `gdk-pixbuf`,
`libgtk`, `webkit2gtk`, `system dependencies`, `prerequisites`, `just
ci`, and `linux setup`. The Linux/GTK issues that exist (#2604, #2643,
#2982, #2811, #2562) are all runtime bugs in shipped builds, not
setup-path failures.

## Verification

The package list is transcribed from `.github/workflows/ci.yml:152-163`;
the same list appears in `release.yml` and `linux-canary.yml`. I have
not installed the packages on my machine, so I can confirm the failure
and the source of the fix but not that the list is exhaustive on a clean
box — worth a second pair of eyes from anyone who has done a fresh Linux
setup recently.

Signed-off-by: Kyler Cao <kcao@gssmail.com>
This commit is contained in:
kcao-gss
2026-07-28 21:13:47 +00:00
committed by GitHub
parent 1d3b810ad7
commit 4fcd55a999
+31
View File
@@ -98,6 +98,37 @@ Hermit pins Rust, `just`, Node, pnpm, and other tools to the versions in
upfront. If you don't use Hermit, ensure your toolchain meets the minimum
versions in the table above.
#### Linux: Tauri system libraries
Hermit pins language toolchains, not system libraries. On Linux, the desktop
app's Rust crates link against GTK and WebKitGTK, so `just ci` (and any
`just desktop-tauri-*` recipe) needs these installed system-wide first. On
Debian/Ubuntu:
```bash
sudo apt-get install -y --no-install-recommends \
build-essential curl file libasound2-dev libayatana-appindicator3-dev \
libgtk-3-dev librsvg2-dev libssl-dev libwebkit2gtk-4.1-dev libxdo-dev \
patchelf wget
```
This is the same list CI installs (see `.github/workflows/ci.yml`), so matching
it locally keeps your results comparable to CI. Other distributions ship these
under different package names — see the
[Tauri prerequisites](https://tauri.app/start/prerequisites/) for the
equivalents.
Without them, `just ci` fails partway through `just check` with a pkg-config
error such as:
```
The system library `gdk-pixbuf-2.0` required by crate `gdk-pixbuf-sys` was not found.
```
If you're only touching the relay, CLI, or other server-side crates, you can
skip this and run the narrower recipes instead — `just fmt-check`, `just
clippy`, `just test-unit`, and `just test` need no GTK.
### First-Time Setup
```bash