Adding a Gnome/GTK app as a sysext produces a broken desktop icon

[bketelsen]

[frostyardyeti]

— Automated by Yeti —

Implementation Plan

Implementation Plan for Issue #164: Broken Desktop Icons for GTK Sysexts

Clarifying Questions

The issue has no description, so several details need confirmation before a fully reliable plan can be written:

1. What does "broken desktop icon" mean specifically?

   • (a) The app appears in GNOME's app grid but shows a generic/missing icon instead of the app's actual icon?
   • (b) The app's .desktop entry doesn't appear in the app grid at all?
   • (c) Something else (corrupted rendering, wrong icon, etc.)?

2. Is this specifically about the emdash sysext, or has it been observed with other apps too?

   • Emdash is currently the only GTK app sysext in the repo. Is the intent to fix emdash and establish a reusable pattern for future GTK sysexts, or is there a new sysext being added that triggered this?

3. What does the Icon= field in emdash's .desktop file look like after the build?

   • If it's an absolute path like Icon=/opt/Emdash/resources/app/icon.png, the relocation to /usr/lib/emdash breaks it (the postinstall only patches Exec=, not Icon=).
   • If it's an icon name like Icon=emdash, the issue is about icon theme cache staleness instead.
   • This determines which fix path is needed.

4. Where does the emdash .deb install its icon files?

   • Into /usr/share/icons/hicolor/<size>/apps/ (standard FreeDesktop location)?
   • Into /opt/Emdash/ alongside the binary (Electron app bundle)?
   • Into /usr/share/pixmaps/?

5. Should the fix be build-time only, or also include a runtime cache regeneration mechanism?

   • Build-time: rebuild icon-theme.cache during the sysext build (sufficient if only one GUI sysext provides icons at a time).
   • Runtime: add a systemd service that regenerates caches after sysext merge at boot (handles multiple GUI sysexts but more complex since /usr is read-only).

Please respond to these questions as a comment on issue #164 so the next refinement cycle can produce a complete plan.

---

Partial Plan (for aspects that are sufficiently clear)

Based on the code analysis, the following problems are identifiable regardless of the answers above, and can be planned now:

Problem Analysis

The emdash sysext postinstall (mkosi.images/emdash/mkosi.postinst.chroot:25) patches the Exec= path in the .desktop file after relocating from /opt/Emdash to /usr/lib/emdash, but does not:

1. Patch the Icon= field (if it references /opt/Emdash/...)
2. Create icon symlinks in /usr/share/icons/hicolor/ (the pattern used by Edge in shared/packages/edge/mkosi.postinst.d/edge.chroot:20-23)
3. Run gtk-update-icon-cache to rebuild the icon theme cache
4. Run update-desktop-database to rebuild the desktop MIME cache

The Bitwarden postinstall (shared/packages/bitwarden/mkosi.postinst.d/bitwarden.chroot:29) has the same gap — it patches Exec= but not Icon=. However, Bitwarden is only used in desktop images (snowloaded), where the full GNOME environment may paper over this via fallback icon scanning. In the sysext context (overlay on a headless base), this is more fragile.

Changes Required

1. mkosi.images/emdash/mkosi.postinst.chroot — Fix icon handling after relocation

What to change:
After the existing sed that patches Exec=, add:

• A sed command to patch the Icon= field if it references /opt/Emdash/ (replace with the relocated path under /usr/lib/emdash/)

