Skip to content

reference.md

Latest commit

 

History

History
38 lines (31 loc) · 2.02 KB

reference.md

File metadata and controls

38 lines (31 loc) · 2.02 KB
Raw

Reference & Guidelines for Plasma 6 Widget Development

This document contains critical technical context for building the Tailscale Plasma 6 widget safely and effectively.

1. System Safety (CRITICAL)

  • Never install to system root (/usr/) during development. A bad install can break the Plasma desktop environment.
  • Always install locally to the user's home directory (~/.local/).
  • In CMake, set the installation prefix to the local user directory if it's not handled automatically by plasma_install_package.
  • Do not use sudo for any build or install commands.

2. Plasma 6 / KF6 Requirements

Fedora is currently using KDE Plasma 6. This means the widget must be built against Qt 6 and KDE Frameworks 6 (KF6).

CMake Context

The CMakeLists.txt must find the correct KF6 and Qt6 packages:

find_package(Qt6 REQUIRED COMPONENTS Core Gui Qml Quick)
find_package(KF6 REQUIRED COMPONENTS Plasma I18n CoreAddons Kirigami)

To install the QML package, use the KF6 macro:

plasma_install_package(package org.kde.tailscale_widget)

QML Imports for Plasma 6

Be aware that imports have changed from Plasma 5.

  • Use import org.kde.plasma.plasmoid instead of the old PlasmaCore.
  • Use import org.kde.kirigami as Kirigami for standard UI components.
  • Use import org.kde.kcm for the configuration pages (configGeneral.qml).

3. Testing the Widget safely

Instead of installing the widget and restarting the entire Plasma shell to test it, use the plasmoidviewer tool. This runs the widget in a standalone window, preventing desktop crashes if the widget contains bugs.

  • Command: plasmoidviewer -a org.kde.tailscale_widget

4. QProcess Security

When executing Tailscale commands via QProcess in the C++ backend:

  • Do not run commands with elevated privileges. The Tailscale daemon provides user-level access to the CLI by default.
  • Always sanitize or strictly control arguments passed to QProcess (e.g., when switching profiles) to prevent arbitrary command execution.