Build Your First KDE Plasma 6 Plasmoid from Scratch

Diesen Artikel auf Deutsch lesen

Building a KDE Plasma widget from an empty directory means dealing with QML, CMake, packaging, settings and translations before the first useful line of UI appears. The KDE Plasma 6 Plasmoid Template prepares that recurring work so you can focus on the widget itself.

Video: From Clone to Desktop

What the template already gives you

This is a small but complete Plasma 6 project: compact and full representations, a configuration dialog, persistent settings, translation files and Qt Quick tests. CMake already knows about the KDE and Qt components required to build it. You get a working starting point instead of a collection of disconnected snippets.

pure QML for the user interface
KConfig settings with KCM.SimpleKCM
translation structure for German, French and Spanish
Qt Quick tests runnable with ctest
an optional C++ plugin example

1. Clone it and install dependencies

The video starts with a normal clone. On openSUSE Tumbleweed, install CMake, Extra CMake Modules, KDE Frameworks and the Qt Quick test packages:

git clone https://github.com/Agundur-KDE/KDE-Plasma-Plasmoid-template.git
cd KDE-Plasma-Plasmoid-template
sudo zypper install cmake kf6-extra-cmake-modules kf6-ki18n-devel \
  kf6-kconfig-devel kf6-kcmutils-devel qt6-quick-devel \
  qt6-test-devel qt6-quicktest-devel

Package names differ on Arch, KDE neon and Ubuntu. If you only want to try the CMake and test path, the repository also documents a CI container with the dependencies already installed.

2. Build, install and test

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$HOME/.local"
make -j$(nproc)
make install
ctest --output-on-failure

Installing into ~/.local needs no sudo. For fast QML iteration you do not need to install anything: plasmoidviewer -a package/ loads the package directly from the source tree.

3. The first gotcha: rename before customising

The template deliberately contains placeholders such as de.agundur.myplasmoid, myplasmoid and KDE-Template. Run the interactive rename script once before making the project your own:

bash rename.sh

It updates the package ID, metadata, translation filenames and URLs. Changing only the visible name in metadata.json leaves an old package ID or install path behind.

4. Change the UI and settings

The popup UI lives in package/contents/ui/main.qml. The compact and full representations stay together because QML IDs such as root are not automatically visible across separate files. Define settings in package/contents/config/main.xml and connect matching fields in configGeneral.qml.

That small amount of structure prevents the most confusing early failures: bindings pointing at invisible IDs, or a package that builds but does not expose its settings correctly.

5. Add translations

Put every visible string in i18n() or i18nc(). Then run Messages.sh to extract new strings and merge them into the existing PO files:

./Messages.sh

English is the source language and does not need its own PO file. Translators fill the new empty msgstr entries for the other languages. A common mistake is editing one PO file by hand and forgetting to refresh the POT structure after the next QML change.

A workflow that stays debuggable

Clone the repository and install dependencies.
Run rename.sh once.
Launch the unchanged template with plasmoidviewer.
Make one small QML change and test it immediately.
Add settings, translations and optional C++ only after the basic UI works.
Finish with a release build, ctest and an install test.

This makes it obvious whether a failure comes from your change or from the environment. The accompanying video demonstrates the whole path on a real desktop.

Code and video

The complete template is available on GitHub. The nine-minute video walks through cloning, renaming, translation, compilation and placing the resulting widget on the desktop.

Open the GitHub repository

← Back to Projects