Installation

The core of Eclipse Cyclone DDS is implemented in C and provides C-APIs to applications. Additional language bindings are:

Supported platforms

The Cyclone DDS supports three primary platforms:

  • Linux

  • macOS

  • Windows

Code examples are provided for each of these platforms throughout the Cyclone DDS documentation. For example:

Linux-specific information

Other platforms where Cyclone DDS is supported (with some caveats):

  • FreeRTOS

  • QNX

  • Openindiana OS, which is similar to Solaris

Note

Cyclone DDS has not been extensively tested on these other platforms and therefore there may be unexpected results.

Prerequisites

Install the following software on your machine:

  • A C compiler (For example, GCC or Clang on Linux, Visual Studio on Windows (MSVC), Clang on macOS).

  • Git version control system.

  • CMake, version 3.10 or later, see CMake build configuration.

  • Optionally, OpenSSL, preferably version 1.1 later to use TLS over TCP.

To obtain the dependencies for Cyclone DDS, follow the platform-specific instructions:

To install the dependencies, use a package manager. For example:

    yum install git cmake gcc
    apt-get install git cmake gcc
    aptitude install git cmake gcc
    # or others

Additional tools

While developing for Eclipse Cyclone DDS, additional tools and dependencies may be required. The following is a list of the suggested tools:

Language-specific installation

Obtain Cyclone DDS via Git from the repository hosted on GitHub:

git clone https://github.com/eclipse-cyclonedds/cyclonedds.git
cd cyclonedds

Building Cyclone DDS

To build and install the required libraries for your applications, use the following:

cd build
cmake -DCMAKE_INSTALL_PREFIX=<install-location> -DBUILD_EXAMPLES=ON ..
cmake --build . --parallel

If you need to reduce the footprint, or have issues with the FindOpenSSL.cmake script, you can explicitly disable it by setting -DENABLE\_SSL=NO to the CMake invocation. For further information, refer to FindOpenSSL.

If you do not require the examples, use -DBUILD_EXAMPLES=OFF to omit them.

To install Cyclone DDS after a successful build:

cmake --build . --target install

The install step copies everything to:

  • <install-location>/lib

  • <install-location>/bin

  • <install-location>/include/ddsc

  • <install-location>/share/CycloneDDS

Note

Depending on the installation location, you may need administrator privileges.

At this point, you are ready to use var-project-short| in your projects.

Note

Build types

The default build type is a release build that includes debugging information (RelWithDebInfo). This build is suitable for applications because it allows the resulting application to be more easily debugged while still maintaining high performance. If you prefer a Debug or pure Release build, add -DCMAKE_BUILD_TYPE=<build-type> to your CMake invocation.

Windows environment variables

To run Cyclone DDS executables on Windows, the required libraries (ddsc.dll and so on) must be available to the executables. Typically, these libraries are installed in system default locations and work out of the box. However, if they are not installed in those locations, you must change the library search path, either:

  • Execute the following command:

set PATH=<install-location>\bin;%PATH%

  • Set the path from the “Environment variables” Windows menu.

Note

An alternative to make the required libraries available to the executables are to copy the necessary libraries for the executables’ directory. This is not recommended.

Test your installation

To test if your installation and configuration are working correctly, either:

  • Use the Cyclone DDS The ddsperf tool

    The ddsperf tool sends a continuous stream of data at a variable frequency. This is useful for sanity checks and to bypass other sporadic network issues.

  • Use the HelloWorld example.

    The Hello World! example sends a single message.

The ddsperf tool

The ddsperf tool is pre-installed within <installation-dir>/bin.

Note

The Python tooling uses ddsperf to provide the cyclonedds performance subcommand and acts as a front-end for ddsperf.

The following test ensures that the the loopback option is enabled.

To complete the sanity checks of your DDS-based system:

  1. Open two terminals.

  2. In the first terminal, run the following command:

ddsperf sanity

The sanity option sends one data sample each second (1Hz).

3. In the second terminal, start ddsperf in Pong mode to echo the data to the first instance of the ddsperf (started with the Sanity option).

ddsperf pong
../_images/4.2-1.png

If the data is not exchanged on the network between the two ddsperf instances, it is probable that Eclipse Cyclone DDS has not selected the the appropriate network card on both machines, or a firewall in-between is preventing communication.

Eclipse Cyclone DDS automatically selects the most available network interface. This behavior can be overridden by changing the configuration file.

HelloWorld

To test your installation, Eclipse Cyclone DDS includes a simple HelloWorld! application (see also the HelloWorld example). HelloWorld! consists of two executables:

  • HelloworldPublisher

  • HelloworldSubscriber

The HelloWorld! executables are located in:

  • <cyclonedds-directory>\build\bin\Debug on Windows

  • <cyclonedds-directory>/build/bin on Linux/macOS.

Note

Requires CMake with -DBUILD_EXAMPLES=ON.

  1. Open two terminals inside the directory with the HelloWorld files.

  2. In the first terminal, start the subscriber by running HelloWorldSubscriber.

    ./HelloworldSubscriber

  3. In the second terminal, start the publisher by running HelloWorldPublisher.

    ./HelloworldPublisher

HelloworldPublisher appears as follows:

../_images/helloworld_publisher.png

HelloworldSubscriber appears as follows:

../_images/helloworld_subscriber.png

Note

There are some common issues with multiple network interface cards on machine configurations. The default behavior automatically detects the first available network interface card on your machine for exchanging the hello world message. To ensure that your publisher and subscriber applications are on the same network, you must select the correct interface card. To override the default behavior, create or edit a deployment file (for example, cyclonedds.xml) and update the property //CycloneDDS/Domain/General/Interfaces/NetworkInterface[@address] to point to it through the CYCLONEDDS\_URI OS environment variable. For further information, refer to Configuration guide and the Configuration File Reference.

Uninstalling Cyclone DDS

To uninstall Cyclone DDS, manually remove the install and build directories:

rm -rf cyclonedds
rm -rf <install-location>