4. Building from source

Since RTI Connext Gateway is distributed in source format, it must be compiled into a shared library before it can be used by Routing Service.

The code can be built using CMake, version 3.10.0 or greater.

4.1. Build Setup

RTI Connext DDS (version 7.3.0 or greater) must be available on the build system. The installation must include libraries for the target build architecture, and rtiddsgen.

Note

The location where RTI Connext DDS is installed will be referred to as NDDSHOME, while the target build architecture will be CONNEXTDDS_ARCH.

4.2. Compiling with CMake

4.2.1. Configuration

Create a build directory and run cmake to create build files for the build system of your preference.

At a minimum, you will need to specify:

CONNEXTDDS_DIR or NDDSHOME environment variable to select an RTI Connext DDS installation.

Optionally, you can use CMAKE_BUILD_TYPE to select the type of libraries to build (for example Release, or Debug, see CMake’s own documentation for CMAKE_BUILD_TYPE). This documentation and README files assume that you are using the Release build configuration. If you build the libraries using Debug configuration, you must run the debug version of Routing Service located at:

$NDDSHOME/resource/app/bin/<architecture>/rtiroutingserviceappd

It is also strongly recommended (albeit not required for building) that you also change the value of variable CMAKE_PREFIX_INSTALL, to specify a custom installation directory where all build artifacts will be copied after building. This directory can be copied, and deployed independently of the source and build directories.

# The build/ and install/ directories can be created inside the git clone
# (they are ignored via .gitignore)
mkdir rticonnextdds-gateways/build \
      rticonnextdds-gateways/install

cd rticonnextdds-gateways/build/

# CONNEXTDDS_DIR and CONNEXTDDS_ARCH will be read from the
# shell environment if not passed explicitly to cmake
cmake .. -DCONNEXTDDS_DIR=/path/to/rti_connext_dds/ \
         -DCMAKE_BUILD_TYPE=Debug|Release           \
         -DCMAKE_INSTALL_PREFIX=../install

4.2.2. Compilation

Once the project has been configured, libraries can be built using the selected toolchain, e.g.:

Linux® and macOS® systems:

cmake --build .

Windows® systems:

cmake --build . --config Debug|Release

4.2.3. Installation

It is recommended that you also run the install step, e.g.:

Linux and macOS systems:

cmake --build . -- install

Windows systems:

cmake --build . --config Debug|Release --target install

4.2.4. CMake General Options

This section summarizes all available CMake general options and configuration variables. Specific adapter options are explained in their corresponding sections.

4.2.4.1. CONNEXTDDS_DIR

Required: Only if NDDSHOME environment variable is not set.
Default: None
Description: The installation location of RTI Connext DDS must be specified using this variable or NDDSHOME environment variable. The latter will take precedence.

4.2.4.2. CONNEXTDDS_ARCH

Required: No
Default: None, if possible, it is taken from FindRTIConnextDDS.
Description: The identifier for the target build architecture must be specified using this variables. Required RTI Connext DDS libraries must be available within path NDDSHOME/lib/CONNEXTDDS_ARCH.

4.2.4.3. RTIGATEWAY_ENABLE_ALL

Required: No
Default: ON
Description: If enabled, all components will be enabled unless they are disabled specifically. This includes tests, examples, docs, plugins…

4.2.4.4. RTIGATEWAY_ENABLE_TESTS

Required: No
Default: ON
Description: If enabled, all tests of enabled plugins will be built.

4.2.4.5. RTIGATEWAY_ENABLE_EXAMPLES

Required: No
Default: ON
Description: If this variable is enabled, all the examples of enabled plugins will be built.

4.2.4.6. RTIGATEWAY_ENABLE_DOCS

Required: No
Default: ON
Description: If enabled, the RTI Connext Gateway user manual (this document) will be built, along with specific documentation for every enabled plugin. Make sure to have Sphinx, breathe and doxygen installed.

4.2.5. Plugins CMake Specific Options

4.2.5.1. RTIGATEWAY_ENABLE_MODBUS

Required: No
Default: ON
Description: If this variable is enabled, the Modbus adapter and all of its components (tests, examples, docs…) will be enabled, unless they have been explicitly disabled using the dedicated variables.

4.2.5.2. RTIGATEWAY_ENABLE_MQTT

Required: No
Default: ON
Description: If this variable is enabled, the MQTT adapter and all of its components (tests, examples, docs…) will be enabled, unless they have been explicitly disabled using the dedicated variables.

4.2.5.3. RTIGATEWAY_ENABLE_KAFKA

Required: No
Default: ON
Description: If this variable is enabled, the Kafka adapter and all of its components (tests, examples, docs…) will be enabled, unless they have been explicitly disabled using the dedicated variables.

4.2.5.4. RTIGATEWAY_ENABLE_FWD

Required: No
Default: ON
Description: If this variable is enabled, the forwarder processor and all of its components (tests, examples, docs…) will be enabled, unless they have been explicitly disabled using the dedicated variables.

4.2.5.5. RTIGATEWAY_ENABLE_TSFM_FIELD

Required: No
Default: ON
Description: If this variable is enabled, the field transformation and all of its components (tests, examples, docs…) will be enabled, unless they have been explicitly disabled using the dedicated variables.

4.2.5.6. RTIGATEWAY_ENABLE_TSFM_JSON

Required: No
Default: ON
Description: If this variable is enabled, the JSON transformation and all of its components (tests, examples, docs…) will be enabled, unless they have been explicitly disabled using the dedicated variables.

4.2.5.7. RTIGATEWAY_ENABLE_TSFM_SEQUENCE2ARRAY

Required: No
Default: ON
Description: If this variable is enabled, the Sequence2Array transformation and all of its components (tests, examples, docs…) will be enabled, unless they have been explicitly disabled using the dedicated variables.

4.2.5.8. RTIGATEWAY_ENABLE_LOG

Required: No
Default: OFF (for Release), ON (for Debug)
Description: By default, plugins will not print any messages to standard output when built in Release mode. When built in Debug mode, or if RTIGATEWAY_ENABLE_LOG is enabled, plugins will print informational and error messages to standard output. These messages cannot be disabled at run-time.
Note: This doesn’t apply to the Modbus Adapter.

4.2.5.9. RTIGATEWAY_ENABLE_TRACE

Required: No
Default: OFF
Description: If enabled, this option will cause plugins to produce a much more verbose logging output, which can be used to trace all function calls within the adapter code.
Note: This doesn’t apply to the Modbus Adapter.

4.2.6. MQTT Adapter CMake Options

4.2.6.1. RTIGATEWAY_ENABLE_SSL

OpenSSL must be available on the system, if support for SSL/TLS is required.

Note

In case that this fails or do not find the correct version, you can provide CMake with the correct path by setting the variable -DOPENSSL_ROOT_DIR=<path_to_openssl>. This directory must contain header files in an include/ subdirectory, and libraries in a lib/ subdirectory. In Windows, there will be dll files in the bin/ subdirectory as well.

Required: No
Default: OFF
Description: When this option is enabled, SSL/TLS support will be compiled in Routing Service MQTT Adapter, and Paho C Client Async MQTT Library. OPENSSLHOME must also be specified to provide the required OpenSSL dependencies. You can specify OPENSSLHOME when calling CMake by adding -DOPENSSLHOME=/path/to/openssl.