# AGENTS.md

## Build & Install

```bash
# 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
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.