Development Environment

Nix Development Shell (Recommended)

The easiest way to get a fully working development environment is with Nix:

nix develop

This provides:

The correct Rust toolchain (stable, latest)
All system library dependencies (Wayland, PipeWire, PulseAudio, etc.)
rust-analyzer for editor integration
Correct LD_LIBRARY_PATH for runtime libraries (Wayland, Vulkan, Mesa, OpenGL)
RUST_SRC_PATH set for rust-analyzer goto-definition

You can then build and run normally:

cargo build --release
./target/release/ashell

Manual Setup

If you don’t use Nix, install the prerequisites for your distribution and ensure Rust 1.89+ is installed.

ashell uses a custom fork of iced (see Architecture Overview). This means rust-analyzer resolves iced types from the git dependency. Go-to-definition works, but it will navigate into ~/.cargo/git/ rather than a local checkout.

If you need to edit or deeply explore the iced fork, clone it locally:

git clone https://github.com/MalpenZibo/iced.git

Then temporarily override the dependency in Cargo.toml using a [patch] section (don’t commit this).

Running ashell

Standard Run

make start
# or
cargo run --release

ashell must be launched within a Wayland session running Hyprland or Niri. It cannot run under X11 or without a compositor.

Custom Config Path

ashell --config-path /path/to/my/config.toml

The default config path is ~/.config/ashell/config.toml.

Logging

ashell uses flexi_logger and writes logs to /tmp/ashell/.

Log files rotate daily and are kept for 7 days.
In debug builds, logs are also printed to stdout.
The log level is controlled by the log_level field in the config file (default: "warn").
The log level follows the env_logger syntax, e.g., "debug", "info", "ashell=debug,iced=warn".

To watch logs in real time:

tail -f /tmp/ashell/*.log

Signal Handling

SIGUSR1: Toggles bar visibility. Useful for keybindings:
```
kill -USR1 $(pidof ashell)
```

ashell Developer Guide