DOCSEARCHbyAlgolia
Submit Docs

Noctalia

repository·main·Indexed 25 days ago

https://github.com/noctalia-dev/noctalia

A native Wayland desktop shell designed for system theming and configuration. It integrates bars, widgets, docks, launchers, and control centers into a single layer built on Wayland and OpenGL ES. Noctalia supports various compositors including Niri, Hyprland, Sway, and others, and features TOML-based configuration with hot reload and built-in Firefox theming capabilities.

Tokens
9.4K
Snippets
22
Records
65
Agent score
93%

What's inside Noctalia

  1. Overview of Noctalia

    main

    Noctalia is a native Wayland desktop shell designed to provide a cohesive, polished, and configurable Linux desktop experience. Unlike setups that rely on a collection of separate tools (bars, launchers, notification daemons, etc.), Noctalia integrates these surfaces into a single layer built on Wayland and OpenGL ES.

    Key Features:

    • Bars & Widgets: Multi-monitor bars with taskbars, workspaces, system tray, media, network, battery, brightness, weather, and clipboard widgets.
    • Desktop Surfaces: Dock, launcher, control center, notification history, wallpaper picker, OSD overlays, lock screen, and session panel.
    • Configuration: TOML-based configuration with hot reload, GUI-managed overrides, and IPC for runtime control.
    • Wayland Integration: Direct support for layer-shell, session lock, idle behavior, clipboard, and fractional scaling.

    Note: Noctalia v5 is currently in Beta and may undergo configuration or behavior adjustments.

  2. Use Luau command-line tools

    main

    Luau provides two primary command-line tools:

    • luau: A command-line REPL and runner for input files. Note that the REPL runs in a sandboxed environment and cannot access the file system except for require-ing modules.
    • luau-analyze: A command-line type checker and linter. It produces errors and warnings based on file configuration, which can be customized via --! comments or .luaurc files.

  3. Build Noctalia using Meson

    main

    Noctalia uses the Meson build system and Ninja. For distribution packages, it is recommended to use the following configuration:

    1. Setup: meson setup build --buildtype=release
    2. jemalloc: Recommended on glibc systems. Use the Meson feature option -Djemalloc=auto|enabled|disabled. On musl systems, use -Djemalloc=disabled or auto.
    3. Optimizations: Do not enable -Dnative_optimizations=true for distro packages as it uses CPU-local codegen which is not portable.
    4. Tests: Use -Dtests=disabled or leave as auto for release builds.

    Important: The assets/ tree (found in <prefix>/share/noctalia/assets/) is required at runtime. Shipping only the binary will break fonts, translations, templates, glyphs, and sounds.

    meson setup build --buildtype=release

  4. Build and install a release version of Noctalia

    main

    To create an optimized release build, use the just command with the release mode. Release builds are portable by default.

    To enable native CPU optimizations for a machine-local build, configure Meson with -Dnative_optimizations=true after the initial configuration.

    To install to a custom location instead of /usr/local, pass a prefix to the configure command.

    # Optimized release build in build-release/
just configure release
just build release

# Install the selected build mode
sudo just install release

# Enable native CPU optimizations for machine-local builds
meson configure build-release -Dnative_optimizations=true
just build release

# Install to a custom prefix (e.g., $HOME/.local)
just configure release "$HOME/.local"
just build release
just install release

  5. Package Noctalia for distribution

    main

    When packaging Noctalia, use the following metadata and identity details:

    • Short Description: A sleek, customizable desktop shell crafted for Wayland. (Do not use shorter alternatives like "status bar").
    • Name: noctalia
    • Binary: noctalia
    • Desktop Entry: dev.noctalia.Noctalia.desktop
    • Icon: noctalia (located at share/icons/hicolor/scalable/apps/noctalia.svg)
    • License: MIT

    Note on Versioning: The version is defined in the Meson project(...) call within meson.build. It is recommended to package tagged releases rather than main snapshots.

  6. Install Dependencies on Void Linux

    main

    To build Noctalia on Void Linux, install the following dependencies using xbps-install:

    sudo xbps-install meson ninja pkg-config git \
  wayland-devel wayland-protocols libepoxy-devel \
  MesaLib-devel libglvnd-devel cairo-devel \
  pango-devel fontconfig-devel freetype-devel \
  harfbuzz-devel libxkbcommon-devel pipewire-devel wireplumber-devel \
  libsecret-devel libsodium-devel \
  libcurl-devel pam-devel libwebp-devel libjxl-devel \
  basu-devel sdbus-c++-devel \
  libmd4c-devel tomlplusplus-devel \
  json-c++ stb \
  polkit-devel librsvg-devel libqalculate-devel libxml2-devel jemalloc-devel

  7. Build Requirements and Compiler Setup

    main

    Noctalia is built using C++23, which requires GCC 13+ or Clang 16+.

    Special Note for Debian 12 (Bookworm): Debian 12 ships with an older compiler by default. To build Noctalia, you must install g++-13 and point Meson to it using the CXX environment variable:

    CXX=g++-13 just configure

  8. Build Luau from source using CMake

    main

    To build Luau binaries from source on any platform, use CMake with the following commands:

    mkdir cmake && cd cmake
cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build . --target Luau.Repl.CLI --config RelWithDebInfo
cmake --build . --target Luau.Analyze.CLI --config RelWithDebInfo

  9. Install Dependencies on Fedora

    main

    To build Noctalia on Fedora, install the following dependencies using dnf:

    sudo dnf install meson gcc-c++ just \
  wayland-devel wayland-protocols-devel \
  libEGL-devel mesa-libGLES-devel \
  freetype-devel fontconfig-devel \
  cairo-devel pango-devel harfbuzz-devel \
  libxkbcommon-devel glib2-devel \
  libsecret-devel libsodium-devel \
  sdbus-cpp-devel pipewire-devel wireplumber-devel \
  pam-devel polkit-devel libcurl-devel libwebp-devel libjxl-devel librsvg2-devel \
  libqalculate-devel libxml2-devel \
  md4c-devel tomlplusplus-devel \
  json-devel stb_image_resize2-devel stb_image_write-devel \
  jemalloc-devel

  11. Run Noctalia unit tests

    main

    Unit tests are not included in the standard just build command. To run tests, use just test.

    If you are working with a release build, you must explicitly specify the mode to run tests: just test release.

    Direct Meson users can control test target generation using the -Dtests=enabled|disabled|auto option.

  12. Install Dependencies on Debian / Ubuntu

    main

    To build Noctalia on Debian or Ubuntu, install the following dependencies using apt:

    sudo apt install meson g++ just \
  libwayland-dev wayland-protocols \
  libegl-dev libgles-dev \
  libfreetype-dev libfontconfig-dev \
  libcairo2-dev libpango1.0-dev libharfbuzz-dev \
  libxkbcommon-dev libglib2.0-dev \
  libsecret-1-dev libsodium-dev \
  libsdbus-c++-dev libpipewire-0.3-dev libwireplumber-0.5-dev \
  libpam0g-dev libpolkit-agent-1-dev libpolkit-gobject-1-dev \
  libcurl4-openssl-dev libwebp-dev libjxl-dev librsvg2-dev \
  libqalculate-dev libxml2-dev \
  libmd4c-dev libtomlplusplus-dev \
  nlohmann-json3-dev libstb-dev \
  libjemalloc-dev