Merge pull request #1037 from FabPei/agent/issue-955

README.md

@@ -224,6 +224,41 @@ DirectX 12 shaders are compiled with FXC, which is part of Windows, so no `dxcom
 
 RISC-V 64 (riscv64): `deckcraft-<ver>-linux-riscv64.tar.gz`, a tarball only (cross-compiled; needs glibc 2.39+, e.g. Ubuntu 24.04+).
 
+**Runtime libraries.** The window-system, GPU and file-dialog libraries DeckCraft needs are opened
+when the app starts (`dlopen` through `x11-dl`, `xkbcommon-dl`, `ash`, `glutin` and `rfd`) instead
+of being linked in, so `ldd` shows none of them: an install that satisfies the linked dependencies
+can still fail at start-up with a loader error and no hint of what to install. Only
+`libasound.so.2` (slide-show sound) is a hard link-time dependency, and only of the `deckcraft`
+GUI — `deckcraft-cli` uses neither sound nor a display. The `.deb` and `.rpm` declare the set in
+`packaging/linux/nfpm.yaml`; a tarball install or a musl system has to provide it itself:
+
+```sh
+apk add libx11 libxcursor libxrandr libxi libxkbcommon xkeyboard-config \
+        wayland-libs-client alsa-lib \
+        vulkan-loader mesa-vulkan-swrast \
+        mesa-gl mesa-egl mesa-dri-gallium \
+        xdg-desktop-portal
+```
+
+Alpine Linux `v3.22` names above; Void's musl variant uses the same `/lib/ld-musl-x86_64.so.1`
+loader and the same libraries as `libX11 libXcursor libXrandr libXi libxkbcommon xkeyboard-config
+wayland alsa-lib vulkan-loader mesa xdg-desktop-portal`. There is no musl build among the release
+artifacts yet — this is what a build from source on musl needs at run time, and what a future musl
+artifact will need (#954).
+
+- `mesa-vulkan-swrast` is the software Vulkan driver: it runs anywhere, VMs and containers
+  included. On a real GPU install your vendor's driver instead (`mesa-vulkan-intel`,
+  `mesa-vulkan-ati`, `mesa-vulkan-nouveau`, …).
+- Without Vulkan the app falls back to CPU rendering through Mesa's GL drivers. It works, but
+  slowly — a driver limit, not a DeckCraft bug.
+- `xdg-desktop-portal` (with `xdg-desktop-portal-gtk` or `-kde`; `-wlr` has no file chooser, so
+  on wlroots compositors install `zenity`) is what the Open and Save dialogs talk to; `xkeyboard-config` holds the XKB keyboard data `libxkbcommon` reads.
+- fontconfig and freetype are not needed: DeckCraft reads `/usr/share/fonts` itself and embeds its
+  presentation fonts.
+
+Building from source on musl also needs `build-base pkgconf alsa-lib-dev` (`alsa-lib-dev` is the
+ALSA headers).
+
 ### FreeBSD
 
 | Build | File |

ROADMAP.md

@@ -150,6 +150,7 @@ app's JSON control channel (`deckcraft --control PORT`).
 | 2026-10-18 | Resizing with the mouse snaps the edge being dragged to the slide, guides and other shapes: a fixed edge that already lined up used to take the snap and leave the dragged edge free, and a fixed edge near a line shifted the dragged one (#961) |
 | 2026-10-18 | Slide show: a video or audio clip is looked up on the slide it belongs to, so slides whose shape ids repeat (the PPTX import numbers each slide afresh) no longer play each other's clips (#994) |
 | 2026-10-18 | About: Contributors and Models get their own fixed-size block below the tab row, so the tab row is no longer squeezed into the credits and the tabs keep answering (#843) |
+| 2026-10-19 | README: the Linux runtime libraries a tarball or musl install has to provide — the `dlopen`ed X11/Vulkan/GL/dialog libraries with their Alpine and Void package names, the software-Vulkan fallback, and why fontconfig and freetype are not among them (#955) |
 | 2026-10-17 | Opening a file caps absurd effect sizes (glow, soft edges, shadows, reflections, on shapes, text and table text) at what Format Shape allows: a glow of 10^18 pt in a .pptx made rendering ask for 34 GB and abort |
 | 2026-10-17 | Opening a .deckcraft file whose shapes repeat an id gives the repeats fresh ids (groups, layouts and masters too), so the deck validates and edits by id find one shape |
 | 2026-10-17 | Edit Points: turning a shape into a freeform is one undo step, so Undo brings the original shape back (it used to stay a freeform) |