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.

Adding Kanzi Monitor to an application with the integrate tool

For an application created from a Kanzi 4.1 application template, the integrate tool in the Kanzi Monitor package makes the Windows and Android build changes below for you, and removes them again. The templates already hold the Kanzi Monitor block in CMakeLists.txt, so the tool only switches it on:

  • In CMakeLists.txt, it sets KANZI_LINK_KZMONITOR on for Windows builds and adds the Kanzi Monitor library folder to the Visual Studio debugger’s PATH.

  • In configs/platforms/android_gradle/kanzinative/build.gradle, it changes -DKANZI_LINK_KZMONITOR=OFF to ON.

  • In configs/platforms/android_gradle/app/src/main/AndroidManifest.xml, it adds the INTERNET permission, which the remote console needs. When the application already requests INTERNET, the tool leaves the manifest as it is, and removing Kanzi Monitor keeps your own permission.

The tool changes the build of a platform only when the Kanzi workspace that the build uses has Kanzi Monitor for that platform: lib/Win64 for Windows, lib/android for Android, in <KanziWorkspace>/Engine/plugins/monitor. The Windows installer installs both; an extracted package has the platforms that you extracted. The tool says which platform it leaves out and why.

The build changes link Kanzi Monitor into the application. Kanzi loads Kanzi Monitor when the kzb lists it, which it does once Kanzi Monitor is added to the Kanzi Studio project. See Using the Kanzi Studio plugin. Alternatively, --module-names also adds kzmonitor to ModuleNames in bin/application.cfg. Kanzi reads that file on every platform and in the Kanzi Studio Preview, and stops at startup where it cannot open kzmonitor, for example in a Linux or QNX build of the same application. So the tool does not change it by default.

On Windows, Kanzi finds kzmonitor.dll as Windows finds any DLL: next to the executable, or on PATH. The Visual Studio debugger gets the Kanzi Monitor library folder through the change above. To run the application otherwise, add <KanziWorkspace>/Engine/plugins/monitor/lib/Win64/vs2022_<Config>_DLL to PATH, or deploy kzmonitor.dll with the application.

Kanzi Monitor has Android libraries for the arm64-v8a and x86_64 ABIs. Without the Gradle property arch, the application templates build every ABI that Kanzi has, and build an ABI that Kanzi Monitor does not have without Kanzi Monitor, with a CMake warning. An application whose kzb lists Kanzi Monitor then cannot load that kzb on a device that runs that ABI. To have Kanzi Monitor in every ABI that you build, build only the ABIs of Kanzi Monitor: pass -Parch=aarch64,x86_64 to Gradle, or add this line to configs/platforms/android_gradle/gradle.properties:

arch=aarch64,x86_64

The tool names the ABIs that the Kanzi Monitor in the workspace has.

On Android, the build packs libkzmonitor.so into the APK. To connect the tools from the host computer to a device connected with USB or to the Android Emulator, run adb forward tcp:56000 tcp:56000. See Connecting from the host computer.

Each change is a marked block or a marked line, so removing takes out exactly what adding put in. The Kanzi Monitor Tools window of Kanzi Studio makes the same changes without Python. See Using the Kanzi Studio plugin. To use the tool on the command line, you need Python 3. The tool is tools/monitor-integrate/monitor_integrate.py in the Kanzi Monitor package, which the installer puts in <KanziWorkspace>/Engine/plugins/monitor. Run:

python <KanziWorkspace>/Engine/plugins/monitor/tools/monitor-integrate/monitor_integrate.py check  <project>
python <KanziWorkspace>/Engine/plugins/monitor/tools/monitor-integrate/monitor_integrate.py add    <project> --yes
python <KanziWorkspace>/Engine/plugins/monitor/tools/monitor-integrate/monitor_integrate.py remove <project> --yes

