Integrating Kanzi Monitor from source code

Integrate Kanzi Monitor from source code when you want your own Kanzi application project to build Kanzi Monitor as part of your build — for example, when you have a source-only Kanzi Monitor package, when you need to modify or debug the plugin itself, or when a prebuilt binary is not available for your Kanzi version or toolchain.

With this method the Kanzi Monitor sources compile together with your application; there is no separate prebuilt library to link against. The application-side wiring (registering the plugin, granting privileges) is the same as for the prebuilt method — see Integrating Kanzi Monitor as a prebuilt library.

Where the Kanzi Monitor source lives

The build steps below refer to the Kanzi Monitor root directory. You can point the build at either location:

• The installed plugin at <KanziWorkspace>/Engine/plugins/monitor/ (its sources are under src/ and headers under include/).

• A copy of the Kanzi Monitor source that you clone or extract into your own project tree (for example third_party/monitor/), so the plugin is versioned and built alongside your application. The steps are identical; only the path to the Kanzi Monitor root differs.

Either way, the build resolves the Kanzi engine from the KANZI_HOME environment variable, so set KANZI_HOME before you configure or build.

Integrating to Windows projects with Visual Studio

If your application uses a CMake build, follow Integrating with CMake (Windows and Android) below.

If your application uses a Visual Studio solution, add the bundled Kanzi Monitor project to your solution so it builds from source with your application:

1. Add configs/platforms/win32/KanziMonitor.vcxproj (from the Kanzi Monitor root) to your Visual Studio solution.

   The project locates the engine through KANZI_HOME (with a nested-workspace fallback), so no per-machine paths are baked in.

2. Add KanziMonitor as a project dependency (or reference) of your application project, so it builds first and your application links against the freshly built kzmonitor.lib / kzmonitor.dll.

3. In your application, add the Kanzi Monitor include/ directory to the include paths if the application code uses the Kanzi Monitor C++ API.

4. Register the plugin — see Registering the plugin.

Integrating with CMake (Windows and Android)

On any platform whose application build is driven by CMake — including the Android native (NDK/CMake) build — add the Kanzi Monitor sources to your build with add_subdirectory:

1. In your application’s CMakeLists.txt, set the Kanzi Monitor root directory.

   Use the installed location, or the path where you cloned the source into your project. On Android, add this after the find_kanzi() and find_package() calls:

   if(NOT KANZI_MONITOR_ROOT)
       set(KANZI_MONITOR_ROOT "$ENV{KANZI_HOME}/Engine/plugins/monitor")
   endif()
   

2. Add the Kanzi Monitor subdirectory:

   add_subdirectory(${KANZI_MONITOR_ROOT} "${CMAKE_BINARY_DIR}/monitor")
   

   Note

   When Kanzi Monitor is added as a subdirectory, its example application is not built. To also build the example, pass -DBUILD_EXAMPLES=ON. To build Kanzi Monitor as a static library instead of shared, pass -DBUILD_SHARED_LIBS=OFF.

3. Link the application executable with the Kanzi Monitor library.

   This propagates the Kanzi Monitor include directories and the KANZI_MONITOR_PLUGIN_API definition automatically, so no extra include or define wiring is needed:

   target_link_libraries(${PROJECT_NAME} KanziPlugin::kzmonitor)
   

4. Regenerate the project from the updated CMake files. On Android, sync the changes into your Android Studio / Gradle build.

5. On Android, make sure the application has the necessary privileges to write files and open TCP sockets. See Setting permissions on Android.

6. Register the plugin — see Registering the plugin.

Note

When you build the Kanzi Monitor Android plugin from source with Gradle, debug builds default to minimized debugging information (KANZI_ANDROID_MINIMIZE_DEBUG=ON, equivalent to -g1 — line tables only), which keeps the debug .so files from bloating with full -g symbols. To build with full debug symbols, pass -PminimizeDebug=false to the Gradle build. The prebuilt binaries in the delivered packages are already built this way.

