libplasmoid-updater 0.2.0

Library for updating KDE Plasma 6 components from the KDE Store. Meant for use in topgrade.
Documentation

libplasmoid-updater

A Rust library for managing KDE Plasma 6 components from the KDE Store.

[!IMPORTANT] The core logic (a combination of Apdatifier and KDE Discover) was ported to Rust with AI assistance (Claude Code and GH Copilot). The code was audited and tested by me. Feel free to contribute with an issue or PR.

Requirements

Runtime dependencies:

  • bsdtar – Archive extraction
  • kpackagetool6 – KDE package installation

Features

  • Component Discovery – Detects installed Plasmoids and other Plasma components
  • Multithreaded update checking and installation via Rayon
  • Automatic Backups with rollback on failure
  • Registry Integration – Maintains KNewStuff registry compatibility
  • Sleep Inhibition – Prevents system sleep during installs (logind DBus or systemd-inhibit)
  • Plasma 6 Support – Compatible with Plasma 6.0 and later

Supported Components

Plasma Widgets, Wallpaper Plugins, KWin Effects/Scripts/Switchers, Global Themes, Plasma Styles, Color Schemes, Splash Screens, SDDM Themes, Icon Themes, Wallpapers, and Aurorae Decorations.

API

Functions

function description
check(&Config) -> Result<CheckResult> scan for available updates to installed KDE components
update(&Config) -> Result<UpdateResult> apply available updates (interactive or automatic)
show_installed(&Config) -> Result<()> print a table of all installed KDE components (cli)
get_installed(&Config) -> Result<Vec<InstalledComponent>> return all installed KDE components; no network calls
install_update(&AvailableUpdate, &Config) -> Result<()> install a single component update with backup/rollback

Config

Built with a builder pattern via Config::new():

method description
with_system(bool) scan system-wide components in /usr/share (requires root)
with_excluded_packages(Vec<String>) skip these packages (by dir name or display name)
with_widgets_id_table(HashMap<String, u64>) override fallback dir-to-content-ID mapping
with_restart(RestartBehavior) plasmashell restart behavior after updates
with_auto_confirm(bool) skip interactive prompts, apply all updates (cli)
with_threads(usize) max parallel install threads (default: logical CPU count)
with_skip_plasma_detection(bool) skip KDE environment check (for CI/testing)
with_inhibit_idle(bool) inhibit system sleep during installs (default: true)
Config::parse_widgets_id(&str) parse a widgets-id file into the fallback table format

Types

RestartBehavior : Never (default) | Always | Prompt

CheckResult returned by check():

  • available_updates: Vec<AvailableUpdate>
  • diagnostics: Vec<Diagnostic>
  • has_updates() -> bool, update_count() -> usize, is_empty() -> bool

Diagnostic : a component that could not be checked:

  • fields: name, reason, installed_version: Option<String>, available_version: Option<String>, content_id: Option<u64>

ComponentType : enum of all supported KDE component kinds:

  • variants: PlasmaWidget, WallpaperPlugin, KWinEffect, KWinScript, KWinSwitcher, GlobalTheme, PlasmaStyle, AuroraeDecoration, ColorScheme, SplashScreen, SddmTheme, IconTheme, Wallpaper
  • user_path() -> PathBuf, system_path() -> PathBuf, all() -> &[ComponentType], all_user() -> &[ComponentType]

InstalledComponent : a KDE component on the local system:

  • fields: name, directory_name, version, component_type: ComponentType, path: PathBuf, is_system: bool, release_date

AvailableUpdate : an update with download metadata:

  • fields: installed: InstalledComponent, content_id: u64, latest_version, download_url, store_url, release_date, checksum: Option<String>, download_size: Option<u64>

FailedUpdate : a component that failed to update:

  • fields: name, error

UnverifiedUpdate : installed but post-install version could not be confirmed:

  • fields: name, expected_version, actual_version: Option<String>

UpdateResult returned by update():

  • succeeded: Vec<String>, failed: Vec<FailedUpdate>, skipped: Vec<String>, unverified: Vec<UnverifiedUpdate>
  • has_failures() -> bool, is_empty() -> bool, success_count() -> usize, failure_count() -> usize
  • print_summary(), print_error_table() (requires cli)

Error : library error type with variants for OS, network, XML, IO, install, checksum, and more. Result<T> aliases Result<T, Error>.

Cargo Features

Default features: cli, inhibit.

feature description
cli Terminal output (spinner, tables, interactive selection), show_installed(), UpdateResult::print_summary(), and UpdateResult::print_error_table(). Pulls in indicatif, comfy-table, bytesize, inquire, is-terminal, terminal_size.
inhibit Inhibit system sleep/shutdown via logind DBus during installs. Pulls in zbus. Without this feature the library falls back to spawning systemd-inhibit as a subprocess.
debug Print request count after update().

To use the library without terminal dependencies:

[dependencies]
libplasmoid-updater = { version = "0.1", default-features = false }

CLI Tool

For a reference CLI implementation, see plasmoid-updater.

License

Licensed under GPL-3.0-or-later.