LUDASH / START

Install. Settle in. Make it yours.

Install LunaDash with the session installer, dismiss the welcome screen and personalize your desktop. Advanced build and validation steps are included below.

Install on Linux

LunaDash is developed primarily on Arch Linux, but the installer also recognizes Debian/Ubuntu, Fedora, openSUSE, Alpine, Void and Gentoo package-manager families. Other distributions can use the same standard CMake install path after providing Qt 6.4+, wlroots 0.17–0.20, Wayland, libinput, libxkbcommon, GL, GLib, Ninja and a C++20 compiler.

TERMINAL

git clone --branch dev https://github.com/LuYishan-4/LunaDash.git
cd LunaDash
./scripts/install-session.sh

Run ./scripts/install-session.sh --dry-run to preview the installation. install-session.sh delegates dependency provisioning to install-dependencies.sh. Arch uses makepkg/pacman; the other recognized distributions build with Ninja and install through CMake. If your package manager is unknown, preinstall the dependencies and use ./scripts/install-session.sh --skip-deps. Quickshell 0.3+ is required for the shell and may need to be installed separately when the distribution does not package it.

On non-systemd systems, install LunaDash normally but enable your display manager with the distribution's own OpenRC/runit procedure instead of --enable-sddm.

Install on NixOS

The flake provides a NixOS module and packages for x86_64-linux and aarch64-linux. Import lunadash.nixosModules.default into your system configuration and enable the desktop:

TERMINAL

programs.lunadash.enable = true;

Rebuild your NixOS configuration, log out and select LunaDash in your existing display manager. The module registers the session and portal services; networking, PipeWire, input methods and the display manager remain host choices. Use NixOS generations for updates and rollback. See the complete NixOS configuration and update guide.

Your first session

The welcome screen contains a greeting and a link to this website for help. Select Start desktop to dismiss it, or open the help link to continue in your browser. It will not appear again automatically after completion. Use Settings for language, network and appearance, or to reopen the welcome screen.

Super+T or Super+Return opens Kitty when it is installed; Super+E opens the default file manager. A default terminal is optional and missing it does not prevent login. Native X11 apps can be launched through the authenticated XWayland path. Save work before testing a standalone session.

Run the checks

TERMINAL

cmake -S . -B build -G Ninja
cmake --build build
env -u MESA_GL_VERSION_OVERRIDE -u MESA_GLSL_VERSION_OVERRIDE \
  QT_QPA_PLATFORM=wayland ./build/lunadash-compositor --nested --socket ludash-test

The repository also contains ./scripts/test-once.sh and Wayland integration tests. Tests use isolated runtime/configuration directories. The current headless wlroots checks exercise protocol/window lifetimes and clean shutdown with pixman. The separate renderer test verifies embedded shaders and software OpenGL. A real session is still needed to inspect application content and hardware behavior.

Distribution coverage

Dev CI selects shared suites from changed files; Main CI runs all suites, including security analysis. Ubuntu builds once for the native and runtime checks. Development changes build Arch; full runs add Debian, Fedora, openSUSE Tumbleweed and Alpine Edge. NixOS CI builds x86_64, evaluates aarch64 and checks the installed headless compositor; check their completed results for the intended commit. Void and Gentoo have maintained automatic dependency/install paths but currently have less CI breadth. Generic Linux support means the standard CMake build/install path is available when the required toolchain exists; it is not a claim that every GPU, display manager or physical seat has been tested.

Understand the preview

Nested software-rendered sessions do not verify all GPUs or standalone login sessions. Multiple outputs, screen locking and some protocol/input integration still vary by environment. Native plugins and custom QML are disabled until explicitly trusted.

See the repository's testing guide and source map for sanitizer commands, platform dependencies, evidence files, packaging checks and the verification record.