From e60b19acafda8613d4533538d701133a55ad85ec Mon Sep 17 00:00:00 2001 From: Wang Zichong Date: Thu, 9 Jul 2026 20:04:43 +0800 Subject: [PATCH] switch to use system gammaray, and CPack DEB packaging --- .gitignore | 2 ++ README.md | 40 +++++++++++++++++++++++------- bridge/CMakeLists.txt | 44 ++++++++++++++++++++++----------- bridge/run.sh | 8 +++--- bridge/src/scenegraph_tools.cpp | 1 - 5 files changed, 67 insertions(+), 28 deletions(-) diff --git a/.gitignore b/.gitignore index 01edc6d..db972d1 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,8 @@ build/ bridge/build/ install-prefix/ +_CPack_Packages/ +*.deb # Compiled test binaries (not committed) tests/testapp/widget_test_app diff --git a/README.md b/README.md index 87cef65..d5cae8e 100644 --- a/README.md +++ b/README.md @@ -16,26 +16,37 @@ The bridge is a GammaRay **client**: it connects to a probe injected into a targ - Qt 6.8+ (system) - C++20 compiler (GCC 12+, Clang 16+) -- GammaRay 3.4.0+ built from source (see [build instructions](#building-gammaray)) +- GammaRay 3.4.0+ (system package: `gammaray-dev` on Debian/Deepin) - [qtmcp](https://github.com/signal-slot/qtmcp) (consumed via FetchContent — no manual install) - Python 3.10+ with `pytest` (for running the test suite) ## Building -### 1. Build and install GammaRay +### 1. Install system dependencies ```bash -cmake -S /path/to/GammaRay -B /path/to/GammaRay/build \ - -DCMAKE_INSTALL_PREFIX=$(pwd)/install-prefix -cmake --build /path/to/GammaRay/build -cmake --install /path/to/GammaRay/build --prefix $(pwd)/install-prefix +# Debian / Deepin +sudo apt install gammaray-dev gammaray-plugin-quickinspector ``` ### 2. Build the bridge ```bash cd bridge -cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH=$(pwd)/../install-prefix +cmake -S . -B build -G Ninja +cmake --build build +``` + +#### Offline build (using a local qtmcp clone) + +If you have a local clone of qtmcp (e.g. at `/home/user/Sources/qtmcp`), +pass `FETCHCONTENT_SOURCE_DIR_QTMcp` to skip the network fetch: + +```bash +cd bridge +cmake -S . -B build -G Ninja \ + -DFETCHCONTENT_SOURCE_DIR_QTMcp=/home/user/Sources/qtmcp \ + -DFETCHCONTENT_FULLY_DISCONNECTED=ON cmake --build build ``` @@ -43,11 +54,11 @@ cmake --build build ```bash # Start a probe (inject into a QML app) -install-prefix/bin/gammaray --inject-only --listen tcp://127.0.0.1:11732 \ +gammaray --inject-only --listen tcp://127.0.0.1:11732 \ --injector preload /usr/lib/qt6/bin/qml /path/to/app.qml -platform offscreen # Or inject into a widget app -install-prefix/bin/gammaray --inject-only --listen tcp://127.0.0.1:11732 \ +gammaray --inject-only --listen tcp://127.0.0.1:11732 \ --injector preload /path/to/widget-app # Start the bridge (stdio MCP server) @@ -56,6 +67,17 @@ bridge/run.sh The bridge starts in lazy-connect mode. Call `connectProbe("127.0.0.1", 11732)` from your MCP client once the probe is up. +### 4. Build a .deb package (optional) + +```bash +cd bridge/build +cpack -G DEB +``` + +The package installs the bridge binary (`/usr/bin/gammaray-mcp-bridge`), +qtmcp shared libs and plugins, and the `run.sh` helper script. +System dependencies (`gammaray >= 3.4.0`, Qt6 libs) are auto-detected. + ## MCP Tools ### Connection management diff --git a/bridge/CMakeLists.txt b/bridge/CMakeLists.txt index d542ca5..2cb1c49 100644 --- a/bridge/CMakeLists.txt +++ b/bridge/CMakeLists.txt @@ -29,10 +29,13 @@ FetchContent_Declare( # Qt-prefixed vars (NOT BUILD_EXAMPLES) — verified to suppress example/test build. set(QT_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE) set(QT_BUILD_TESTS OFF CACHE BOOL "" FORCE) +# qtmcp is built as shared libs + plugins (Qt plugin system requires this). +# For a distribution deb, the package includes the qtmcp shared libs and +# stdio plugin alongside the bridge binary. CPACK_DEBIAN_PACKAGE_SHLIBDEPS +# auto-detects the required system dependencies (gammaray, qt6, etc.). FetchContent_MakeAvailable(qtmcp) -# --- GammaRay (built & installed in ../install-prefix by Step 1) --- -# Pass -DCMAKE_PREFIX_PATH=$(pwd)/../install-prefix at configure. +# --- GammaRay (system package: gammaray-dev >= 3.4.0) --- find_package(GammaRay REQUIRED) # --- Qt6 components for the bridge target (Qt6 already found globally by qtmcp) --- @@ -68,17 +71,30 @@ target_link_libraries(gammaray-mcp-bridge PRIVATE Qt6::McpCommon ) -# Add GammaRay source common/ for message.h (not in installed headers) -target_include_directories(gammaray-mcp-bridge PRIVATE - /home/blumia/Sources/GammaRay/common +install(TARGETS gammaray-mcp-bridge RUNTIME DESTINATION bin) +install(PROGRAMS run.sh DESTINATION bin) + +# Runtime: qtmcp shared libs and stdio plugin are built in the build tree. +# For development, run.sh sets LD_LIBRARY_PATH and QT_PLUGIN_PATH. +# For distribution, CPack bundles qtmcp's install rules automatically. +set_target_properties(gammaray-mcp-bridge PROPERTIES + BUILD_RPATH "$" + INSTALL_RPATH "$ORIGIN/../lib/x86_64-linux-gnu" ) -# Runtime: qtmcp builds SHARED libs + the stdio backend plugin into the build -# tree. Set RPATH so the bridge finds libQt6Mcp*.so, and set QT_PLUGIN_PATH at -# run time (see run.sh) so Qt loads mcpserverbackend/libqmcpserverstdio.so. -# Also add GammaRay's install lib dir for libgammaray_*.so. -set(_GR_LIBDIR "$") -set_target_properties(gammaray-mcp-bridge PROPERTIES - BUILD_RPATH "$;${CMAKE_SOURCE_DIR}/../install-prefix/lib" - INSTALL_RPATH "$ORIGIN/../lib" -) +# --- CPack packaging --- +set(CPACK_PACKAGE_NAME "gammaray-mcp-bridge") +set(CPACK_PACKAGE_VERSION "0.1.0") +set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "GammaRay MCP bridge") +set(CPACK_PACKAGE_DESCRIPTION "MCP server that exposes GammaRay probe introspection data (QML SceneGraph, QML items, and Qt Widgets) to LLMs for assisted debugging.") +set(CPACK_PACKAGE_CONTACT "Blumia ") +set(CPACK_PACKAGE_VENDOR "gammaray-mcp") +set(CPACK_PACKAGE_SECTION "devel") +set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Blumia ") +set(CPACK_DEBIAN_PACKAGE_SECTION "devel") +set(CPACK_DEBIAN_PACKAGE_HOMEPAGE "https://github.com/blumia/gammaray-mcp") +set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON) +set(CPACK_DEBIAN_PACKAGE_RECOMMENDS "gammaray-plugin-quickinspector") +set(CPACK_DEBIAN_FILE_NAME "DEB-DEFAULT") +set(CPACK_GENERATOR "DEB") +include(CPack) diff --git a/bridge/run.sh b/bridge/run.sh index 18f47d6..cc30006 100755 --- a/bridge/run.sh +++ b/bridge/run.sh @@ -1,13 +1,13 @@ #!/bin/sh # Run the GammaRay MCP bridge. -# Sets up LD_LIBRARY_PATH (GammaRay + qtmcp libs) and QT_PLUGIN_PATH (qtmcp stdio -# backend plugin) so the bridge can find everything at runtime. +# Sets up LD_LIBRARY_PATH for qtmcp shared libs (in build tree) and QT_PLUGIN_PATH +# (qtmcp stdio backend plugin) so the bridge can find everything at runtime. +# GammaRay libraries come from the system package (gammaray-dev). # SPDX-License-Identifier: GPL-2.0-or-later set -e HERE="$(cd "$(dirname "$0")" && pwd)" -ROOT="$HERE/.." BLD="$HERE/build" -export LD_LIBRARY_PATH="$ROOT/install-prefix/lib:$BLD/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH:-}" +export LD_LIBRARY_PATH="$BLD/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH:-}" export QT_PLUGIN_PATH="$BLD/lib/x86_64-linux-gnu/qt6/plugins:${QT_PLUGIN_PATH:-}" export QT_QPA_PLATFORM=offscreen exec "$BLD/gammaray-mcp-bridge" "$@" diff --git a/bridge/src/scenegraph_tools.cpp b/bridge/src/scenegraph_tools.cpp index 6df2fe2..f6ee123 100644 --- a/bridge/src/scenegraph_tools.cpp +++ b/bridge/src/scenegraph_tools.cpp @@ -12,7 +12,6 @@ #include "quickinspector_types.h" #include -#include #include #include