<project> is the Kanzi Studio project file (<Name>.proj.kzm), its folder, the folder that holds Tool_project, or the application folder. The project can be in any folder: the tool finds the application through the Binary Export Directory of the Kanzi Studio project, or as the Application folder next to the project. When it finds no application, pass the application folder. A Kanzi Studio project without an application has no build configuration to change; for it, add Kanzi Monitor to the Kanzi Studio project. Without --yes, the tool shows what it would change and changes nothing. Then regenerate the build, for example with generate_cmake_vs2022_solution.bat.

Before the tool changes anything, it checks that it can make every change safely. When it cannot, it changes nothing and names each file and the reason. For example, the tool refuses:

  • An application that was not created from a Kanzi 4.1 application template, or whose Kanzi Monitor block differs from the template’s. The Android service application template has no Kanzi Monitor block.

  • A Kanzi workspace without Kanzi Monitor for any platform of the application.

  • An Android build without app/src/main/AndroidManifest.xml, or whose manifest has more than one <application>.

  • A file in UTF-16, or a change that the tool made earlier and that you edited since.

  • With --module-names: an application that sets moduleNames in its code.

In those cases, follow the steps below, or add Kanzi Monitor from the Kanzi Monitor Tools window of Kanzi Studio, which makes the same checks. The tool checks the workspace that each build uses: the Kanzi_DIR cached in an existing build folder, KANZI_HOME, or the workspace that holds the application, and for Android also kanzi.home in local.properties or in a gradle.properties. A -DKANZI_HOME that you give to CMake by hand, or a -P that you give to Gradle by hand, is not known to the tool. The template’s block links Kanzi Monitor only when KANZI_RESOLVER is cmake, the default.

Integrating to Windows projects with CMake and Visual Studio

