Integrating Kanzi Monitor as a prebuilt library¶

You can integrate Kanzi Monitor as a prebuilt library into your Kanzi application project. The prebuilt libraries are located in the <KanziWorkspace>/Engine/plugins/monitor/lib directory.

Note

Kanzi 3.6 uses a different build system on each platform: Visual Studio on Windows, CMake + Gradle on Android, and SCons on Linux. The integration steps below follow that split. The conceptual steps are the same on every platform; only the build wiring and the plugin-registration call differ.

Integrating to Windows projects with Visual Studio¶

Kanzi 3.6 has no Win32 CMake package, so on Windows you integrate Kanzi Monitor through the Visual Studio project property sheets.

To integrate Kanzi Monitor as a prebuilt library to a Windows application project:

Register the plugin in your application.

In your Application-derived class, add Kanzi Monitor to the module names in onConfigure:
```
#include <kanzimonitor_module.hpp>

virtual void onConfigure(ApplicationProperties& configuration) KZ_OVERRIDE
{
    configuration.binaryName = "myapp.kzb.cfg";

    // Load the Monitor plugin. This registers the module and starts its services.
    configuration.moduleNames.push_back("kzmonitor");

    // Optional: give the plugin the Application instance to enable scene-aware
    // services such as the Overwatch scene-tree inspection.
    KanziMonitorModule::ApplicationReference::get().setApplication(this);
}
```
Note

Adding "kzmonitor" to moduleNames is what registers the plugin and starts its services. Linking the .lib alone only loads the DLL; it does not start the services (the Overwatch TCP port never opens). For static (non-_DLL) configurations there is no DLL to load by name, so instead call KanziMonitorModule::registerModule(getDomain()); from an overridden registerMetadataOverride(ObjectFactory&). Do not call registerModule() for _DLL configurations.

Add the Kanzi Monitor build wiring to the application’s dll_application.props property sheet (for the *_DLL configurations):

<PropertyGroup Label="UserMacros">
  <KanziMonitorPath>$(KanziEnginePath)\plugins\monitor</KanziMonitorPath>
</PropertyGroup>

<ItemDefinitionGroup>
  <ClCompile>
    <AdditionalIncludeDirectories>$(KanziMonitorPath)\include;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
    <!-- DLL configurations import the plugin's exported symbols. -->
    <PreprocessorDefinitions>KANZI_MONITOR_PLUGIN_API=__declspec(dllimport);%(PreprocessorDefinitions)</PreprocessorDefinitions>
  </ClCompile>
  <Link>
    <AdditionalLibraryDirectories>$(KanziMonitorPath)\lib\Win32\$(Configuration);%(AdditionalLibraryDirectories)</AdditionalLibraryDirectories>
    <AdditionalDependencies>kzmonitor.lib;%(AdditionalDependencies)</AdditionalDependencies>
  </Link>
</ItemDefinitionGroup>

For static configurations, define KANZI_MONITOR_PLUGIN_API= (empty) instead of __declspec(dllimport).

Note

Linking kzmonitor.lib is strictly required only if the application code calls the Kanzi Monitor C++ API (for example setApplication). A pure moduleNames integration with no API calls can skip the link step.

Make sure that kzmonitor.dll is findable at run time. Add its directory (<KanziWorkspace>/Engine/plugins/monitor/lib/Win32/<Configuration>) to the PATH, or copy the DLL next to the executable.
Make sure that the application has the necessary privileges to write files and open TCP sockets.

Integrating to Android projects with Gradle, CMake, and Android Studio¶

Note

On Kanzi 3.6 the App Framework application is native C++ — there is no droidfw Java API. Kanzi Monitor is a prebuilt per-ABI .so that you link into the application at build time with an IMPORTED CMake target. Dynamic loading through dlopen does not work because RTTI type information must resolve across the .so boundary.

To integrate Kanzi Monitor as a prebuilt library to an Android application project:

#include <kanzimonitor_module.hpp>

configuration.moduleNames.push_back("kzmonitor");                     // registers the plugin + starts services
KanziMonitorModule::ApplicationReference::get().setApplication(this); // optional: scene-aware services

