Exo
A Material 3 inspired desktop shell for Niri and Hyprland created with Ignis.
Star 0
Fork 0
Watch
Exo MODULES.md
5.6 kB · 131 lines
Markdown
at main

Exo Modules #

Structure #

Exo features live in ignis/modules/<name>/. Each module must have a module.py manifest exporting MODULE.

  • ignis/core/ contains the registry, module types and shared code.
  • ignis/modules/ contains Exo Modules.
  • m3components and shared_modules are shared code, not Exo Modules.
  • ignis/config.py loads the registry and attaches it to app.registry.

Import core.*, not ignis.core.*. The latter is not the Exo core package.

Manifest #

A module directory must match its ID ([a-z][a-z0-9_]*). Directories without a manifest are ignored.

from core.module import Module

def setup(ctx):
    from .impl import create_service
    ctx.provide("my_service", create_service())

MODULE = Module(
    id="my_module",
    requires=(),
    provides=("my_service",),
    needs=(),
    settings=None,
    setup=setup,
    settings_tabs=(),
    bar_widgets=(),
    styles=None,
    nix_options=None,
    enabled_by_default=True,
)

Module fields:

  • requires: other module IDs
  • provides: services provided by this module
  • needs: required services
  • settings: optional JSON file path
  • setup: module setup function receiving a Context
  • settings_tabs: SettingsTab definitions
  • bar_widgets: BarWidget definitions
  • styles: optional styles
  • nix_options: optional Nix options
  • enabled_by_default: defaults to True

SettingsTab(id, title, icon, order, group, factory) defines a settings tab. Its factory is called when needed. Groups are ordered as Shell, Connections, System. Unknown groups are sorted alphabetically after them.

BarWidget(id, factory, default_location, default_bar_id, default_visible, name, description) defines a bar widget. Bar widgets must stay inside bar for now.

Keep manifests import-light. Do not import gi, ignis, user_settings or anything that imports them at the top level. Use lazy imports inside setup() and factories instead. This also applies to disabled modules because all manifests are read before startup. tests/test_manifest_imports.py checks this.

Registry #

core.registry scans modules/*/module.py and loads MODULE.

Module enablement follows this priority:

  1. EXO_MODULE_<ID> environment variable (1, true, yes, on, 0, false, no, off).
  2. modules.json, generated by Nix from exo.modules.<id>.enable.
  3. enabled_by_default in the manifest.

Invalid environment values produce a warning. Module states are decided at startup.

requires uses module IDs. provides and needs use service names. Missing dependencies or required services cause the affected module to be skipped. Modules are loaded in dependency order, with alphabetical order used for ties.

The registry catches discovery and setup errors, logs the module ID and traceback, and skips the affected module. Modules depending on a failed module are skipped too. Failed setup side effects are not rolled back.

Context and services #

Every setup() receives a Context. Modules should communicate through services and signals instead of importing each other directly.

ctx.provide("name", service)  # Register a service
ctx.get("name")               # Optional dependency, returns None if missing
ctx.require("name")           # Required dependency, raises if missing

core must not depend on specific Exo Modules.

Settings and UI #

Settings are stored in shared JSON files:

  • ignis/core/settings.json
  • ignis/modules/<id>/settings.json

Python uses them to build ExoGroup and OptionsManager. Nix reads the same files with builtins.fromJSON and readDir. No IFD is needed.

Settings tabs and bar widgets are declared in the module manifest. The settings UI combines tabs using modules/settings/tab_layout.py.

Keep the existing settings JSON structure, exo.settings.* paths and public Nix options unchanged.

Bar widgets stay inside bar. The interface.modules.* namespace and "Bar Modules" label are kept for compatibility. Use "bar widget" in new code and documentation. BarWidget is not an Exo Module.

If two settings tabs have the same ID, the later one wins and a warning is logged.

Styles #

Modules can provide styles through Module.styles. They are merged at runtime into a writable overlay at:

state_path("exo", "styles-overlay", "ignis")

Styles are loaded in this order:

bar, dock, corners, settings, network, bluetooth, sidebar, launcher, powermenu, quickcenter, notifications, osd, m3, previews

Unknown styles produce a warning and are placed last. No manual @use statements are needed.

Nix #

Use exo.modules.<id>.enable to enable or disable modules. Nix writes the result to modules.json next to the seed file.

Settings are exposed through exo.settings.* and read from the shared JSON files. The old hand-written toJSON in settings.nix is no longer used.

Other Nix options belong in nix/options/*.

Notes #

  • Do not use utils.Poll or blindly resample values. Use GObject/GLib signals and cancellable GLib.timeout* calls.
  • Keep compatibility with existing settings, Nix paths and lock behaviour.
  • Compatibility wrappers in scripts/ may remain during migration.
  • ignis/modules/_template/ contains a minimal manifest template. Copy it into a properly named module directory before using it.

The registry currently includes corners, launcher, notifications, osd, m3test, powermenu, quickcenter, bluetooth, network, settings, bar, wallpaper and recorder. Other services include bar_styles and auto_dark.