Skip to main content

Reload and Debugging

1. The edit-reload loop​

kiln.reload() re-runs your config file without restarting the compositor:

kiln.key {
mods = { "mod", "ctrl" }, key = "r",
desc = "reload config", group = "system",
press = kiln.reload,
}

or trigger it from your editor via IPC:

kiln-client eval 'require("kiln").reload()'

A reload re-executes the config file in the same Lua VM. Modules loaded with require remain cached, including your own modules. See Configs split across modules.

2. What survives, what resets​

StateOn reload
Application windows and running childrenKept.
Client and tag Lua objectsRetired and replaced. Saved references no longer control windows or tag membership.
Screens, layer surfaces, notificationsKept. Screen custom properties and instance listeners are cleared. Layer and notification instance listeners are cleared too.
Bindings, rules, config listeners, bars, declare hooksRemoved; the config must register them again.
Config timers, watches, pipe callbacks, grabs, animations, scroll offsetsCleared. Running child processes are not terminated.
Config popupsClosed and unregistered; construct new ones.
Focus and tag-selection historiesCleared.
Theme, input settings, globals, cached modulesKept unless the config overwrites them.
Replacements for the ten kiln.defaults policiesAll reset except successor, which retains its current function.
kiln.widgets replacementstitlebar resets. Other function replacements remain.

After running the config, Kiln emits added for each screen, refreshes layer surfaces, then replays clients through the new rules. Clients without a matching tag rule go to the focused screen's selected tag. Config-side minimisation and floating geometry are lost. To retain memberships, see Keep client tags across reload.

kiln.reload() schedules this work after the current callback returns. It returns true when accepted, false during initial config loading or while a reload is already pending or running. Code after the call still sees the old configuration.

A config error leaves the session running with the registrations made before the failure. Reload does not restore the previous config. Fix the file and reload again.

Configs split across modules​

Export a setup function from each module. Call it from rc.lua on every load. Registrations in the module body run only on the first require; reload removes them without running that body again.

Save bindings.lua beside rc.lua:

local M = {}

function M.setup(kiln)
kiln.key {
mods = { "mod" }, key = "Return",
press = function() kiln.spawn("foot") end,
}
end

return M

In rc.lua, after setting kiln.modkey:

require("bindings").setup(kiln)

This restores registrations but does not reread edits to bindings.lua. To reread that module, clear its cache entry before requiring it:

package.loaded["bindings"] = nil
require("bindings").setup(kiln)

Dependencies remain cached. Restart Kiln after editing its standard library; clearing individual kiln.* entries can leave references to older modules.

3. Catch errors with the error signal​

Errors in bindings, signal listeners, rules and spawn callbacks emit the global error signal and are printed to stderr. Register a listener near the top of the config to display them:

kiln.on("error", function(signal, err)
kiln.notify {
urgency = "critical",
title = "Config error in " .. tostring(signal),
message = tostring(err),
}
end)

Bar and layout declaration errors are logged as Lua frame: ...; they do not emit this signal. Direct kiln.timer callback errors are logged as Lua timer: .... Always check the log when the error listener reports nothing.

Declaration failures​

A declaration error rejects the screen's entire new frame. The previous scene and its pointer handlers remain active. Lua state writes made before the error are not undone. A duplicate element ID has the same frame-rejection behaviour.

After correcting the cause, reload the config or call kiln.dirty() to request another frame. A failed declaration does not schedule its own retry. kiln.on_declare hook errors also emit error before rejecting the frame. A failed notify_display function emits error and is skipped on later frames until replaced with another function or reset by reload.

4. Logs​

Kiln logs to stdout and stderr. make run does not capture or rotate them. The TTY launcher records both in server.log under the directory listed in build/last-tty-trial. For a nested trial, capture both streams:

kiln_demo=$(mktemp -d /tmp/kiln-demo.XXXXXX)
KILN_SOCK="$kiln_demo/eval.sock" KILN_RC="$PWD/kilnrc.lua" \
dbus-run-session -- ./build/kiln >"$kiln_demo/server.log" 2>&1

tail -f "$kiln_demo/server.log" from another terminal.

5. See what your config actually built​

Toggle the Clay inspector with mod+shift+i; see Inspect the Live Element Tree.

6. Test changes in a nested instance​

Run the nested command above with KILN_RC pointing at the config under test. Address it with kiln-client -s $kiln_demo/eval.sock ...; kiln-client -s PATH exec foot starts a client inside it.

For full HOME/config/cache isolation, use Testing headless. A private bus and socket alone do not isolate side effects of arbitrary config code.

See also​