To integrate Kanzi Monitor as a library to a Windows application project by hand, for example when the integrate tool refuses the application:

  1. Enable Kanzi Monitor in the top-level CMakeLists.txt:

    • If a Kanzi 4.1 application template created the application, its CMakeLists.txt already has an if(KANZI_LINK_KZMONITOR) block. Pass -DKANZI_LINK_KZMONITOR=ON when you generate the CMake project, and go to the next step.

    • Otherwise, for example when an earlier version of Kanzi Studio created the application, add this block after the add_executable(${PROJECT_NAME} ...) call, and pass -DKANZI_LINK_KZMONITOR=ON when you generate the CMake project:

      Note

      This block ends with target_link_libraries(${PROJECT_NAME} ...), so place it after the add_executable(${PROJECT_NAME} ...) call that creates the target, not immediately after include(kanzi-common). Placing it before the target exists fails CMake configuration with “Cannot specify link libraries for target … which is not built by this project.”

      if(KANZI_LINK_KZMONITOR)
          set(PLUGIN_COMMON_SETUP cmake/common-setup.cmake)
          # KANZI_MONITOR_ROOT can be set explicitly: cmake -DKANZI_MONITOR_ROOT=<path>
          # If not set, auto-detection from known locations is attempted.
          if(NOT KANZI_MONITOR_ROOT)
              if(EXISTS ${PROJECT_SOURCE_DIR}/../../../Engine/plugins/monitor/${PLUGIN_COMMON_SETUP})
                  set(KANZI_MONITOR_ROOT ${PROJECT_SOURCE_DIR}/../../../Engine/plugins/monitor)
              elseif(DEFINED ENV{KANZI_HOME} AND
                     EXISTS "$ENV{KANZI_HOME}/Engine/plugins/monitor/${PLUGIN_COMMON_SETUP}")
                  set(KANZI_MONITOR_ROOT "$ENV{KANZI_HOME}/Engine/plugins/monitor")
              endif()
              if(NOT KANZI_MONITOR_ROOT)
                  message(FATAL_ERROR
                      "Cannot find Monitor plugin root directory. "
                      "Pass -DKANZI_MONITOR_ROOT=<path> to CMake, set the KANZI_HOME "
                      "environment variable to your Kanzi workspace root, or install "
                      "the plugin under 'WORKSPACE/Engine/plugins'.")
              endif()
          endif()
          include(${KANZI_MONITOR_ROOT}/${PLUGIN_COMMON_SETUP})
          include(${KANZI_MONITOR_ROOT}/cmake/monitor-config.cmake)
          target_link_libraries(${PROJECT_NAME} ${KANZI_MONITOR_NAMESPACE}kzmonitor)
      endif()
      
  2. Add the Kanzi Monitor library folder to the environment of the Visual Studio debugger, so that the debugger finds the Kanzi Monitor DLL. In CMakeLists.txt, add this after the line that sets VS_DEBUGGER_ENVIRONMENT, or at the end of the file if it has no such line:

    # Add the Kanzi Monitor library location to the VS debugger environment.
    if(KANZI_LINK_KZMONITOR AND KANZI_MONITOR_ROOT)
        set_target_properties(${PROJECT_NAME} PROPERTIES VS_DEBUGGER_ENVIRONMENT
            "${KANZI_VS_DEBUGGER_ENVIRONMENT};${KANZI_MONITOR_ROOT}/${PLATFORM_LIBRARY_DIR}")
    endif()
    
  3. (Optional) If the Kanzi Monitor plugin is not added to the Kanzi Studio project, enable the plugin by adding it to the ModuleNames configuration option in application.cfg:

    ModuleNames = "kzmonitor"
    
  4. (Optional) Enable the application executable to use the Kanzi Monitor C++ API.

    In the CMakeLists.txt for the application executable, add the Kanzi Monitor headers to the include directories inside the if(KANZI_LINK_KZMONITOR) block:

    # Add the Kanzi Monitor include path.
    target_include_directories(${PROJECT_NAME}
        PRIVATE ${KANZI_MONITOR_ROOT}/include)
    
  5. (Optional) To enable rendering statistics and GPU object counts in Release and Profiling builds, enable the Kanzi graphics statistics layer. You can do this in either application.cfg:

    GraphicsStatisticEnabled = true
    

    or in onConfigure():

    configuration.graphicsStatisticsEnabled = true;
    

    In Debug builds, the graphics statistics layer is enabled by default. Without this setting, the Kanzi Monitor still reports FPS, frame time, resource counts, and memory usage, but per-frame rendering counters and GPU object counts remain zero.

    See GraphicsStatisticEnabled in the Kanzi application configuration reference.

  6. Regenerate the project from the updated CMake files.

    For example, run the generate_cmake_vs2022_solution.bat script.

  7. 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 Android, you must link Kanzi Monitor with target_link_libraries at build time. Dynamic plugin loading via ModuleNames alone does not work on Android because RTTI type information is not shared across .so library boundaries, which prevents the Kanzi Engine from recognizing the plugin module.

