This topic shows how to generate the makefiles for the plug-ins and how to make sure that they are available for the Communicator.

If you have not implemented a plug-in yet, you may use the provided example plug-ins for an initial test or refer to the topic Getting Started with Plug-in Development to get information about the implementation of a plug-in.

How to Build a Plug-in

With CMake, the build system artifacts (e.g. Makefiles) are generated automatically according to the respective platform, toolchain, and generator.

To build the release version of the plug-in, you can use the following commands:

cmake -B <BUILD DIR> -S <PLUG-IN SOURCE DIR> -DCMAKE_PREFIX_PATH=<MERLIC INSTALL DIR> -DCMAKE_BUILD_TYPE=Release

cmake --build <BUILD DIR> --config Release

Example for Windows

The following code shows how to build the example plug-in "event-logger" on a Windows system.

cmake -B "%USERPROFILE%/communicator_plugin_builds/event-logger" -S "<MERLIC EXAMPLE DIR>/communicator_plugins/event-logger" -DCMAKE_PREFIX_PATH="<MERLIC INSTALL DIR>" -DCMAKE_BUILD_TYPE=Release

cmake --build "%USERPROFILE%/communicator_plugin_builds/event-logger" --config Release

The placeholder for <MERLIC EXAMPLE DIR> and <MERLIC INSTALL DIR> must be replaced with the path to the respective location of the MERLIC examples and the MERLIC installation.

Example for aarch64

The following code shows how to build the example plug-in "event-logger" for an aarch64 Linux target on a x64 Linux host:

cmake -B $HOME/communicator_plugin_builds/event-logger          \
      -S <MERLIC EXAMPLE DIR>/communicator_plugins/event-logger \
      -DCMAKE_PREFIX_PATH=<MERLIC INSTALL DIR>                  \
      -DCMAKE_BUILD_TYPE=Release                                \
      -DCMAKE_SYSTEM_NAME=Linux                                 \
      -DCMAKE_SYSTEM_PROCESSOR=aarch64                          \
      -DCMAKE_CXX_COMPILER=<AARCH64 CROSS COMPILER NAME>
cmake --build $HOME/communicator_plugin_builds/event-logger --config Release

The placeholder for <MERLIC EXAMPLE DIR> and <MERLIC INSTALL DIR> must be replaced with the path to the respective location of the MERLIC examples and the MERLIC installation.

In addition, you have to specify the compiler executable name for the placeholder <AARCH64 CROSS COMPILER NAME>, e.g., aarch64-linux-gnu-g++.

Additional Arguments for Plug-ins that Require Boost

To build a plug-in that requires the Boost libraries, you have to ensure that Boost is already installed on your system. When building the plug-in, you have to specify the respective installation directory of Boost with the additional argument "DBoost_ROOT".

For more information on the Boost libraries and the installation, see the Getting Started Guide of Boost.

The following section shows an example of how to build a plug-in that requires the Boost libraries.

Example

The provided example plug-in "action-sender" uses the Boost ASIO library for portable networking and requires Boost 1.73 or newer. Therefore, it must be built with the additional "DBoost_ROOT" argument. The following code shows the commands for Windows systems:

cmake -B "%USERPROFILE%/communicator_plugin_builds/action-sender" -S "<MERLIC EXAMPLE DIR>/communicator_plugins/action-sender" -DCMAKE_PREFIX_PATH="<MERLIC INSTALL DIR>" -DBoost_ROOT="<BOOST INSTALL DIR>" -DCMAKE_BUILD_TYPE=Release

cmake --build "%USERPROFILE%/communicator_plugin_builds/action-sender" --config Release

The placeholder for <MERLIC EXAMPLE DIR>, <MERLIC INSTALL DIR>, and <BOOST INSTALL DIR> must be replaced with the path to the respective location of the MERLIC examples, the MERLIC installation, and the Boost installation.

To get more detailed information about CMake, see the respective documentation at cmake.org/documentation.

Providing the Plug-ins for the Communicator

Plug-in Directory

To ensure that the plug-ins can be found by the Communicator, you have to copy them after the build to your plug-in directory. By default, the plug-in directory is either "%PROGRAMFILES%\MVTec\MERLIC-5.4\bin\x64-win64" (if MERLIC was installed with administrator rights) or the directory "%LOCALAPPDATA%\Programs\MVTec\MERLIC-5.4\bin\x64-win64" (if MERLIC was installed without administrator rights). This is also the location where the standard plug-ins of MERLIC, including the example plug-ins, are located.

It is also possible to change the plug-in directory or to specify multiple plug-in directories, e.g., if you want to keep the plug-in library in the respective build output directory instead of copying the file to the default plug-in directory. For more information, see the topic "Changing Communicator and Plug-in Settings" in the Communicator Manual.

Naming Convention

In addition, a specific naming convention is required: You have to make sure that the file name of the corresponding dynamic library starts with "pMV".

In the "Communication" tab of the MERLIC RTE Setup, this prefix is not shown in the names of the listed plug-ins but it is used to differentiate plug-ins from any other dynamic libraries which may be placed in the same directory as plug-in dependencies. For instance, "pMVevent-logger.dll" on Windows or "pMVevent-logger.so" on Linux corresponds to the plug-in named "event-logger".

Providing the Directory for Additional Files

When loading a Communicator plug-in from a custom plug-in directory, any indirect library dependencies, i.e., DLL files, which are located in the same directory as the plug-in, are automatically resolved when using Windows. For Linux you have to set the RPATH of your plug-in manually for the Communicator executable to be able to load additional files. The required settings can be copied from the CMakeLists.txt of our example plug-ins and adapted for your project.