lemurs

Lemurs populates its environment switcher based on runnable scripts located in specific directories. The filename of the script determines the name displayed in the Lemurs UI.

• Xorg/X11: Place your xinitrc scripts in /etc/lemurs/wms/.
• Wayland: Place scripts that start your compositor in /etc/lemurs/wayland/.

Important: You must make these scripts executable using chmod.

Xorg Example (bspwm)

Create /etc/lemurs/wms/bspwm:

#! /bin/sh
sxhkd &
exec bspwm

Then run: sudo chmod 755 /etc/lemurs/wms/bspwm

Wayland Example (Sway)

Create /etc/lemurs/wayland/sway:

#! /bin/sh
exec sway

Then run: sudo chmod 755 /etc/lemurs/wayland/sway (Ensure you are in the seat group).

To compile and set up Lemurs on a Unix machine, use the provided install.sh script. This script automates the following:

1. Building the project in release mode using cargo.
2. Setting up the /etc/lemurs directory for configuration and window manager files.
3. Disabling the existing Display Manager.
4. Copying and enabling the systemd service.

Note: You should set up your window manager scripts (see Usage) before rebooting to ensure they appear in the Lemurs environment switcher.

Lemurs can be installed directly from the Arch Linux extra repository. If you already have a display manager running, you should disable it before enabling Lemurs to avoid conflicts.

sudo pacman -S lemurs

# Disable your current display manager if one is active
sudo systemctl disable display-manager.service

# Enable the Lemurs service
sudo systemctl enable lemurs.service

Alternatively, lemurs-git is available in the AUR.

sudo pacman -S lemurs

# Not needed if you don't have a window manager yet
sudo systemctl disable display-manager.service

sudo systemctl enable lemurs.service

Lemurs supports variable substitution within configuration files. Variables are defined in a separate variables.toml file and can be referenced in the main configuration using the $ prefix.

Syntax

Use $variable_name to inject the value of a variable. Variables can be nested (up to a depth of 10) and can be used within strings.

Example

If variables.toml contains:

my_path = "/home/user/logs"

You can use it in config.toml like this:

main_log_path = "$my_path/lemurs.log"

The PostLoginEnvironment enum defines the types of sessions supported. You can use to_xdg_type() to get the corresponding XDG session type string.

The InputFieldDisplayType enum determines how characters typed into an InputFieldWidget are rendered to the user.

• Echo: The standard mode where characters typed are displayed as they are entered.
• Replace(String): A mode where the input field always displays a static string (the provided String) repeatedly to fill the available width, rather than showing the actual typed content.

pub enum InputFieldDisplayType {
    /// Show the characters that were typed
    Echo,
    /// Always statically show a selected character
    Replace(String),
}

When implementing a login flow that involves forking, ValidatedCredentials holds the necessary PAM handle and user account metadata.

Workflow:

1. Call try_validate to get a ValidatedCredentials instance.
2. fork() the process.
3. In the Child: Call open_session (exported from crate::auth::pam) using the credentials, then exec the compositor.
4. In the Parent: Call std::mem::forget on the credentials to ensure the PAM handle is not double-freed when the parent process cleans up.

Log Files

Lemurs writes logs to the following locations:

• /var/log/lemurs.log: Main control flow log (primary debugging source).
• /var/log/lemurs.client.log: stdout and stderr of your environment scripts (useful for debugging /etc/lemurs/wms or /etc/lemurs/wayland scripts).
• /var/log/lemurs.xorg.log: stdout and stderr of the X server (X11 only).

To disable logging globally, add the --no-log flag to your service manager script.

CLI Commands

• lemurs --show-config: Prints all current settings (including defaults) in TOML format to verify parsing.
• lemurs --preview: Runs a preview instance of your configuration to test the UI. This creates a lemurs.log in the current working directory.

The shell_login_flag setting determines the type of login flag used for the shell. Supported values are:

• none: No login flag is used.
• short: Uses the short flag version.
• long: Uses the long flag version.

The focus_behaviour setting determines which field receives focus when the application starts. Supported values are:

• default (maps to FirstNonCached): Focuses the first non-cached item.
• no-focus: No field is focused initially.
• environment: Focuses the environment switcher.
• username: Focuses the username field.
• password: Focuses the password field.