sirula: a small Wayland app launcher with a CSS file

What it is, and what it is not

Sirula, which stands for simple rust launcher, is an application launcher for Wayland. The readme states the scope in one sentence: currently, the only feature is launching applications from desktop entry files.

That is a much narrower scope than most launchers have, and the readme is clear that the narrowness is a starting point rather than a limitation. It invites pull requests for any feature anybody would like, which is a different statement from a claim of completeness.

The author's motivation is stated with unusual candour. It was written partially to learn Rust, so perfect Rust code should not be expected, and criticism of the code is welcome. That framing matters for a project you might depend on, because it tells you what the project is for. It is a small piece of software that a person wanted to exist, published so that other people can use it and improve it. It is not a product with a support commitment, and the licence reflects that: the GNU General Public Licence, version three, which is the licence you would expect a personal project that wants to be incorporated into other people's distributions to use.

The release history is short and says something about the pace. There is a first release in 2021 and a second in December of 2024, and the last push to the repository is in the autumn of 2026. So this is a project with a long gap between releases, which is consistent with a tool that is finished enough and small enough that it does not need to change, and with a maintainer for whom it is one project among several.

The dependency list confirms the shape of the thing, and it is the most informative part of the repository. The launcher is built on the layer shell library, which is the mechanism by which a Wayland compositor is asked to place a window in a particular layer, above or below ordinary windows, and to let it receive keyboard input without taking focus away from whatever you were doing. That single choice is what makes a launcher possible on Wayland at all, and it is also what ties the tool to compositors that implement the protocol.

Everything else in the list is a supporting part: the toolkit itself with its application, input and graphics libraries, the drawing library, the core object and type system, and a handful of small utility crates. The application layer is what you would expect of a launcher and nothing more: a fuzzy matching library, a parser for the desktop entry format, the configuration format, a TOML parser, a regular expression library, a shell-like word splitting library for launch commands, a crate for finding an executable on the path, and a logger.

The configuration, and why it is a stylesheet

Configuration is two files in a directory: a TOML file and a CSS file, both in the configuration directory for the application, and the readme points at a sample configuration directory for the documentation.

The CSS is the part worth thinking about, because it is unusual for a Rust application built on a toolkit to be styled that way. The sample configurations are named, and one of them is described as an overlay in the centre of the screen with some simple CSS animations. So the sample demonstrates not just a different layout but motion.

The reason this works is the toolkit. The graphical libraries in the dependency list are the ones whose interface is described in terms of style sheets, and they apply a style sheet to a widget tree in the same way a browser applies one to a document. A launcher is a small set of widgets, so a style sheet can set the background, the colours, the padding, the border radius, and the font, and the result is a launcher that looks like the rest of the user's desktop rather than like a default program.

And the animations come for free with it, because the same style sheet engine that handles the layout handles transitions, and a launcher that fades in is a launcher whose appearance you did not have to write code for.

The TOML file is the other half, and the readme's decision to point at the sample directory rather than to document the format in the readme is worth noting. It means the format is documented by example, which is a reasonable choice for a configuration with a handful of keys and an unusual amount of look-and-feel in it, and a less good one for a format with many options. For a user, the practical effect is that you copy a sample, change what you want to change, and read the sample when you want to know what a key does.

The two files together also mean the launcher is restyleable without recompiling, and the sample configurations make it easy to see how far that goes. For a tool whose entire job is to appear and disappear, the appearance is most of the product, and making it a document rather than a set of constants is the right call.

The daemon, and the four ways to reload

The daemon mode is marked in the readme as available in the latest git version only, and it changes the launcher's behaviour in a way that matters on a compositor.

Running the program with the daemon flag starts a daemon. To show the window, you run the program again, or use a toggle flag to toggle the window. So the first invocation leaves something running, and subsequent invocations are cheap, because the process is already there and all that is needed is a signal.

That is the classic reason a launcher has a daemon mode. On a compositor, the cost of starting a process, initialising the toolkit, connecting to the display server and drawing the first frame is the whole latency of pressing your shortcut. A daemon that is already connected pays none of that, and the window appears as soon as the compositor honours the request.

Alongside the daemon there are reload commands, and there are four ways to invoke them. There is a reload flag, a reload or restart flag, and two keyboard shortcuts inside the running program, one for reload and one for the other.

And the readme says exactly what gets reloaded: all the desktop, configuration and styling files. That is the important part. A launcher caches the list of installed applications, and if you install a new application while the launcher is running, the cached list is stale until something refreshes it. Reloading the desktop files is how the launcher notices, and reloading the configuration and the stylesheet is how you apply a change to how it looks without restarting the process.

