Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

Note: The content of this developer guide has been entirely generated by AI, based on analysis of the ashell source code, GitHub issues, pull requests, and project discussions. It may contain inaccuracies or become outdated as the project evolves. Contributions to improve and maintain this documentation are welcome.

ashell is a ready-to-go Wayland status bar for Hyprland and Niri window managers. It is written in Rust using the iced GUI framework and provides a modern, feature-rich taskbar experience for Wayland-based Linux desktops.

Who This Book Is For

This developer guide is written for:

  • New contributors who want to understand the codebase and start contributing.
  • Existing developers who need a reference for architecture decisions, patterns, and subsystems.
  • Anyone interested in learning how a real-world iced + Wayland application is built.

This is not a user guide. For end-user documentation (installation, configuration, usage), visit the ashell website.

How to Navigate This Book

If you’re new to the project, read the sections in order:

  1. Getting Started — Set up your development environment and build the project.
  2. Architecture — Understand the high-level design, the Elm architecture, and data flow.
  3. Core Systems — Learn about the App struct, configuration, theming, and output management.
  4. Modules and Services — Understand how UI modules and backend services are structured.

If you’re an existing developer looking for a reference:

  • Jump directly to the specific chapter you need (e.g., Writing a New Module or D-Bus Services Pattern).
  • Use the search feature (top of the page) to find specific topics.
  • Check the Reference section for configuration details, environment variables, and D-Bus interfaces.

Project Identity

ashell is designed around two core principles:

  • “Ready to go” — It works out of the box with sensible defaults and minimal configuration.
  • “Everything built in” — All features are integrated directly rather than relying on external scripts or tools.

The project uses a full Rust stack intentionally, prioritizing consistency, type safety, and a unified development experience.