Integrating to Linux and QNX projects with SCons

On Kanzi 3.6, these Kanzi Monitor build targets use SCons:

• linux_x11_glx_cpp11 — Linux X11.

• linux_wayland_aarch64 — Linux Wayland, embedded aarch64 (EGL/OpenGL ES).

• qnx710_screen_aarch64_cxx — QNX 7.1 Screen, aarch64, built with the C++/LLVM toolchain of the QNX Software Development Platform.

The integration steps below are the same for all of them; only the platform directory you build from differs.

To build Kanzi Monitor from source as part of a SCons application project:

1. In your project’s configs/platforms/common/config.py, define a kzmonitor module that builds from the Kanzi Monitor sources.

   Add this before your application module definition (adjust monitor_dir to the installed location or your in-project copy):

   # Path to the Kanzi Monitor plugin directory.
   monitor_dir = os.path.join(engine_root, "plugins", "monitor")
   
   # Define the kzmonitor module to build from source.
   kzmonitor = module("kzmonitor")
   kzmonitor.type = "a"
   kzmonitor.depends += ["kzcoreui", "kzui"]
   kzmonitor.root = os.path.join(monitor_dir, "src")
   kzmonitor.include_paths += [os.path.join(monitor_dir, "include")]
   kzmonitor.env["CPPDEFINES"] += ["KANZI_MONITOR_PLUGIN_API="]
   
   if GetOption("build-dynamic-libs"):  # .so with --dynamic, else static .a
       kzmonitor.type = "so"
       kzmonitor.env["SHLINKFLAGS"] += ["-shared"]
       kzmonitor.env["SHLINKFLAGS"] += ["-Wl,-soname,libkzmonitor.so"]
       kzmonitor.env["CPPDEFINES"] += ["DECLARE_PLUGIN_ENTRY"]
   
   del kzmonitor
   

2. In the same file, add kzmonitor as a dependency of your application module.

   If the application code uses the Kanzi Monitor C++ API, also add the Kanzi Monitor include path:

   m = module(project_name)
   m.depends += ["kzmonitor"]
   # Optional: add the Monitor include path if the application uses the Monitor API.
   m.include_paths += [os.path.join(monitor_dir, "include")]
   del m
   

3. Build the project from the platform-specific SConstruct directory, for example:

   cd configs/platforms/linux_x11_glx_cpp11
   KANZI_HOME=/path/to/linux-engine-sdk python2.7 $(command -v scons) release GL --dynamic -j4
   

   Omit --dynamic to link Kanzi Monitor as a static library.

4. Make sure the application has the necessary privileges to write files and open TCP sockets.

5. Register the plugin — see Registering the plugin.

Note

If you build over a Windows-mounted filesystem under WSL (a /mnt/c 9p mount), set [automount] options = "metadata" in /etc/wsl.conf and run wsl --shutdown first, or the SCons Install step fails with Operation not permitted.

Registering the plugin

Building Kanzi Monitor from source links it into your application at build time, whether it is built as a shared .so/.dll or as a static library. This build-time link is intentional: it lets the application call the Kanzi Monitor C++ API directly, and on platforms such as Android it is also required so that RTTI type information resolves across the shared-library boundary — which is why the .so is linked at build time rather than loaded with dlopen.

Linking the library does not by itself start the Kanzi Monitor services; the plugin must also be registered. This is a separate concern from how the library is built, and it works the same way as for the prebuilt method:

• Add kzmonitor to the module names — in kanzimonitor.cfg or in onConfigure — where the engine module system loads Kanzi Monitor by name (Windows *_DLL builds and Android):

  configuration.moduleNames.push_back("kzmonitor");
  

• Call KanziMonitorModule::registerModule() where the application registers the linked-in module itself (Windows static builds and Linux/SCons), and do not also add it to moduleNames.

For the details and the load-order caveat, see Loading Kanzi Monitor before dependent plugins.

See also

Integrating Kanzi Monitor as a prebuilt library

Getting started with Kanzi Monitor