The split between the two reload flags is the interesting detail. A reload that replaces the window is cheap and loses nothing, but it cannot re-read the configuration if the configuration affects how the process itself was set up. A reload that restarts the process can do anything, at the cost of the startup latency that the daemon existed to avoid. Having both means you can choose: reload the style sheet for a change you made to your theme, restart for a change you made to the behaviour.

The readme also points at the help output for the remaining options, which is the right way to handle a tool that has a handful of flags and a growing set of them.

Desktop environment integration

The readme gives one worked example of integrating the launcher with a desktop environment, and it uses a tiling compositor, which is the case where a launcher's behaviour matters most.

exec_always sirula --reload-or-restart
bindsym --no-repeat --release Super_L exec sirula --toggle

Two lines, and they do two different things.

The first runs the reload or restart command every time the configuration is reloaded, with the always modifier that means it runs at start-up as well. That is the line that keeps the launcher in step with the rest of the configuration: change your keybindings, and the launcher is restarted at the same time, so that a launcher configured for the old bindings does not linger.

The second binds a key to the toggle command. The flags on the binding are the interesting part. The no-repeat modifier means the key does not fire repeatedly while it is held down, which for a launcher means a held key does not open and close the window several times. The release modifier means the command runs when the key is released rather than when it is pressed, which avoids the window appearing under your finger before you have finished the gesture. And the toggle command rather than a show command means the same key both opens and closes the window, which is the behaviour a keyboard user expects from a launcher.

That example is worth studying as a template rather than as documentation, because it shows what a good integration looks like. The launcher starts with the session, it reloads when the configuration changes, the key is bound to a modifier rather than to a bare letter so it does not clash, and the same key does both directions.

For a compositor that is not a tiling one, the equivalent is a keybinding in the desktop environment's own settings, and the same reasoning applies about the modifiers and about using a toggle. The only compositor-specific requirement is the one the dependency list implies: the window is placed with the layer shell protocol, so a compositor that does not implement it cannot place the launcher's window the way the application expects.

Building it, and the small details in the manifest

Building is a dependency and two commands. The dependency is the layer shell library, and the build is a release build of the Rust toolchain, with a note that the binary can be stripped afterwards to reduce its size. Alternatively it can be installed directly from the checkout, and there is an unofficial package in the Arch user repository for people who want their system to manage the upgrade.

That is the whole installation story, and it is short because the project is small. There is a build script in the repository alongside the manifest, which in a Rust project of this kind usually means something about linking or code generation that the toolchain cannot do on its own.

The manifest is worth a closer look than a manifest of a project this size usually deserves, because the dependency list reads as a description of the design.

The toolkit is the obvious part, and the version features on it are the interesting detail: a feature flag naming a specific minimum release of the toolkit's own version, and another naming a minimum version of the application library. Those flags are how a Rust project declares that it needs a recent enough version of the underlying libraries, which matters on a desktop where the distribution may ship an older one.

The desktop entry library is the one that makes the launcher's one feature possible, and the crate for the directory specification is what tells it where to look. The fuzzy matching library is what makes typing a few letters narrow the list. The regular expression and shell-like splitting libraries are for parsing the launch command out of a desktop entry and for running it, since a desktop entry's command line is not simply a program name and its arguments. The crate that finds an executable is for the case where the entry names a program that is not on the path.

And then there are two small ones that say something about the project's care. One is a locale library, which suggests the launcher sorts or searches in a way that respects the user's language settings. The other is a universally unique identifier library with the time-ordered variant enabled, which is the kind of thing you use when a launcher's window or its entries need identifiers that do not collide and that sort by creation time.

The release profile enables link time optimisation, which is the standard choice for a small binary you install once, and it is consistent with the note in the readme about stripping the result. A launcher that starts in a few milliseconds is the whole point of the daemon mode, and the size of the binary is a small part of the same budget.

Editorial conclusion

Sirula fits a person on a Wayland compositor who wants a launcher that starts instantly, looks the way they want it to look, and does not fight them for the keyboard shortcut, and it fits somebody who wants to read a hundred lines of Rust and understand how a layer shell overlay is put together. It does not fit a user who wants a launcher with search plugins, recent files or a calculator. Verify first that your compositor implements the layer shell protocol, since the whole overlay model depends on it, that the applications you want to launch have desktop entry files installed, which excludes a fair number of command line tools, and that you understand the configuration format by reading the sample configuration directory, because the readme deliberately does not document it in full.

Frequently asked questions

Official sources

1. DorianRudolph/sirula on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases