runapp

runapp is an application runner for Linux desktop environments that integrate with systemd.

Its job is simple: it launches the given application in an appropriate systemd user unit, according to systemd's idea of how this should be done.

It is useful if you are using a light-weight Linux desktop environment such as Sway. In such cases, runapp works great as a complement to your favourite application launcher, such as Fuzzel.

runapp owes its inspiration to uwsm, a great way to go all-in on the systemd way of running applications in a Desktop context, and another great complement to runapp. In fact, the uwsm app subcommand has exactly the same purpose as runapp, and has several more features; see below Missing features section for a comparison.

So why runapp? Its main advantage over uwsm app and other alternatives is that it is fast: being a native executable (written in C++) with no dependencies, it has significantly lower startup latency and resource usage.

Usage

If you use Sway with Fuzzel, you might include something like the following in your .config/sway/config file:

bindsym Mod4+d runapp fuzzel --launch-prefix runapp

This will launch Fuzzel via runapp when the Super+D key combination is pressed, and tells Fuzzel to run any application it launches via runapp as well.

Variants of the above will apply for other combinations of desktop compositors and application launchers.

To see what else you can do, try runapp --help:

runapp [OPTIONS] COMMAND...
    Run COMMAND as a systemd user unit, in a way suitable for typical applications.
    Options:

    -v, --verbose: Increase output verbosity.
    -o, --scope:   Run command directly, registering it as a systemd scope;
                   the default is to run it as a systemd service.
    -i SLICE, --slice=SLICE:
                   Assign the systemd unit to the given slice (name must include
                   ".slice" suffix); the default is "app-graphical.slice".
    -d DIR, --dir=DIR:
                   Set working directory of command to DIR.
    -e VAR=VALUE, --env=VAR=VALUE:
                   Run command with given environment variable set;
                   may be given multiple times.

runapp --help
    Show this help text.

Or you can read the man page via man runapp.

Installation

• If using Arch Linux, install runapp from the AUR (Arch User Repository).
• Otherwise, run make install. This requires that you have a recent GCC with C++ compiler and GNU Make. You may be prompted for your sudo password. To uninstall again, run make uninstall.

Features

• Fast: talks directly to systemd, via its private socket if available, the same way that systemd-run does.
• No dependencies beyond systemd.
• Run app either as systemd service (recommended, default) or as systemd scope.
  • The latter means runapp directly executes the application, after registering it with systemd.
• Run app either under app-graphical.slice (recommended for most cases, default) or under any other slice.
• Option to run app in given working directory.
• Option to run app with given environment variables.
• If run from Fuzzel, derive unit name from .desktop name, per systemd recommendations.
• On error, if not run from interactive terminal, show desktop notification.

Missing features

Most of the features on this list are implemented in uwsm app. I don't consider these very important to have, but I'm open to discussions (feel free to open an issue!).

• Support custom unit name / description.
• Unit description: derive from .desktop file.
  • For Fuzzel, would be made much easier (and more performant) with https://codeberg.org/dnkl/fuzzel/issues/292
• Support being given a Desktop File ID (only).
  • With optional Action ID
• Support running .desktop files with args, using field codes.
  • See https://specifications.freedesktop.org/desktop-entry-spec/latest/exec-variables.html
  • Note that %f and %u entail running multiple app instances
  • Alternatively, this could be done by the launcher, e.g. Fuzzel: https://codeberg.org/dnkl/fuzzel/issues/346
• Alternative ways of accepting Desktop File ID (beyond Fuzzel).
• Support running app under Terminal.

Alternatives

• uwsm app: the original; somewhat slow due to being written in Python
• uwsm-app: shell script that ships with uwsm; spawns a background daemon
• app2unit: self-sufficient and feature-complete shell script by the author of uwsm

Development

Prerequisites: Recent GCC with C++ compiler and GNU Make.

• make debug: create debug build.
• make compile_commands.json: generate compile_commands.json file, useful for language servers like clangd; requires bear.
• make release: create release build.
• make clean: delete all build artefacts.