Skip to content

Load plugins through per-rescan shims so hot reload recompiles - #15023

Open
kstorm12 wants to merge 1 commit into
omacom:quattrofrom
kstorm12:fix/plugin-hot-reload-recompile
Open

kstorm12 wants to merge 1 commit into
omacom:quattrofrom
kstorm12:fix/plugin-hot-reload-recompile

Conversation

@kstorm12

Copy link
Copy Markdown

Problem

Editing a plugin (or running omarchy-shell shell rescanPlugins) does not pick
up the change: the shell keeps running the old code, and a bar widget can
vanish from the bar, until the shell is restarted.

finishPluginReload in shell.qml tried to force a recompile with

if (typeof Qt.clearComponentCache === "function") Qt.clearComponentCache()

but clearComponentCache is a method of QQmlEngine, not of the QML Qt
object, so the guard is always false and the call never runs. The QML engine
caches compiled components by URL for its whole lifetime and exposes no QML API
to clear that cache, so re-loading the same URL always returns the cached
component.

Fix

Load every plugin through a fresh URL on each rescan:

  • PluginRegistry.rescan() symlinks each plugin source dir into a new
    per-rescan revision dir under the shell cache (loadRoot) and emits the load
    dir alongside the source dir in its scan output
    (===<kind>::<source>::<load>===).
  • The manifest records __loadDir (falling back to __sourceDir), and
    entryPointUrl() resolves the entry point through it. The component URL
    therefore changes on every rescan and the engine recompiles the entry point
    and its relative imports.
  • Shim creation is best-effort: if the cache is unwritable the load dir falls
    back to the source dir, so behavior is unchanged. Older revisions are left in
    place for the session so preserved keepLoaded services keep resolving, and
    ensureUserDir() wipes stale shims at startup.
  • No new engine is built, so keepLoaded services (for example the lock) are
    not dropped.

A two-field scan line (===<kind>::<source>===) still parses and resolves
through the source dir, so the format change is backward compatible.

Testing

  • test/shell.d/plugin-registry-contract-test.sh is extended with checks that a
    three-field line records __loadDir, that entryPointUrl() resolves through
    it, and that a two-field line falls back to the source dir. The new checks
    fail against the current quattro and pass with this change.
  • Verified live: edited an on-bar widget, ran rescanPlugins, and saw the
    edited code run; a second edit also took effect. Startup and every rescan
    create a fresh rev.* dir, so each edit gets a new URL.

Fixes #10729.

Qt.clearComponentCache() is not a member of the QML Qt object, so the
guarded call in finishPluginReload was a no-op and the engine kept
serving the cached component after an edit. The engine caches compiled
components by URL for its lifetime and gives QML no way to clear it.

rescan() now symlinks each plugin source dir into a fresh per-rescan dir
under the shell cache and emits it alongside the source dir;
entryPointUrl() loads through it, so the component URL changes and the
engine recompiles the entry point and relative imports, without building
a new engine and dropping the keepLoaded services. Shim creation is
best-effort and falls back to the source dir if the cache is unwritable.
@greptile-apps

greptile-apps Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 3/5

[Medium impact] Plugin hot-reload mechanism now uses per-rescan symlink directories.

Fix the missing indicator paths and the startup cleanup race before merging.

Findings

  1. P1 Indicator icons disappear ▶
  2. P1 Startup deletes fresh plugin links ▶
  3. P2 Valid plugin paths break ▶
  4. P2 Reload behavior lacks coverage ▶

Summary

The PR gives each plugin scan fresh load URLs through directory symlinks and adds checks for the new scan format.

  • Plugin rescans load edited code through fresh URLs.

Intentional choices stated by kstorm12: keepLoaded services remain alive, old revisions remain available during the session, and failed shim creation falls back to source paths.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Shell startup] --> B[Cleanup process]
  A --> C[First scan process]
  B --> D[Delete load directory]
  C --> E[Create revision and plugin links]
  E --> F[Emit fresh load URLs]
  D -. may delete .-> E
  B --> G[Request another scan]
  G --> H{Scan still running?}
  H -->|Yes| I[Skip follow-up scan]
  F --> J[Load plugin components]
Loading

Reviews (1) · Last reviewed commit: "Load plugins through per-rescan shims so..." · Reviewed by Greptile

+ " if [[ ${manifest##*/} == \"manifest.json\" ]]; then sub=\"${manifest%/manifest.json}\"; else sub=\"$(dirname -- \"$manifest\")\"; fi; "
+ " printf '===%s::%s===\\n' \"$kind\" \"$sub\"; "
+ " target=\"${sub%/}\"; load=\"$sub\"; "
+ " if [[ -n $rev_dir ]]; then shim=\"$rev_dir/$(printf '%s' \"$target\" | md5sum | cut -c1-16)\"; if ln -sfn \"$target\" \"$shim\" 2>/dev/null; then load=\"$shim\"; fi; fi; "

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Indicator icons disappear

The shim for Indicators.qml points only to bar/widgets, where its manifest lives. The widget uses Qt.resolvedUrl("../indicators/" + …), which now points to rev.*/indicators/ instead of bar/indicators/. Those files cannot load, so the configured indicator icons disappear. Preserve the surrounding directory layout when creating fresh load URLs.

Knowledge Base Used: Shell UI and desktop interactions

