mjdev-desktop/.claude/skills/mjdev-package-dependencies/SKILL.md

---

name: mjdev-package-dependencies

description: Multiplatform packaging rule for mjdev — every distributable that has runtime dependencies must declare them through that package format's native dependency mechanism (deb Depends, rpm Requires, …) so the OS package manager resolves them on install; if the format has no dependency system, bundle the dependencies inside the package. Use when building/reviewing deb/rpm/AppImage/exe/msi/dmg/flatpak/apk packaging so a clean install "just works" on any machine.

Packaging: declare deps natively, else bundle them

Goal: a user who gets a package and installs it must be able to use the app on any machine — the package pulls or carries everything it needs. Never ship a package that silently misses a runtime dependency (that is what black-screened fresh installs).

The rule

For each distributable, put runtime dependencies where that format resolves them:

Format	Dependency mechanism (preferred)	If not possible → bundle
.deb	Depends: (+ Recommends:) in DEBIAN/control → apt resolves	ship the lib in the package + ldconfig/rpath
.rpm	Requires: tags → dnf/zypper resolve	ship the lib in the package
AppImage	none — bundle everything in the AppDir (that's the point of AppImage)	(always bundle)
.exe/.msi	installer prerequisites / bundled redistributables	bundle DLLs next to the exe
.dmg/.pkg	macOS frameworks / @rpath	bundle dylibs in the .app
flatpak	runtime + extensions in the manifest	bundle in the sandbox
.apk	gradle deps compiled in (self-contained)	(always self-contained)

Prefer the native dependency system (smaller package, shared/updated libs). Only bundle when the format has no resolver (AppImage) or the dep is unavailable / ABI-pinned on the target distro.

Single source of truth (no hardcode — see [[mjdev-code-conventions]])

Keep the dependency list in one place (the version catalog: app-compositor-runtime-deps) and feed every packager + installer + ISO from it. Don't copy the list into each packaging step.

TWO product shapes — don't conflate them

1. Full desktop session = deb / rpm / live ISO. Ships the compositor (mjdevc) + mjdev-session
   • the wayland-sessions entry, and the app runs as the session shell. THESE need the wayland runtime stack (libwlroots/xwayland/mesa/seatd) declared/bundled — a clean/console box has no compositor. The desktop session is Linux-only.
2. Standalone app = AppImage / exe / msi / dmg / apk. The app runs as a normal window on the user's EXISTING desktop (GNOME/KDE/other wayland or X) — that environment already provides a compositor. So do NOT bundle mjdevc / wlroots here; just ship the self-contained app (jpackage already bundles the JRE + Skiko). On a real desktop GPU, Skiko uses hardware GL normally.

This project's reference

• deb (shape 1): PackageFullDebTask (buildSrc) injects compositor + session and appends the wayland runtime stack to Depends (from the catalog), so apt install ./mjdev-desktop.deb pulls libwlroots/xwayland/mesa/seatd on a clean console Linux.
• rpm (shape 1): same completeness via Requires: (rpm rebuild) — TODO.
• AppImage/exe/dmg/apk (shape 2): leave as jpackage produces — self-contained app, no compositor.
• buildAll (and the GitHub Actions release) must emit ALL formats — the more platforms the better.