To integrate Kanzi Monitor as a library to an Android application project by hand, for example when the integrate tool refuses the application:

  1. In the configs/platforms/android_gradle/kanzinative/build.gradle, enable Kanzi Monitor linking. If a Kanzi 4.1 application template created the application, the file has the line arguments "-DKANZI_LINK_KZMONITOR=OFF": change OFF to ON. Otherwise add the argument:

    Note

    In Gradle projects, enable Kanzi Monitor linking by passing -DKANZI_LINK_KZMONITOR=ON in the cmake { arguments } block of the kanzinative/build.gradle:

    cmake {
        // Enable to add Monitor plugin to the AAR.
        arguments "-DKANZI_LINK_KZMONITOR=ON"
    }
    
  2. Build only the ABIs that Kanzi Monitor has.

    Kanzi Monitor has Android libraries for the arm64-v8a and x86_64 ABIs. Without the Gradle property arch, the application templates build every ABI that Kanzi has, and build an ABI that Kanzi Monitor does not have without Kanzi Monitor, with a CMake warning. An application whose kzb lists Kanzi Monitor then cannot load that kzb on a device that runs that ABI. To have Kanzi Monitor in every ABI that you build, build only the ABIs of Kanzi Monitor: pass -Parch=aarch64,x86_64 to Gradle, or add this line to configs/platforms/android_gradle/gradle.properties:

    arch=aarch64,x86_64
    
  3. In the CMakeLists.txt of the application:

    • If a Kanzi 4.1 application template created the application, the file already has an if(KANZI_LINK_KZMONITOR) block. Go to the next step.

    • Otherwise, add this block after the add_executable(${PROJECT_NAME} ...) call:

      Note

      This block ends with target_link_libraries(${PROJECT_NAME} ...), so place it after the add_executable(${PROJECT_NAME} ...) call that creates the target, not immediately after include(kanzi-common). Placing it before the target exists fails CMake configuration with “Cannot specify link libraries for target … which is not built by this project.”

      if(KANZI_LINK_KZMONITOR)
          set(PLUGIN_COMMON_SETUP cmake/common-setup.cmake)
          # KANZI_MONITOR_ROOT can be set explicitly: cmake -DKANZI_MONITOR_ROOT=<path>
          # If not set, auto-detection from known locations is attempted.
          if(NOT KANZI_MONITOR_ROOT)
              if(EXISTS ${PROJECT_SOURCE_DIR}/../../../Engine/plugins/monitor/${PLUGIN_COMMON_SETUP})
                  set(KANZI_MONITOR_ROOT ${PROJECT_SOURCE_DIR}/../../../Engine/plugins/monitor)
              elseif(DEFINED ENV{KANZI_HOME} AND
                     EXISTS "$ENV{KANZI_HOME}/Engine/plugins/monitor/${PLUGIN_COMMON_SETUP}")
                  set(KANZI_MONITOR_ROOT "$ENV{KANZI_HOME}/Engine/plugins/monitor")
              endif()
              if(NOT KANZI_MONITOR_ROOT)
                  message(FATAL_ERROR
                      "Cannot find Monitor plugin root directory. "
                      "Pass -DKANZI_MONITOR_ROOT=<path> to CMake, set the KANZI_HOME "
                      "environment variable to your Kanzi workspace root, or install "
                      "the plugin under 'WORKSPACE/Engine/plugins'.")
              endif()
          endif()
          include(${KANZI_MONITOR_ROOT}/${PLUGIN_COMMON_SETUP})
          include(${KANZI_MONITOR_ROOT}/cmake/monitor-config.cmake)
          target_link_libraries(${PROJECT_NAME} ${KANZI_MONITOR_NAMESPACE}kzmonitor)
      endif()
      
  4. If the Kanzi Monitor plugin is not added to the Kanzi Studio project, enable the plugin by adding it to the ModuleNames configuration option in application.cfg:

    ModuleNames = "kzmonitor"
    

    This is the recommended registration method for Android because it works with both Kanzi application frameworks:

    • appfw (Basic Application template) – The application has a C++ ExampleApplication subclass, so you can alternatively set configuration.moduleNames = { "kzmonitor" }; in onConfigure().

    • droidfw (Android Application template) – The application lifecycle is Java-driven and the C++ source is a stub, so application.cfg is the only viable registration path.

  5. (Optional) To enable rendering statistics and GPU object counts in Release and Profiling builds, enable the Kanzi graphics statistics layer. You can do this in application.cfg:

    GraphicsStatisticEnabled = true
    

    or in onConfigure() (appfw projects only):

    configuration.graphicsStatisticsEnabled = true;
    

    In Debug builds, the graphics statistics layer is enabled by default. Without this setting, the Kanzi Monitor still reports FPS, frame time, resource counts, and memory usage, but per-frame rendering counters and GPU object counts remain zero.

    See GraphicsStatisticEnabled in the Kanzi application configuration reference.

  6. Regenerate the project from the updated CMake files.

    For example, update your Android Studio and Gradle environment with the changes that you made to the CMake files.

  7. Make sure that the application has the necessary privileges to write files and open TCP sockets. See Setting permissions on Android.

See also

Integrating Kanzi Monitor from source code

Getting started with Kanzi Monitor