RFC: desktop: block — source-built GUI apps, first-class on the desktop (alternative to Cask)

[tannevaled]

Problem

pkgx + pantry currently package CLIs and libraries beautifully (~1500 source-built recipes covering compilers, daemons, build tools, libraries, etc.). But for graphical applications, we have a gap:

• A pantry recipe like mpv.io or inkscape.org builds the binary, but does not register it with the OS's app-launcher (/Applications on darwin, ~/.local/share/applications on linux freedesktop). Users can run pkgx mpv … from a terminal but the app doesn't appear in Spotlight / GNOME Activities / KDE Krunner / Cinnamon's menu.
• The dominant solution in homebrew is Cask — but Cask is fundamentally a vendored binary distribution channel. A Cask formula downloads a pre-built .dmg/.pkg from upstream and copies it to /Applications. That is the opposite of pkgx's source-first philosophy and explicitly what pantry tries to avoid (warnings: - vendored is the carve-out, not the norm).
• We need a way to register GUI apps with the desktop session that preserves the source-build property.

This is an RFC for a new optional recipe block: desktop:.

Proposal — desktop: block in package.yml

A new top-level optional key on any pantry recipe whose binary is a GUI app. Purely additive — recipes that don't define desktop: behave exactly as today.

Recipe-side schema

# projects/inkscape.org/package.yml
distributable: …
versions: …
build: …
provides:
  - bin/inkscape

desktop:
  name: Inkscape
  comment: Professional vector graphics editor
  categories: [Graphics, VectorGraphics, GTK]    # freedesktop XDG categories
  mime-types: [image/svg+xml, image/svg+xml-compressed, application/pdf, …]
  icon: share/inkscape/icons/inkscape.svg        # path relative to {{prefix}}
  bin: bin/inkscape                              # which provides entry is the launcher
  # optional per-OS overrides
  darwin:
    bundle-id: org.inkscape.Inkscape
    # icns auto-generated from icon: if absent
  linux:
    startup-wm-class: org.inkscape.Inkscape      # X11 WM_CLASS for icon-grouping
    terminal: false

What pkgm / pkgx does with this

When pkgm install inkscape.org runs, after the normal bottle-relocation:

• linux: synthesize a .desktop file under ${PREFIX}/share/applications/<name>.desktop from the desktop: block, then symlink/install it to the user's ~/.local/share/applications/ (or system path under --system). Run update-desktop-database if available.
• darwin: synthesize a *.app bundle skeleton under ${PREFIX}/Applications/<Name>.app/ with a generated Info.plist from desktop: (CFBundleIdentifier from bundle-id, CFBundleIconFile from generated icns, CFBundleExecutable as a small shim that exec's ${PREFIX}/bin/<bin>), then symlink to /Applications (or ~/Applications).
• uninstall symmetrically removes the synthesized launchers.

Why this is not Cask

	Cask	desktop:
Binary origin	upstream-vendored .dmg/.pkg	pantry source-build (build.script)
Reproducibility	depends on upstream not rotating the artifact	full source-from-tag, hash-verified tarball
Trust model	implicit trust in vendor's signing chain	same trust as every other pantry recipe
Update cadence	tied to upstream's release pace + Cask maintainer	versions: polls upstream + pantry CI
Sandbox	none — Cask runs installer(8) privileged	brewkit sandbox, then relocation, no privileged install

The desktop: block is just metadata for registration. The binary itself remains a pantry-built bottle.

What I'd like guidance on

1. Recipe-side surface — does the proposed schema feel right, or should it be flatter / split per-OS? I'm specifically uncertain about the mime-types: shape and whether categories: should be freedesktop-string or pkgx-abstract.
2. pkgm integration vs. a separate verb — should pkgm install <pkg-with-desktop> automatically register, or should there be an explicit pkgm app-register <pkg> (and the inverse app-unregister)? Auto-register matches user expectation, but breaks the "pkgm only installs to /usr/local" model.
3. Icons — accept any image; on darwin auto-convert SVG/PNG → .icns via iconutil (already in the Xcode toolchain, pantry can shell out). On linux just install the SVG/PNG to ${PREFIX}/share/icons/hicolor/…/apps/. Reasonable?
4. First-recipe candidates — once landed, the obvious first recipes to retrofit: inkscape.org, mpv.io, gimp.org, wireshark.org, audacity-team.org, videolan.org/vlc. Any one of these can prove the design end-to-end.
5. Schema validation — desktop: should be fully optional. CLI-only recipes (the vast majority) need zero changes. Adding a bad desktop: block should warn, not fail CI.

Non-goals (deliberately)

• No vendored binaries. This RFC does not propose a Cask-style binary distribution channel. The day pantry accepts pre-built GUI app bundles is the day pkgx becomes just-another-homebrew. The point of desktop: is to make the source-built GUI apps we already produce first-class on the desktop.
• No GUI installer. This is a pkgm/pantry feature, not a desktop-app-store UI. Users still install via pkgm install <pkg>.
• No replacement for Flatpak/Snap/AppImage. Those bundle the whole runtime; we're using the host's runtime (pantry-bottled deps), which is the point of pkgx.

Implementation sketch (rough)

1. Schema (pantry): add desktop: to the recipe JSON schema. Add a CI lint check that catches typos in categories/mime-types.
2. Manifest carry-over (brewkit): bottle the desktop: block as a desktop.yml next to the existing manifest inside the bottle tarball, so consumers (pkgm) can read it back without re-reading pantry.
3. pkgm: on install, if desktop.yml exists in the bottle, run the per-OS registration step.
4. pkgx run (optional, later): if the user runs pkgx <gui-app> and the app has desktop.terminal: false, detach from the parent shell.

Prior art reviewed

• Homebrew Cask — vendored, not source. Reference for darwin Info.plist shape.
• nixpkgs makeDesktopItem — Nix function generating .desktop files. Closest to what I'm proposing; the desktop: block is essentially a declarative version.
• freedesktop.org Desktop Entry spec 1.5 — authoritative for the linux side.
• Apple's CFBundle docs — authoritative for the darwin side.

Status

Posting this as an Ideas discussion (not a PR) to gather feedback on the shape before writing code. Happy to drive the pantry-side schema PR + a reference pkgm-side patch once direction is agreed.

---

— posted from a contributor currently active on pantry (recent PRs: #13099, #13100, #13102, #13103, #13104, #13106, #13107, #13108, #13111, #13112, brewkit#350)