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_DIRorNDDSHOMEenvironment 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
NDDSHOMEenvironment variable is not set.- Default:
None
- Description:
The installation location of RTI Connext DDS must be specified using this variable or
NDDSHOMEenvironment 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:
OFF- 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.4.7. RTIGATEWAY_ENABLE_SSL
- Required:
No
- Default:
OFF- Description:
- Required:
No
- Default:
OFF- Description:
Build plugins and dependencies with support for OpenSSL and other security features (e.g. Routing Service MQTT Adapter, and Paho C Client Async MQTT Library). OpenSSL must be available on the system, if support for SSL/TLS is required.
OPENSSLHOMEcan be used to specify the location of the required OpenSSL dependencies. You can specifyOPENSSLHOMEwhen calling CMake by adding-DOPENSSLHOME=/path/to/openssl.
Note
You can also specify with the path to the OpenSSL installation by setting CMake variable
OPENSSL_ROOT_DIR. 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.
4.2.4.8. RTIGATEWAY_ENABLE_LOG
- Required:
No
- Default:
OFF(forRelease),ON(forDebug)- Description:
By default, plugins will not print any messages to standard output when built in
Releasemode. When built inDebugmode, or ifRTIGATEWAY_ENABLE_LOGis 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.4.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.4.10. RTIGATEWAY_ENABLE_PROTOBUF_BUILD
- Required:
No
- Default:
OFF- Description:
Build the included Protocol Buffers submodule, instead of relying on a system-wide installation.
4.2.5. CMake Plugin Selection 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_PROTOBUF
- Required:
No
- Default:
ON- Description:
If this variable is enabled, the Protocol Buffers transformation and all of its components (tests, examples, docs…) will be enabled, unless they have been explicitly disabled using the dedicated variables.
Warning
The transformation requires the Protocol Buffers compiler (protoc), and
libraries to be installed on the system. If these dependencies are not
available, the build process will emit a warning and skip the transformation.
It is also possible to provision these dependencies by enabling the
RTIGATEWAY_ENABLE_PROTOBUF_BUILD CMake option, which will build the
Protocol Buffers version included as a submodule of this repository.
4.2.5.8. 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.