JSwitchDisplayApplet/AGENTS.md

AGENTS.md

Build & Install

# Quick build + install (requires sudo password in terminal)
bash install.sh

# Or manual:
cmake -Bbuild && cmake --build build
sudo cmake --install build
systemctl --user restart dde-shell@DDE

• sudo requires a real TTY — agent bash tool cannot provide passwords. Tell the user to run install commands in their terminal.
• install.sh order: build → remove old → install → restart. If build fails, old plugin is NOT removed (set -e).
• Never declare a Q_INVOKABLE method or Q_PROPERTY without implementing it before building. The .so will load but dde-shell will crash with undefined symbol, taking down the entire taskbar.

Deb Packaging

bash build-deb.sh           # output to release/
bash build-deb.sh --install # build + install + restart

• dpkg-buildpackage outputs to ../, build-deb.sh moves artifacts to release/.
• debian/compat must NOT exist — compat level is declared in debian/control via debhelper-compat (= 13).

Architecture

DDE Shell taskbar plugin. C++ backend (graphicsdriverapplet.cpp) + QML frontend (package/driverview.qml).

• Root element: AppletItem with import org.deepin.ds.dock 1.0
• Plugin ID: org.deepin.ds.graphics-driver, parent: org.deepin.ds.dock
• dockOrder: 21 = right side of taskbar (20-30 range)
• C++ exposes properties via Q_PROPERTY + Q_INVOKABLE, QML accesses via applet (the Applet attached object)
• PanelPopup for click popup, PanelToolTip for hover tooltip
• DockPanelPositioner.bounding must be set before calling open() on popup/tooltip

LSP False Positives

The LSP reports errors like 'applet.h' file not found and Unknown type name 'DS_BEGIN_NAMESPACE'. These are pre-existing and expected — the dde-shell headers are in /usr/include/dde-shell/ which LSP doesn't index. Do NOT attempt to fix them. Verify with cmake --build build instead.

Data Collection (no D-Bus)

All GPU data is collected directly from sysfs/command-line tools (no D-Bus service):

Data	NVIDIA	AMD/Intel
GPU detect	lspci -mm	lspci -mm
Driver name	/sys/bus/pci/devices/0000:XX:XX.X/driver symlink → symLinkTarget().section('/', -1)	same
Driver version	/proc/driver/nvidia/version (regex Kernel Module\s+(\d+\.\d+\.\d+))	/proc/sys/kernel/osrelease (prefixed "Linux ")
Temperature	nvidia-smi --query-gpu=...	/sys/class/hwmon/hwmonN/temp1_input (÷1000)
GPU usage	nvidia-smi	/sys/class/drm/cardN/device/gpu_busy_percent
VRAM	nvidia-smi	/sys/class/drm/cardN/device/mem_info_vram_* (bytes → MB)
Primary GPU	/sys/bus/pci/devices/.../boot_vga = 1	same
GPU mode	Check /usr/share/X11/xorg.conf.d/nvidia-drm-outputclass.conf existence → PRIME	—

• PCI→DRM card mapping: scan /sys/bus/pci/devices/0000:XX:XX.X/drm/ for cardN entries (regex ^card(\d+)$).
• gpuStats property format: QStringList, one line per GPU: "temp|gpuUsage|memUsage|memUsed|memTotal" (-1 = unavailable).
• nvidia-smi query: --query-gpu=pci.bus_id,temperature.gpu,utilization.gpu,utilization.memory,memory.total,memory.used --format=csv,noheader,nounits. Match by PCI bus ID (last two segments).

Translations

• .ts files in translations/, compiled to .qm at build time via lrelease.
• lrelease path: /usr/lib/qt6/bin/lrelease
• Manual lupdate target: cmake --build build --target update_translations
• For simple string additions, edit .ts files directly (add <message> blocks).
• Watch for Unicode dashes: previous edits introduced em-dash (U+2014) where ASCII hyphen was intended. The edit tool may fail to match strings containing these. Use Python re.sub as fallback.

QML Conventions

• Colors derived from DockPalette.iconTextPalette (basePalette): primaryText, secondaryText, tertiaryText, cardBackground, cardBorder, accentBlue, accentBlueLight.
• Existing JS helper functions in driverview.qml: parseGpuName(), parseDriverInfo(), parseDriverName(), parseDriverVersion(), parseGpuVendorShort(), buildToolTipText().
• deviceInfo format: each line = "GPU Name (driver version)". Parsed by splitting on ( and ).
• Timer pattern: statsRefreshTimer (2s interval) starts on popup open AND tooltip hover, stops on close/leave.

No Tests

No test suite exists. Verify changes by building + installing + visually checking the taskbar.

Reference Plugin

/home/Jokul/Downloads/dde-weather/ — another dde-shell plugin using the same AppletItem/PanelPopup pattern. Useful reference for UI structure.