In the application executable’s CMakeLists.txt, declare Kanzi Monitor as an imported shared library. Add this in the ANDROID branch, after the find_kanzi() and find_package() calls:
```
if(ANDROID)
    # Monitor was installed under <KanziWorkspace>/Engine/plugins/monitor.
    if(NOT MONITOR_ROOT)
        set(MONITOR_ROOT "$ENV{KANZI_HOME}/Engine/plugins/monitor")
    endif()
    add_library(kzmonitor SHARED IMPORTED)
    set_target_properties(kzmonitor PROPERTIES
        IMPORTED_LOCATION             "${MONITOR_ROOT}/lib/android/ES3_${CMAKE_BUILD_TYPE}/${ANDROID_ABI}/libkzmonitor.so"
        INTERFACE_INCLUDE_DIRECTORIES "${MONITOR_ROOT}/include"
        INTERFACE_COMPILE_DEFINITIONS "KANZI_MONITOR_PLUGIN_API=")
    target_link_libraries(${PROJECT_NAME} kzmonitor)
endif()
```
Set KANZI_HOME in the environment that runs Gradle, or pass -DMONITOR_ROOT=<path> explicitly. Alternatively, consume the plugin through the shipped CMake package under lib/android/cmake/ES3/$ANDROID_ABI/.
Note

Three wiring details are required:
- Set KANZI_MONITOR_PLUGIN_API= (empty) on the imported target’s INTERFACE_COMPILE_DEFINITIONS, or dependents fail to compile with incomplete type 'class KANZI_MONITOR_PLUGIN_API'.
- Do not add jniLibs.srcDirs for libkzmonitor.so. AGP auto-packages .so files from IMPORTED CMake targets; adding jniLibs too makes mergeNativeLibs fail with “More than one file”.
- Use the IMPORTED build-time link, not dlopen.
Add the required permissions to the application’s AndroidManifest.xml. See Setting permissions on Android.
Build the APK with the Kanzi Gradle Plugin, then forward the console port to reach it from the host:
```
adb forward tcp:56000 tcp:56000
```
Match the APK ABI to the device or emulator.

Integrating to Linux and QNX projects with SCons¶

On Kanzi 3.6, the Linux and QNX targets build with SCons: linux_x11_glx_cpp11 (Linux X11), linux_wayland_aarch64 (Linux Wayland, embedded aarch64), and qnx710_screen_aarch64_cxx (QNX 7.1 Screen, aarch64). The steps are the same for all of them; only the platform directory and the library path differ.

To integrate Kanzi Monitor as a prebuilt library to a Linux or QNX application project:

Register the plugin in your application.

The SCons integration links the plugin .so into the executable, so register it from code and do not add it to moduleNames:
```
#include <kanzimonitor_module.hpp>

// In onConfigure(...):
KanziMonitorModule::ApplicationReference::get().setApplication(this);

// In an overridden registerMetadataOverride(ObjectFactory&):
Domain* domain = getDomain();
KanziMonitorModule::registerModule(domain);
```
Note

On Linux, use registerModule, not moduleNames. Because the .so is linked into the executable, adding it to moduleNames as well makes the framework load it a second time, and Monitor’s exported "Logging" profiling category is then registered twice, aborting the application with Profiling category with name 'Logging' has been already registered.

Define the kzmonitor prebuilt library in your project’s configs/platforms/common/config.py, from engine_root (which points at the installed plugin), and add it to the application module:

# Kanzi Monitor prebuilt library, installed under <KanziWorkspace>/Engine/plugins/monitor.
monitor_dir = os.path.join(engine_root, "plugins", "monitor")
kzmonitor_lib = library("kzmonitor")
kzmonitor_lib.include_paths += [os.path.join(monitor_dir, "include")]
kzmonitor_lib.libpaths     += [os.path.join(monitor_dir, "lib", platform_name, profile_string)]
kzmonitor_lib.binaries     += ["kzmonitor"]
del kzmonitor_lib

m = module(project_name)
m.used_libraries += ["kzmonitor"]
# App code uses the Monitor C++ API, so add its headers and the export macro.
m.include_paths += [os.path.join(monitor_dir, "include")]
m.env["CPPDEFINES"] += ["KANZI_MONITOR_PLUGIN_API="]
del m

Build the project from the platform-specific SConstruct directory, for example:
```
scons release ES3
```
At run time, add the Monitor .so directory to LD_LIBRARY_PATH (together with the engine and platform library directories), set DISPLAY, and make sure the application can write files and open TCP sockets. The remote console listens on TCP port 56000.

Integrating Kanzi Monitor as a prebuilt library¶

Integrating to Windows projects with Visual Studio¶

Integrating to Android projects with Gradle, CMake, and Android Studio¶

Integrating to Linux and QNX projects with SCons¶

See also¶