How pop-os/libcosmic works
Project type and purpose
• This repository is a Rust-based UI toolkit (“libcosmic”) built on top of the iced framework.
• It provides:
• A core library (src/) exposing widgets, theming, configuration, and app scaffolding.
• Two helper crates: cosmic-config-derive (a procedural-macro crate for code generation) and cosmic-config (runtime settings management via D-Bus/calloop).
• Example applications showing how consumers use libcosmic.
File structure
• Top-level crates:
• cosmic-config-derive/ (proc-macro)
• cosmic-config/ (runtime settings daemon & subscription)
• cosmic-theme/ (theme model, derivation, output)
• Root crate (src/): the core libcosmic library (widgets, app, executor, surfaces)
• examples/ demonstrating usage
• Key modules inside the core crate (src/):
• app/: scaffolding for cosmic applets/apps
• applet/: token-based Applet API (Wayland/X11 support)
• config/: core hooks into cosmic-config crate
• executor/: single/multi-threaded runtimes (smol/tokio vs iced default)
• widget/: hundreds of custom widgets (buttons, menus, dialogs, etc.)
• theme/: runtime styling (portal dialogs, style sheets)
• Integration points: D-Bus activation, file-chooser portal, calloop event loop, Wayland vs winit, GPU rendering (wgpu vs softbuffer).
README for additional insights
• The library is used to build COSMIC desktop components (applets, panels, launchers, etc.).
• It is organized as multiple Cargo workspaces/crates.
• Feature flags drive async runtime, windowing backend, GPU or software rendering, and XDG portal integration.
• cosmic-config-derive (Proc-Macro)
• cosmic-config (Settings Daemon + D-Bus Subscription)
• cosmic-theme (Theme Model + Derivation + Output modules)
• libcosmic core:
– App & Applet APIs
– Executor (iced runtime or smol/tokio)
– Widget Library
– Theme Engine (consumes cosmic-theme outputs)
– Config Bridge (consumes cosmic-config)
– Dialog & Portal integration
• External Dependencies: iced (GUI framework), calloop (event loop), D-Bus, Wayland/Winit, XDG Portal, wgpu/softbuffer.
• Consumers: Example applications or downstream COSMIC desktop components.
• Proc-Macro (cosmic-config-derive) → codegen into libcosmic consumer code
• libcosmic ↔ cosmic-config via D-Bus subscription to system settings
• libcosmic → iced for widget rendering
• iced → calloop (or chosen executor) → OS event loop
• libcosmic → file-chooser portal → XDG portal or native dialogs
• libcosmic → Wayland or winit for surface creation
• libcosmic → wgpu or softbuffer for rendering
• Application code → libcosmic APIs → drives UI
c. Architectural patterns & principles
• Modular crate separation (proc-macro, runtime config, theming, core UI)
• Inversion of control: consumers supply callbacks, libcosmic owns the event loop
• Feature-flag–driven backends (async runtime, windowing, rendering)
• Pub-sub pattern for settings (using D-Bus subscription)
• Theming pipeline: model → derivation → multi-format output
d. Key technologies
• Rust & Cargo Workspaces
• iced GUI framework
• calloop / async executors (smol, tokio)
• D-Bus (system settings daemon)
• Wayland / winit (windowing)
• wgpu or softbuffer (rendering)
• XDG portals (file dialogs)
• Procedural macros for code generation