Skip to main content

max / shop

Document the three system libraries shop links at build time libwayland-client, libxkbcommon and libfontconfig are linked, not dlopened, and no file in the repo named any of them. shop is packaged nowhere and consumers take it as a git dep, so building from source is the only way anyone gets it. Record how each one fails, since they differ: wayland-sys and yeslogic-fontconfig-sys panic out of build scripts through pkg-config, but xkbcommon 0.8 has no build script and declares #[link] directly, so it surfaces late as a bare -lxkbcommon linker error and wants the .so symlink rather than the runtime .so.0. Note that leaving RUST_FONTCONFIG_DLOPEN unset is a choice: the font lookup only fires on the first character the bundled font lacks, so a link error at build time beats a missing library found when somebody prints CJK. CONTRIBUTING gets the coupling that caused this: a new linked library changes the README and Alloy's Containerfile, which builds shop at a pinned SHOP_REV.
Co-Authored-By
Claude Opus 5 (1M context) <noreply@anthropic.com>
Author: Max Johnson <me@maxj.phd> · 2026-08-09 17:08 UTC
Signed with PGP, not checked
Commit: 03b0562a109f68c6e0f466d81abf1fe3c849f009
Parent: 7eba62f
2 files changed, +49 insertions, -0 deletions
M CONTRIBUTING.md +5
@@ -11,6 +11,11 @@
11 11 - `cargo deny check` must pass before commit. No GPL/LGPL/AGPL, ever.
12 12 - `cargo fmt` + `cargo clippy --all-targets` clean.
13 13 - Commits are concise, imperative, no emoji.
14 + - Build prerequisites are in the README's Building section. A dependency that
15 + links a new system library changes that section, and it changes Alloy's
16 + Containerfile too: Alloy builds shop from source at a pinned revision, so a
17 + library added here breaks its image at the next `SHOP_REV` move. Say so in the
18 + commit.
14 19
15 20 ## Adding a component crate
16 21
M README.md +44
@@ -24,6 +24,50 @@
24 24 `-e PROGRAM [ARGS...]` runs a program instead of the login shell, as every
25 25 terminal does. `--exec 'CMD'` is the shell-string form, for benchmarks.
26 26
27 + ## Building
28 +
29 + Three system libraries are linked at build time, so their development headers
30 + have to be installed. A Rust toolchain and these are the whole list.
31 +
32 + Fedora:
33 +
34 + ```
35 + dnf install rust cargo pkgconf wayland-devel libxkbcommon-devel fontconfig-devel
36 + ```
37 +
38 + Debian, Ubuntu, Pop!_OS:
39 +
40 + ```
41 + apt install pkg-config libwayland-dev libxkbcommon-dev libfontconfig-1-dev
42 + ```
43 +
44 + Then `cargo build --release`, which leaves the binary at `target/release/shop`.
45 + `ldd` on it is the check if this list ever looks wrong.
46 +
47 + What each one is for, and how it fails if it is missing:
48 +
49 + - **libwayland-client.** `wayland-client` is built with its `system` feature, so
50 + it calls the C library instead of reimplementing the wire protocol. Its
51 + `wayland-sys` build script probes `wayland-client` through pkg-config and
52 + panics if it is absent.
53 + - **libxkbcommon.** Keymap handling and key encoding, reached through
54 + smithay-client-toolkit. The `xkbcommon` crate has no build script and no
55 + pkg-config probe; it declares `#[link(name = "xkbcommon")]` directly, so a
56 + missing dev package surfaces late, as a linker error about `-lxkbcommon`
57 + rather than as a build-script message. The runtime `.so.0` is not enough on
58 + its own: the link needs the `.so` symlink the dev package carries.
59 + - **libfontconfig.** The system font query described under Fonts.
60 + `yeslogic-fontconfig-sys` panics out of its build script with a pkg-config
61 + dump advising you to set `PKG_CONFIG_PATH`, which is the wrong instruction
62 + when the package is simply not installed.
63 +
64 + Fontconfig is linked rather than dlopened, deliberately. The crate supports
65 + `RUST_FONTCONFIG_DLOPEN` and shop does not set it: the font lookup runs on the
66 + first character the bundled font lacks, which can be a long way into a session,
67 + and a link error at build time is a better failure than a missing library found
68 + when somebody prints CJK. Anyone repackaging shop who wants fontconfig soft can
69 + set that variable and accept the runtime failure instead.
70 +
27 71 ## Layout
28 72
29 73 - `crates/shop/` — the binary.