JNetApplet/AGENTS.md

AGENTS.md

Guidance for AI agents working in this repo. Verified against CMakeLists.txt, package/metadata.json.in, and the installed macro file at /usr/lib/x86_64-linux-gnu/cmake/DDEShell/DDEShellPackageMacros.cmake.

What this is

A dde-shell applet (deepin desktop shell panel widget) for network speed monitoring. Uses a C++ backend (NetworkMonitorApplet class) for data collection and a QML frontend for the UI. The C++ backend reads /proc/net/dev to monitor network traffic.

• Applet ID: space.jokul.JNetApplet.
• Root element of networkview.qml must be AppletItem from import org.deepin.ds 1.0.

Features

• Real-time download/upload speed monitoring (1-second refresh)
• Total data transfer statistics
• Multiple network interface support with interface switching
• Taskbar icon displays live speed (changes color at high speeds)
• Hover tooltip shows speed summary
• Click to open detailed popup
• Popup shows active interface IP address, per-interface speed comparison and stats
• One-click plugin uninstall from the popup

Build & install

Requires the DDEShell CMake package (from the dde-shell dev package) at configure time. Standard flow:

cmake -B build
cmake --build build
sudo cmake --install build   # -> /usr/share/dde-shell/space.jokul.JNetApplet/

Or use the install script:

bash install.sh

cmake --install needs sudo because the default DDE_SHELL_PACKAGE_INSTALL_DIR is /usr/share/dde-shell (a CMake CACHE variable on this system).

Deb packaging

build-deb.sh builds a .deb from the version declared in CMakeLists.txt:

bash build-deb.sh   # -> jnetapplet_<version>_<arch>.deb

After installation, restart dde-shell:

systemctl --user restart dde-shell@DDE

There is no test, lint, typecheck, or CI target. Verification is manual: install, then restart dde-shell (it discovers applets by scanning the install dir for metadata.json).

Project structure

├── CMakeLists.txt                 # Build configuration
├── install.sh                     # Install script
├── build-deb.sh                   # Deb packaging script
├── src/
│   ├── networkmonitorapplet.h     # C++ backend header
│   └── networkmonitorapplet.cpp   # C++ backend implementation
├── package/
│   ├── metadata.json.in           # Plugin metadata 模板（由 CMake 生成 metadata.json）
│   └── networkview.qml            # QML UI
├── docs/                          # Design docs and implementation plans
└── AGENTS.md                      # This file

Architecture

┌──────────────────────────────────────────────────┐
│              DDE Shell Taskbar                   │
├──────────────────────────────────────────────────┤
│        space.jokul.JNetApplet                    │
│  ┌────────────────┐  ┌────────────────────────┐  │
│  │ C++ Backend    │  │ QML Frontend           │  │
│  │ NetworkMonitor │  │ networkview.qml        │  │
│  │ - /proc/net/dev│  │ - Speed display        │  │
│  │ - Speed calc   │  │ - Popup window         │  │
│  │ - Interface    │  │ - Interface switcher   │  │
│  └────────────────┘  └────────────────────────┘  │
└──────────────────────────────────────────────────┘

C++ Backend (NetworkMonitorApplet)

Inherits from DApplet, provides:

• downloadSpeed / uploadSpeed: Current speed in bytes/sec
• totalDownload / totalUpload: Total data transferred
• networkInterfaces: List of available interfaces
• interfaceStats: Per-interface statistics
• activeInterface: Currently selected interface
• ipAddress: IP address of the active interface
• refresh(): Manually trigger stats update
• setActiveInterface(name): Switch active interface

Identifier correspondence (keep in sync when renaming)

Where	Field	Value
CMakeLists.txt	add_library(...) target	space.jokul.JNetApplet
CMakeLists.txt	PLUGIN_ID	space.jokul.JNetApplet
package/metadata.json.in	Plugin.Id	space.jokul.JNetApplet

Plugin.Url (networkview.qml) is a path relative to package/, not an identifier. Keep it pointing at the entry QML.

Required metadata fields (QML applet)

package/metadata.json.in is the template; CMake's configure_file() generates the final metadata.json in the build directory at configure time. The template must contain Plugin.Version, Plugin.Id, Plugin.Url, and Plugin.Parent. Don't drop any.

Version management

Single source of truth: CMakeLists.txt line 3 project(JNetApplet VERSION x.y.z).

• package/metadata.json.in uses @PROJECT_VERSION@ placeholder, substituted at configure time -> installed metadata.json always matches.
• build-deb.sh extracts the version directly from CMakeLists.txt via grep.
• To bump the version: edit only the project(... VERSION ...) line in CMakeLists.txt. All downstream consumers (install, deb) pick it up automatically.

Conventions

• QML files carry SPDX headers (SPDX-FileCopyrightText + SPDX-License-Identifier: LGPL-3.0-or-later). Preserve on new/edited QML files.
• C++ files carry SPDX headers (SPDX-License-Identifier: LGPL-3.0-or-later).
• Default branch is master (not main).
• QML property types must be QML-compatible (use double/real instead of qint64).