function ensureUserDir() {
initProcess.command = ["bash", "-c", "mkdir -p \"$0\"", registry.pluginsDir]
// Wipe stale load shims from the previous shell run before the first scan.
initProcess.command = ["bash", "-c", "mkdir -p \"$0\" && rm -rf \"$1\" && mkdir -p \"$1\"", registry.pluginsDir, registry.loadRoot]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Startup deletes fresh plugin links

ensureUserDir() starts cleanup in one process, while shell.qml immediately calls rescan() in another. Cleanup can remove a shim after the scan has emitted its URL. If cleanup finishes while scanning is still true, its follow-up scan is skipped. The first scan then publishes URLs to deleted files, leaving plugins unable to load. Wait for cleanup before starting the first scan.

Comment on lines +623 to +629
var separator = startMatch[2].indexOf("::")
if (separator === -1) {
currentSource = startMatch[2].replace(/\/$/, "")
currentLoad = currentSource
} else {
currentSource = startMatch[2].slice(0, separator).replace(/\/$/, "")
currentLoad = startMatch[2].slice(separator + 2).replace(/\/$/, "")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Valid plugin paths break

Splitting at the first :: breaks valid source directory names containing those characters. A manually installed plugin under plugins/acme::clock/ is scanned, but this parser records plugins/acme as its source and clock::<shim> as its load directory. Its entry point then points to the wrong file. Escape or encode the path fields instead of splitting raw paths.

Comment on lines +466 to +469
registry.parseScanOutput(block("thirdparty", "/third/regression", manifest("third.regression", ["panel"], { panel: "Panel.qml" }), "/load/rev-a/regression"))
root.assertEqual(registry.installedPlugins["third.regression"].__sourceDir, "/third/regression", "a load-dir line keeps the source dir")
root.assertEqual(registry.installedPlugins["third.regression"].__loadDir, "/load/rev-a/regression", "a load-dir line records the per-rescan dir")
root.assertEqual(registry.entryPointUrl(registry.installedPlugins["third.regression"], "panel"), "file:///load/rev-a/regression/Panel.qml", "entryPointUrl loads through the per-rescan dir")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Reload behavior lacks coverage

These assertions only parse invented scan lines and compare URL strings. They do not check that rescan() creates usable shims or that edited QML runs after a second scan. Add a test with a real temporary plugin that loads, changes, rescans, and returns the changed value. That would protect the actual hot-reload fix rather than just its scan format.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

@jandrusk

Copy link
Copy Markdown

Good find that Qt.clearComponentCache was never reachable from QML. A few things before this is ready:

  • ensureUserDir() now runs rm -rf "$loadRoot". If the first rescan() starts before initProcess finishes, startup can delete the fresh rev.* links (Greptile flagged this too). Chaining the first scan off initProcess.onExited, or creating the revision dir inside the same script that wipes the old ones, would avoid the race.
  • entryPointUrl() now resolves through the shim, but other paths, such as indicator icon assets, still build from __sourceDir. Mixing the two may be fine, but it's worth a test showing that relative assets and imports load from both.
  • Overlap: Fix hot reload of local plugins by busting the component cache #13911 ("Fix hot reload of local plugins by busting the component cache") is open for the same goal. It's worth checking which approach maintainers prefer.

@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed at f4955e3, by reading this diff and the competing ones against current quattro. Nothing was run on a worker. A fix that is not the one being recommended isn't worth one, and this branch also conflicts with quattro now, after #15163 rewrote the scan script.

The diagnosis is right. Qt.clearComponentCache is not on the QML Qt object, so the guard in finishPluginReload never fires. Moving the whole plugin directory to a new URL is also the one approach so far that makes a sibling Helper.qml or Model.js recompile without rebuilding the engine. But as written it breaks two things, so this is not the fix I'm recommending.

  • The bar's indicators stop loading, at startup and not only on reload. The shim links only the directory that holds the manifest. omarchy.indicators is in the default bar, and its manifest is shell/plugins/bar/widgets/Indicators.manifest.json, so the shim points at bar/widgets. Indicators.qml loads each icon with Qt.resolvedUrl("../indicators/" + id + ".qml") (line 494 on quattro). Loaded from rev.X/<hash>/Indicators.qml, that resolves to rev.X/indicators/…, which does not exist. Qt resolves .. in the URL, not on disk. The fix depends on this: if Qt resolved the symlink, the URL would never change and nothing would recompile. Any plugin file that reaches above its own manifest directory is affected the same way.
  • Startup can delete the shims it is about to load from. ensureUserDir() now runs rm -rf on the load root in its own process. shell.qml (line 164 on quattro) starts the first rescan() straight away, alongside it, without waiting. If the cleanup lands after the scan has made its rev.* directory, the manifests point at deleted paths. The follow-up scan that quattro chains after cleanup is skipped while scanning is still true. Greptile and @jandrusk raised this too. It is still present on current quattro.

The new fixture checks only parse invented scan lines. Nothing edits a loaded plugin and checks that the new code runs, so neither problem above would show up in them.

Competing fixes: this is the sixth open pull request for this bug. #11408 is the one recommended to the maintainer so far. It reloads the engine on a local .qml, .js or qmldir change, defers while locked, and covers sibling imports. It is waiting on its author for one finding: a source edit tears down an open polkit prompt. #10576 and #13911 version only the entry-point URL, so sibling imports stay cached. #7771 and #8766 no longer merge. The oldest fix wins unless a newer one is clearly better, and this one breaks the indicators, so it doesn't displace the older ones. If this approach is the one wanted, it needs the shim to keep the plugin's surrounding layout (or link from the plugin's root rather than the manifest's directory), the first scan ordered after the cleanup, and a runtime test that edits a sibling import.

Codex Medium reviewed this separately. It found the same two defects, and it checked the indicator URL against the installed Qt runtime. It also confirmed with a probe that changing the directory alias, unlike a query string, does make an edited relative import recompile. It agreed this one should not be brought forward. On which competitor should be, it leaned to #10576 as the oldest, rather than #11408. It can read this session's notes, so its agreement is not guaranteed independent.

Waiting on the maintainer to choose among the competing fixes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bar-widget plugins are not re-instantiated on hot reload: the widget silently vanishes from the bar until the shell is restarted

3 participants