Skip to main content

The Native/Lua Boundary

Odin occupies the native side of the policy boundary: the Wayland protocols, the backends, input devices, client buffers and the renderer are Odin. Clay, Mesa, libinput, xkbcommon, cairo, pango and LuaJIT remain C dependencies.

Native core​

The Odin core handles the Wayland protocols, outputs and input devices, client buffers, scene rendering, and PAM authentication. It exposes operations such as focusing a surface and configuring an output.

Lua configuration​

Lua defines focus behaviour, tags, layouts, rules, keybindings, menus, and notifications. It handles fullscreen and activation requests and declares the UI.

Events and function calls​

Odin sends events as tables to a single handler in the standard library, which emits object signals. For example, a native map event creates a client object and emits its map signal. See the events reference.

Lua calls native functions to focus clients, configure surfaces, and set output modes.

Defaults are policy you can replace​

kiln.defaults defines the default request handlers. Assign a new function to any kiln.defaults field to replace that policy:

kiln.defaults.fullscreen = function(c, on)
-- the stock handler does `c.fullscreen = on`
end

To remove a request handler without a replacement, take the stock function off the bus; the request is then ignored:

client.off("request::fullscreen", kiln.defaults.fullscreen)

See defaults and Replacing default policies.

Direct core access​

The core global exposes the native API used by the standard library. It bypasses the object model, signals, and policies. Use objects and kiln.* for configuration; use core when extending the library, such as for output configuration.

Why the line is drawn here​

Policy lives in Lua so kiln.reload() can replace it without restarting, and so your config and the default desktop use the same API.

See also​