Skip to content

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

Merged
wpfleger96 merged 1 commit into
block:mainfrom
kcao-gss:docs/contributing-linux-prereqs
Jul 28, 2026
Merged

docs(contributing): document the Linux system libraries just ci requires#3396
wpfleger96 merged 1 commit into
block:mainfrom
kcao-gss:docs/contributing-linux-prereqs

Conversation

@kcao-gss

@kcao-gss kcao-gss commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

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 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.

@kcao-gss
docs(contributing): document the Linux system libraries just ci requires
8e83142 
The prerequisites table covers language toolchains but not system libraries.
Hermit pins the former and not the latter, so on Linux `just ci` fails partway
through `just check` at `desktop-tauri-clippy` with a pkg-config error for
`gdk-pixbuf-2.0` — the desktop crates link against GTK and WebKitGTK.

Add the apt list CI already installs, so a local run matches CI, plus a pointer
to Tauri's prerequisites for other distributions and a note that server-side
work can use the narrower recipes that need no GTK.

Signed-off-by: Kyler Cao <kcao@gssmail.com>
@kcao-gss
kcao-gss requested a review from a team as a code owner July 28, 2026 20:58
@wpfleger96
wpfleger96 enabled auto-merge (squash) July 28, 2026 21:00
@wpfleger96
wpfleger96 merged commit 4fcd55a into block:main Jul 28, 2026
25 checks passed
tlongwell-block pushed a commit that referenced this pull request Jul 28, 2026
npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d Tyler Longwell
Merge remote-tracking branch 'origin/main' into eva/agent-trading-cards
60ceadf 
* origin/main:
  feat(acp): steer claude-code and codex agents via _session/steering (#3007)
  feat(desktop): apply WebKit rendering workarounds at startup on Linux (#3271)
  fix(desktop): stabilize flaky DM expansion E2E ordering assertions (#2004)
  docs(contributing): document the Linux system libraries just ci requires (#3396)

Signed-off-by: npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz>
Co-authored-by: Tyler Longwell <tlongwell@block.xyz>
Signed-off-by: Tyler Longwell <tlongwell@block.xyz>
dophsquare pushed a commit to sailt-k/buzz that referenced this pull request Jul 28, 2026
Fizz (agent)
Merge branch 'main' into add-orcarouter-provider
746b224 
Pull in nostr 0.44.6 (patched NIP-44 v2 DoS advisory) to clear the
Security/cargo-deny failure. No conflicts.

Co-authored-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>
Signed-off-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>

* origin/main: (74 commits)
  chore(ci): bump desktop smoke E2E timeout to 30 minutes (block#3409)
  release(chart): publish 0.1.7 (block#3393)
  feat(acp): steer claude-code and codex agents via _session/steering (block#3007)
  feat(desktop): apply WebKit rendering workarounds at startup on Linux (block#3271)
  fix(desktop): stabilize flaky DM expansion E2E ordering assertions (block#2004)
  docs(contributing): document the Linux system libraries just ci requires (block#3396)
  fix(desktop): paint community rail full height (block#3382)
  fix(acp): disable goose cron scheduler in managed agent children (block#3144)
  feat(desktop): add custom harness inline from agent dialogs (block#3252)
  chore(compose): remove stale typesense env vars (block#3332)
  feat(desktop): refine agent catalog sharing (block#2439)
  fix(desktop): keep drafts out of the Inbox All view (block#3217)
  docs: restructure DCO guidance into scannable subsection (block#3337)
  Unify mobile loading spinners (block#3314)
  fix(desktop): restore the inbox icon in the sidebar (block#3341)
  fix(desktop): gate codex-acp on a minimum supported version (block#3254)
  feat(cli): add users set-status command for NIP-38 profile status (block#3253)
  fix(composer): scope multiline block formatting (block#3246)
  feat(chart): add relay pod extension points (block#3322)
  Refine mobile attachment picking (block#3313)
  ...
dophsquare pushed a commit to SHL0MS/buzz that referenced this pull request Jul 28, 2026
Fizz (agent)
Merge branch 'main' into PR block#3334 to clear stale-base CI failure
3b9a61b 
Co-authored-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>
Signed-off-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>

* origin/main:
  chore(ci): bump desktop smoke E2E timeout to 30 minutes (block#3409)
  release(chart): publish 0.1.7 (block#3393)
  feat(acp): steer claude-code and codex agents via _session/steering (block#3007)
  feat(desktop): apply WebKit rendering workarounds at startup on Linux (block#3271)
  fix(desktop): stabilize flaky DM expansion E2E ordering assertions (block#2004)
  docs(contributing): document the Linux system libraries just ci requires (block#3396)
  fix(desktop): paint community rail full height (block#3382)
  fix(acp): disable goose cron scheduler in managed agent children (block#3144)
  feat(desktop): add custom harness inline from agent dialogs (block#3252)
  chore(compose): remove stale typesense env vars (block#3332)
  feat(desktop): refine agent catalog sharing (block#2439)
  fix(desktop): keep drafts out of the Inbox All view (block#3217)
  docs: restructure DCO guidance into scannable subsection (block#3337)
  Unify mobile loading spinners (block#3314)
  fix(desktop): restore the inbox icon in the sidebar (block#3341)
  fix(desktop): gate codex-acp on a minimum supported version (block#3254)
  feat(cli): add users set-status command for NIP-38 profile status (block#3253)
  fix(composer): scope multiline block formatting (block#3246)
  feat(chart): add relay pod extension points (block#3322)
  Refine mobile attachment picking (block#3313)
dophsquare pushed a commit to linxule/buzz that referenced this pull request Jul 28, 2026
Fizz (agent)
Merge branch 'main' into PR block#3343 to clear stale-base CI failure
bdb8278 
Co-authored-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>
Signed-off-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>

* origin/main:
  chore(ci): bump desktop smoke E2E timeout to 30 minutes (block#3409)
  release(chart): publish 0.1.7 (block#3393)
  feat(acp): steer claude-code and codex agents via _session/steering (block#3007)
  feat(desktop): apply WebKit rendering workarounds at startup on Linux (block#3271)
  fix(desktop): stabilize flaky DM expansion E2E ordering assertions (block#2004)
  docs(contributing): document the Linux system libraries just ci requires (block#3396)
  fix(desktop): paint community rail full height (block#3382)
  fix(acp): disable goose cron scheduler in managed agent children (block#3144)
  feat(desktop): add custom harness inline from agent dialogs (block#3252)
  chore(compose): remove stale typesense env vars (block#3332)
  feat(desktop): refine agent catalog sharing (block#2439)
  fix(desktop): keep drafts out of the Inbox All view (block#3217)
  docs: restructure DCO guidance into scannable subsection (block#3337)
  Unify mobile loading spinners (block#3314)
  fix(desktop): restore the inbox icon in the sidebar (block#3341)
  fix(desktop): gate codex-acp on a minimum supported version (block#3254)
  feat(cli): add users set-status command for NIP-38 profile status (block#3253)
  fix(composer): scope multiline block formatting (block#3246)
dophsquare pushed a commit to bhargavms/buzz that referenced this pull request Jul 28, 2026
Fizz (agent)
Merge branch 'main' into PR block#2839 to clear stale-base CI failure
e6a6523 
Co-authored-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>
Signed-off-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>

* origin/main: (111 commits)
  chore(ci): bump desktop smoke E2E timeout to 30 minutes (block#3409)
  release(chart): publish 0.1.7 (block#3393)
  feat(acp): steer claude-code and codex agents via _session/steering (block#3007)
  feat(desktop): apply WebKit rendering workarounds at startup on Linux (block#3271)
  fix(desktop): stabilize flaky DM expansion E2E ordering assertions (block#2004)
  docs(contributing): document the Linux system libraries just ci requires (block#3396)
  fix(desktop): paint community rail full height (block#3382)
  fix(acp): disable goose cron scheduler in managed agent children (block#3144)
  feat(desktop): add custom harness inline from agent dialogs (block#3252)
  chore(compose): remove stale typesense env vars (block#3332)
  feat(desktop): refine agent catalog sharing (block#2439)
  fix(desktop): keep drafts out of the Inbox All view (block#3217)
  docs: restructure DCO guidance into scannable subsection (block#3337)
  Unify mobile loading spinners (block#3314)
  fix(desktop): restore the inbox icon in the sidebar (block#3341)
  fix(desktop): gate codex-acp on a minimum supported version (block#3254)
  feat(cli): add users set-status command for NIP-38 profile status (block#3253)
  fix(composer): scope multiline block formatting (block#3246)
  feat(chart): add relay pod extension points (block#3322)
  Refine mobile attachment picking (block#3313)
  ...
dophsquare pushed a commit to darox/buzz that referenced this pull request Jul 28, 2026
Fizz (agent)
Merge branch 'main' into PR block#3003 to clear stale-base CI failure
4e90e36 
Co-authored-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>
Signed-off-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>

* origin/main: (84 commits)
  chore(ci): bump desktop smoke E2E timeout to 30 minutes (block#3409)
  release(chart): publish 0.1.7 (block#3393)
  feat(acp): steer claude-code and codex agents via _session/steering (block#3007)
  feat(desktop): apply WebKit rendering workarounds at startup on Linux (block#3271)
  fix(desktop): stabilize flaky DM expansion E2E ordering assertions (block#2004)
  docs(contributing): document the Linux system libraries just ci requires (block#3396)
  fix(desktop): paint community rail full height (block#3382)
  fix(acp): disable goose cron scheduler in managed agent children (block#3144)
  feat(desktop): add custom harness inline from agent dialogs (block#3252)
  chore(compose): remove stale typesense env vars (block#3332)
  feat(desktop): refine agent catalog sharing (block#2439)
  fix(desktop): keep drafts out of the Inbox All view (block#3217)
  docs: restructure DCO guidance into scannable subsection (block#3337)
  Unify mobile loading spinners (block#3314)
  fix(desktop): restore the inbox icon in the sidebar (block#3341)
  fix(desktop): gate codex-acp on a minimum supported version (block#3254)
  feat(cli): add users set-status command for NIP-38 profile status (block#3253)
  fix(composer): scope multiline block formatting (block#3246)
  feat(chart): add relay pod extension points (block#3322)
  Refine mobile attachment picking (block#3313)
  ...
dophsquare pushed a commit to skyerus/buzz that referenced this pull request Jul 28, 2026
Fizz (agent)
Merge branch 'main' into PR block#2885 to clear stale-base CI failure
2bb6578 
Co-authored-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>
Signed-off-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>

* origin/main: (111 commits)
  chore(ci): bump desktop smoke E2E timeout to 30 minutes (block#3409)
  release(chart): publish 0.1.7 (block#3393)
  feat(acp): steer claude-code and codex agents via _session/steering (block#3007)
  feat(desktop): apply WebKit rendering workarounds at startup on Linux (block#3271)
  fix(desktop): stabilize flaky DM expansion E2E ordering assertions (block#2004)
  docs(contributing): document the Linux system libraries just ci requires (block#3396)
  fix(desktop): paint community rail full height (block#3382)
  fix(acp): disable goose cron scheduler in managed agent children (block#3144)
  feat(desktop): add custom harness inline from agent dialogs (block#3252)
  chore(compose): remove stale typesense env vars (block#3332)
  feat(desktop): refine agent catalog sharing (block#2439)
  fix(desktop): keep drafts out of the Inbox All view (block#3217)
  docs: restructure DCO guidance into scannable subsection (block#3337)
  Unify mobile loading spinners (block#3314)
  fix(desktop): restore the inbox icon in the sidebar (block#3341)
  fix(desktop): gate codex-acp on a minimum supported version (block#3254)
  feat(cli): add users set-status command for NIP-38 profile status (block#3253)
  fix(composer): scope multiline block formatting (block#3246)
  feat(chart): add relay pod extension points (block#3322)
  Refine mobile attachment picking (block#3313)
  ...
dophsquare pushed a commit to arisgysel-design/buzz that referenced this pull request Jul 28, 2026
Fizz (agent)
Merge branch 'main' into PR block#2766 to clear stale-base CI failure
78feb58 
Co-authored-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>
Signed-off-by: Phuoc (Phu) Do <91568955+dophsquare@users.noreply.github.com>

* origin/main: (126 commits)
  chore(ci): bump desktop smoke E2E timeout to 30 minutes (block#3409)
  release(chart): publish 0.1.7 (block#3393)
  feat(acp): steer claude-code and codex agents via _session/steering (block#3007)
  feat(desktop): apply WebKit rendering workarounds at startup on Linux (block#3271)
  fix(desktop): stabilize flaky DM expansion E2E ordering assertions (block#2004)
  docs(contributing): document the Linux system libraries just ci requires (block#3396)
  fix(desktop): paint community rail full height (block#3382)
  fix(acp): disable goose cron scheduler in managed agent children (block#3144)
  feat(desktop): add custom harness inline from agent dialogs (block#3252)
  chore(compose): remove stale typesense env vars (block#3332)
  feat(desktop): refine agent catalog sharing (block#2439)
  fix(desktop): keep drafts out of the Inbox All view (block#3217)
  docs: restructure DCO guidance into scannable subsection (block#3337)
  Unify mobile loading spinners (block#3314)
  fix(desktop): restore the inbox icon in the sidebar (block#3341)
  fix(desktop): gate codex-acp on a minimum supported version (block#3254)
  feat(cli): add users set-status command for NIP-38 profile status (block#3253)
  fix(composer): scope multiline block formatting (block#3246)
  feat(chart): add relay pod extension points (block#3322)
  Refine mobile attachment picking (block#3313)
  ...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@wpfleger96 wpfleger96 wpfleger96 approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@kcao-gss @wpfleger96