• OR (if the .deb installs icons to hicolor and Icon= is just a name): create explicit icon symlinks in /usr/share/icons/hicolor/<size>/apps/ pointing to the relocated icon files, following the Edge postinstall pattern:

  mkdir -p /usr/share/icons/hicolor/{16x16/apps,24x24/apps,32x32/apps,48x48/apps,64x64/apps,128x128/apps,256x256/apps}
  for size in 16 24 32 48 64 128 256; do
      ln -sf /usr/lib/emdash/resources/app/icons/${size}x${size}.png \
             /usr/share/icons/hicolor/${size}x${size}/apps/emdash.png
  done

  (Exact source paths depend on clarifying question feat: bitwarden extension #4 — the icon file locations inside the .deb.)

• Run gtk-update-icon-cache /usr/share/icons/hicolor/ to rebuild the icon cache with the sysext's icons included

• Run update-desktop-database /usr/share/applications/ to rebuild the MIME type cache

Why: The .desktop file's icon reference is broken after /opt relocation. Without icon cache regeneration, GTK uses the stale cache from the base image's package triggers and cannot find the sysext's icons.

2. shared/outformat/image/finalize/mkosi.finalize.chroot — Add icon cache and desktop database rebuild for desktop images

What to change:
After the existing glib-compile-schemas and dconf update blocks (lines 31-38), add:

# Rebuild icon theme caches
if command -v gtk-update-icon-cache >/dev/null 2>&1; then
    for dir in /usr/share/icons/*/; do
        if [[ -f "${dir}index.theme" ]]; then
            gtk-update-icon-cache -f "${dir}"
        fi
    done
fi

# Rebuild desktop database
if command -v update-desktop-database >/dev/null 2>&1; then
    update-desktop-database /usr/share/applications/
fi

Why: The desktop image finalize script currently compiles GLib schemas and dconf databases but does not rebuild icon caches or the desktop MIME database. After postinstall scripts install and relocate apps (Edge, Bitwarden, Azure VPN, etc.) with new icons and .desktop files, these caches need regeneration. This fixes desktop images and also ensures the base image's icon cache is comprehensive (which sysexts inherit via BaseTrees).

Implementation Order

1. First: Update shared/outformat/image/finalize/mkosi.finalize.chroot — this ensures desktop images and the base image have correct caches, and it's a standalone improvement
2. Second: Update mkosi.images/emdash/mkosi.postinst.chroot — fix the emdash-specific icon handling (depends on answers to clarifying questions for exact paths)

Dependencies

• Change firmware #2 depends on knowing the emdash .deb's icon file locations and Icon= field format (clarifying questions feat: edge, nordvpn #3 and feat: bitwarden extension #4)
• Change chore: attempting package parity with snow #1 is independent and can proceed immediately

Risks and Edge Cases

1. Multiple GUI sysexts providing hicolor icons: If a second GTK sysext is added later, both would have their own icon-theme.cache in the overlay. Only one wins (last-merged sysext). This is a known limitation of the sysext overlay model. A runtime cache regeneration service would be needed for that case, but it's blocked by read-only /usr. This is an acceptable risk for now since emdash is the only GUI sysext.

2. gtk-update-icon-cache not available in sysext build: The emdash sysext installs libgtk-3-0 which should pull in gtk-update-icon-cache. Verify this is the case — if not, add the package providing it (typically libgtk-3-bin on Debian) to the sysext's Packages= list.

3. update-desktop-database not available: This is provided by desktop-file-utils. Verify it's available in the build chroot. If not, add it to Packages=.

4. Base image has no icon theme: The base image is headless with no GTK packages. The finalize script change (chore: attempting package parity with snow #1) uses command -v guards so it's a no-op for the base image. Only affects desktop image profile builds where GTK is present.

5. Icon paths vary between Electron app versions: The specific icon file paths inside the .deb (e.g., resources/app/icons/) may change between emdash releases. The postinstall script should verify the icon source path exists before creating symlinks.

Testing Approach

• Manual verification: Build the emdash sysext (just sysexts), merge it on a running system, and confirm the icon appears correctly in GNOME's app grid
• Build-time check: After the postinstall runs, verify that /usr/share/icons/hicolor/*/apps/emdash.png exists and that icon-theme.cache references it
• Desktop image check: Build a snow/snowloaded image and verify Edge, Bitwarden, and Azure VPN icons render correctly (regression check for change chore: attempting package parity with snow #1)

[frostyardyeti]

— Automated by Yeti —

Plan Review

1. The plan misses the most basic integration point: the emdash sysext does not currently wire in its postinstall script. mkosi.images/emdash/mkosi.conf has no PostInstallationScripts=..., while a sysext that does use one declares it explicitly in mkosi.images/nix/mkosi.conf. The plan proposes editing mkosi.images/emdash/mkosi.postinst.chroot but never mentions the file that actually has to be changed to make that script run.

2. The proposed change to shared/outformat/image/finalize/mkosi.finalize.chroot is over-broad and likely does not address the sysext bug. That finalize hook is only referenced by full image profiles, not by sysext builds, as seen in mkosi.profiles/snow/mkosi.conf and related profiles. Rebuilding icon caches inside the base desktop image cannot make those caches aware of files that only appear later through a sysext overlay. For a sysext-specific broken icon, the fix needs to live in the sysext content or in a sysext-specific build hook, not in the generic image finalize path.

3. The plan treats icon-theme cache regeneration and update-desktop-database as established root causes, but the repo does not support that conclusion. The existing Edge relocation script only adds hicolor symlinks and path fixes in shared/packages/edge/mkosi.postinst.d/edge.chroot; it does not rebuild caches. That points to the more likely fix being “make the icon discoverable at the expected path/name”, not “add global cache rebuilds everywhere”. update-desktop-database is especially suspect here because it is for desktop MIME metadata, not icon lookup.

4. If the implementation really does require gtk-update-icon-cache or update-desktop-database, the plan omits the file that must change to provide those binaries in the emdash sysext build. mkosi.images/emdash/mkosi.conf currently lists only runtime libraries. The plan mentions missing-tool risk, but leaves the dependency update as a note instead of part of the required changes.

5. The testing section is too weak for this regression and adds no lasting coverage. The existing sysext test only checks that sysext machinery exists in the image, not that a merged GUI sysext exposes a working desktop entry or icon, as shown in test/tests/03-sysexts.sh. A credible plan should include at least one deterministic verification step against the built emdash sysext contents, such as asserting the final emdash.desktop Icon=/Exec= values and the expected icon file or symlink paths.

Open questions:

• The plan still depends on unverified assumptions about the actual Icon= value and icon install locations inside the emdash .deb. Without resolving that first, the proposed sed vs symlink branch is not implementation-ready.
• If the current missing PostInstallationScripts wiring means relocation never runs, the reported symptom may not be “just the icon” at all.

[bketelsen]

The proposed fix largely misses the mark. Here's why:

1. The Icon= field is already correct. It's set to Icon=emdash (a theme name, not an absolute path like
   /opt/Emdash/...), so the proposed sed to patch the Icon= field would be a no-op.
2. The icon files already exist in the right places. All standard hicolor sizes are populated at
   /usr/share/icons/hicolor/*/apps/emdash.png, so creating symlinks (the Edge pattern) is redundant.
3. The plan review nails the real problems:
   - The postinstall script isn't even wired in — mkosi.images/emdash/mkosi.conf has no
   PostInstallationScripts= entry, so none of the proposed changes to the postinstall would run.
   - The finalize hook change targets full image builds, not sysext builds, so it can't fix sysext icons.
   - update-desktop-database is for MIME metadata, not icon lookup — it's irrelevant here.

The one thing that might actually matter is gtk-update-icon-cache. Since this is a sysext overlay, the
base system's icon-theme.cache was built before the sysext was merged, so GTK may not find the icons
even though the files are on disk. But that cache rebuild needs to happen inside the sysext build (so
the sysext overlays the stale cache with an updated one), and the current plan doesn't ensure that path
works.

In short: the diagnosis is incomplete and most of the proposed changes address problems that don't exist
on this system. The icon cache is the likely culprit, but the plan doesn't wire it up correctly.

[frostyardyeti]

— Automated by Yeti —

Implementation Plan

Now I have a complete picture. Let me produce the implementation plan.

---

Implementation Plan for Issue #164: Broken Desktop Icons for GTK Sysexts

Root Cause Analysis

The emdash sysext installs icon files to /usr/share/icons/hicolor/*/apps/emdash.png (confirmed by @bketelsen: files exist in the right places, Icon=emdash is correct). The icons are broken because of stale icon-theme.cache files.

Here's why: Desktop images build icon-theme.cache via dpkg triggers during package installation. This cache indexes all icons known at image build time. When the emdash sysext is merged via OverlayFS at runtime, it adds new icon files to the hicolor directory tree, but the existing icon-theme.cache in the desktop image doesn't know about them. GTK uses the cache exclusively when it exists — it doesn't fall back to directory scanning — so the emdash icon is invisible.

Key constraint: Rebuilding the cache inside the sysext build would create a sysext-layer icon-theme.cache that shadows the desktop image's cache via OverlayFS. Since the sysext build starts from BaseTrees=%O/base (the headless base image, not the desktop image), the sysext's cache would only contain base + emdash icons, breaking all other desktop icons. This approach is not viable.

Correction to Prior Plan Review

The plan review and @bketelsen's comment both state the emdash postinstall script isn't wired in because mkosi.images/emdash/mkosi.conf lacks PostInstallationScripts=. This is incorrect — mkosi v24+ auto-discovers mkosi.postinst.chroot files in image directories. Multiple other sysexts (docker, tailscale, incus, podman) follow this same pattern: they have mkosi.postinst.chroot files without explicit PostInstallationScripts= declarations and function correctly. The nix sysext's explicit PostInstallationScripts=mkosi.postinst.chroot is redundant.

Changes Required

1. shared/outformat/image/finalize/mkosi.finalize.chroot — Remove icon-theme.cache files

What to change: After the existing dconf update block (line 37-38), add:

# Remove icon-theme.cache files so GTK falls back to directory scanning.
# This is required for sysext overlays: sysexts add icon files via OverlayFS
# but cannot update the desktop image's pre-built cache. Without the cache,
# GTK scans icon directories at runtime and finds icons from all layers.
for dir in /usr/share/icons/*/; do
    rm -f "${dir}icon-theme.cache"
done

Why: Without this change, the desktop image ships a icon-theme.cache that doesn't include sysext icons. GTK uses this cache exclusively and never finds the emdash icon. Removing the cache forces GTK to scan icon directories at runtime, which correctly sees files from both the desktop image layer and any sysext overlay layers. The performance impact is negligible — GTK builds an in-memory hash table on first icon lookup, and the directory scan takes under 100ms on modern hardware.

Secondary benefit: This also fixes a latent issue where icons added by PostInstallationScripts (Edge relocation at shared/packages/edge/mkosi.postinst.d/edge.chroot:20-23, Bitwarden at shared/packages/bitwarden/mkosi.postinst.d/bitwarden.chroot) aren't in the cache that dpkg triggers built before those scripts ran.

Implementation Order

Single change to a single file. No dependencies.

Risks and Edge Cases

1. Performance: Removing icon-theme.cache adds a one-time directory scan overhead per GTK process launch. On typical hicolor directories with hundreds of icons, this is <100ms and barely perceptible. GTK caches icons in memory after the first lookup.

2. Multiple GUI sysexts: This fix handles any number of GUI sysexts correctly — directory scanning sees all icons from all overlay layers. No per-sysext cache management needed.

3. Non-hicolor icon themes: The for dir in /usr/share/icons/*/ loop removes caches from all icon themes (Adwaita, hicolor, etc.). This is intentional — any theme could have sysext-provided icons. If performance concerns arise for large themes, the loop could be narrowed to hicolor only, but this shouldn't be necessary.

4. Base image unaffected: The finalize script only runs for desktop image profiles (FinalizeScripts= in snow/snowloaded/snowfield/snowfieldloaded/cayo/cayoloaded profiles). The headless base image and sysext builds don't use this finalize script.

Testing Approach

1. Build-time verification: After building a desktop image (just snow), confirm that no icon-theme.cache files exist under /usr/share/icons/ in the output image.

2. Runtime verification: Boot a desktop image with the emdash sysext merged, open GNOME's app grid, and confirm the emdash icon displays correctly. Also verify that standard GNOME application icons (Settings, Files, Terminal) still display correctly — this confirms the directory scanning fallback works for all icons.

3. Regression check: Verify that Edge and Bitwarden icons display correctly in snowloaded builds (these should improve or remain the same since their postinstall-added icons were also potentially missing from the stale cache).

[frostyardyeti]

— Automated by Yeti —

Plan Review

Findings:

1. The fix is incomplete if the emdash sysext itself contains icon-theme.cache.
   The plan only deletes caches from the desktop image via shared/outformat/image/finalize/mkosi.finalize.chroot (used at lines 30-38 today), but emdash is built separately from mkosi.images/emdash/mkosi.conf with BaseTrees=%O/base, and installs its package in mkosi.images/emdash/mkosi.postinst.chroot. If dpkg triggers generate /usr/share/icons/*/icon-theme.cache inside the sysext during that install, the sysext layer can still shadow the image-side state. The plan needs an explicit verification step for the sysext artifact, and likely a sysext-side cleanup hook if those cache files exist.

2. The stated blast radius is wrong: this finalize script is not desktop-only.
   The plan says the shared finalize script only runs for desktop profiles, but mkosi.profiles/cayo/mkosi.conf:20 and mkosi.profiles/cayoloaded/mkosi.conf:23 both use the same shared/outformat/image/finalize/mkosi.finalize.chroot. That does not make the change invalid, but it does mean the plan understates scope and omits server-image regression risk.

3. The testing plan is too manual and misses the actual risk boundary.
   Current automated sysext coverage in test/tests/03-sysexts.sh only checks that sysext machinery exists, not that a GUI sysext icon resolves after merge. The proposed tests also only mention “build snow” and then manual app-grid inspection, but do not require checking:

• that the desktop image artifact has no icon-theme.cache
• that the emdash sysext artifact also has no conflicting icon-theme.cache
• how the sysext is activated in the runtime test
  Without at least deterministic artifact-level assertions, this is easy to regress silently.

Open question:

• The root-cause section is very confident about GTK cache behavior, but the plan does not include any artifact inspection step to prove whether the broken icon comes from the image cache, a sysext cache, or both. That proof should be part of the implementation plan before changing a shared finalize hook.