Installation

As previously mentioned throughout this documentation, Safe DDS is a C++ library characterized by its strong emphasis on portability. It is important to highlight that Safe DDS has no external dependencies, which significantly simplifies the integration process. Additionally, the library has minimal system requirements, making it suitable for a wide variety of environments.

The installation method described in the following sections targets systems that meet the aforementioned requirements. However, it should be noted that there are alternative possibilities for porting the library to other types of platforms and toolchains, enabling Safe DDS to adapt to various scenarios and meet diverse platform requirements.

Minimum Requirements

In order to successfully build Safe DDS, there are certain minimum requirements that must be fulfilled. These requirements include:

• CMake 3.5 or higher, although it should be noted that the build process is not limited to this particular build system and can be accomplished with other alternatives.

• A C++11 compliant compiler, ensuring compatibility with the necessary features and standards.

• A subset of the C++ standard library, providing essential functionalities for the library’s operation.

Note

It is possible to port Safe DDS to platforms that do not satisfy these requirements; however, the process for doing so falls beyond the scope of this document. For more details please check Portability section.

Build and install the library

Note

To obtain a copy of Safe DDS please contact support@eProsima.com

In order to build and install Safe DDS, the standard CMake procedure is employed, as detailed below:

cmake "$SAFEDDS_PATH" \
    -B"$BUILD_SAFEDDS_FOLDER" \
    -DCMAKE_INSTALL_PREFIX="$INSTALL_SAFEDDS_FOLDER"
cmake --build "$BUILD_SAFEDDS_FOLDER" --target install

Upon completion of the installation process, a libsafedds.a file and an include directory can be located within the specified installation directory. This enables users to seamlessly integrate Safe DDS into their projects by linking the library and including the necessary header files.

Cross-compiling Safe DDS

To cross-compile Safe DDS, the utilization of the standard CMake toolchain method is recommended.

Below a sample of a basic toolchain for building the library targeting the Cortex-M3 architecture can be found:

# Example Safe DDS CMake Toolchain file for Cortex-M3
set(CMAKE_SYSTEM_NAME Generic)
set(CMAKE_SYSTEM_PROCESSOR arm)

# Set the toolchain path
set(CMAKE_C_COMPILER arm-none-eabi-gcc)
set(CMAKE_CXX_COMPILER arm-none-eabi-g++)

# Set the common ARM Cortex M3 flags
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -mcpu=cortex-m3 -mthumb")
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -mcpu=cortex-m3 -mthumb")

# Ensure that the compiler works
set(CMAKE_C_COMPILER_WORKS 1)
set(CMAKE_CXX_COMPILER_WORKS 1)

# Set the Safe DDS platform and transport to none
set(SAFEDDS_PLATFORM "none" CACHE STRING "Force no platform" FORCE)
set(SAFEDDS_TRANSPORT "none" CACHE STRING "Force no transport" FORCE)

This example provides a starting point for configuring the toolchain settings to cross-compile Safe DDS for the Cortex-M3 platform. Mind that adjusting the toolchain settings according to the specific platform and requirements may be required.

Once the toolchain file is ready, the library can be cross-compiled by invoking CMake as follows:

cmake "$SAFEDDS_PATH" \
    -Bbuild \
    -DCMAKE_TOOLCHAIN_FILE="$TOOLCHAIN_FILE" \
    -DCMAKE_INSTALL_PREFIX="$SAFEDDS_INSTALL_FOLDER"
cmake --build build --target install

Override C++ Standard Library

As mentioned in the Portable module section, Safe DDS’ dependency on the C++ standard library is both limited and encapsulated. To facilitate customization, it is possible to override the contents of the include/portable folder, allowing for modifications or replacements of any headers found within this directory. This enables the utilization of a custom C++ standard library or a tailored implementation to suit specific requirements.

To illustrate this process, consider the example of overriding the usage of the builtin __builtin_clz() in the default implementation of portable::clz(). This can be accomplished by rewriting the file include/portable/CLZ.hpp as include_overrides/safedds/portable/CLZ.hpp and subsequently incorporating it into the toolchain as follows:

# Add the custom include folder to override library headers
include_directories(${CMAKE_CURRENT_SOURCE_DIR}/include_overrides)

By employing this method, it is possible to adapt Safe DDS to utilize alternative C++ standard libraries or bespoken implementations as needed, offering flexibility and versatility for varying project requirements.

CMake options

Safe DDS incorporates a variety of CMake options, which serve to enhance the customization of the build process. The following options are available:

Option	Description	Possible values	Default
SAFEDDS_BUILD_UT_TESTS	Builds unit tests suite	ON OFF	OFF
SAFEDDS_BUILD_MOD_TESTS	Builds module tests suite	ON OFF	OFF
SAFEDDS_BUILD_SYSTEM_TESTS	Builds system tests suite	ON OFF	OFF
SAFEDDS_BUILD_EXAMPLES	Builds examples	ON OFF	OFF
SAFEDDS_BUILD_TESTS_COVERAGE	Builds tests with coverage support	ON OFF	OFF
SAFEDDS_BUILD_TESTS_ASAN	Builds tests with address sanitizer support	ON OFF	OFF
SAFEDDS_COMPILE_OPTIONS	Adds custom compile options	<string>	"-fno-exceptions -fno-rtti -Wall -Werror -Wextra -Wpedantic -Wsuggest-override"
SAFEDDS_COMPILE_OPTIONS_PRIVATE	Adds custom private compile options	<string>	"-Wcast-align -Wunused -Wconversion -Wshadow -Wsign-conversion -Wdouble-promotion -Woverloaded-virtual -Wold-style-cast -Wlogical-op -Wduplicated-cond -Wduplicated-branches -Wrestrict"
SAFEDDS_PLATFORM	Sets the target platform	posix, freertos, none	posix
SAFEDDS_TRANSPORT	Sets the transport to use	posix/udpv4, freertos_plus_tcp/udpv4, none	posix/udpv4

Safety Certified Platforms

QNX

Installation

Safe DDS can be built for QNX platforms listed in Supported platforms.

To build Safe DDS and its test suite for QNX, it is first required to build Google Test for QNX:

# Clone googletest
git clone -b release-1.11.0 https://github.com/google/googletest "$GOOGLETEST_SRC_PATH"

# Define toolchain flag if required
if [ "$SAFEDDS_CROSSCOMPILING" = "ON" ]; then
    SAFEDDS_CROSSCOMPILING_OPTIONS="-DCMAKE_TOOLCHAIN_FILE=$TOOLCHAIN_FILE"
else
    SAFEDDS_CROSSCOMPILING_OPTIONS=""
fi

# Build googletest
rm -rf "$GOOGLETEST_SRC_PATH"_build
mkdir "$GOOGLETEST_SRC_PATH"_build
pushd "$GOOGLETEST_SRC_PATH"_build || exit
    cmake "$GOOGLETEST_SRC_PATH" "$SAFEDDS_CROSSCOMPILING_OPTIONS" -DCMAKE_INSTALL_PREFIX="$GOOGLETEST_INSTALL_PATH"
    make -j1 && make install
popd || exit

# Remove googletest source code and build folder
rm -rf "$GOOGLETEST_SRC_PATH"_build "$GOOGLETEST_SRC_PATH"

Once Google Test is built and installed in the required location, Safe DDS and its whole test suite can be built for QNX:

# Define toolchain flag if required
if [ "$SAFEDDS_CROSSCOMPILING" = "ON" ]; then
    SAFEDDS_CROSSCOMPILING_OPTIONS="-DCMAKE_TOOLCHAIN_FILE=$TOOLCHAIN_FILE"
else
    SAFEDDS_CROSSCOMPILING_OPTIONS=""
fi

# Build Safe DDS
mkdir "$SAFEDDS_BUILD_PATH"
pushd "$SAFEDDS_BUILD_PATH" || exit
    cmake "$SAFEDDS_SRC_PATH" "$SAFEDDS_CROSSCOMPILING_OPTIONS" -DCMAKE_PREFIX_PATH="$GOOGLETEST_INSTALL_PATH" -DSAFEDDS_BUILD_UT_TESTS=ON -DSAFEDDS_BUILD_MOD_TESTS=ON -DSAFEDDS_BUILD_SYSTEM_TESTS=ON -DSAFEDDS_BUILD_TOOL_QUALIFICATION_TESTS=ON
    make -j"$(nproc)"
popd || exit

For reference a basic toolchain for building the library targeting the QNX platform can be found below:

# Safe DDS CMake Toolchain file

# Set the target system name
set(CMAKE_SYSTEM_NAME QNX)

# Set compiler paths
set(CMAKE_C_COMPILER   $ENV{QNX_HOST}/usr/bin/qcc)
set(CMAKE_CXX_COMPILER $ENV{QNX_HOST}/usr/bin/q++)
set(CMAKE_LINKER       $ENV{QNX_HOST}/usr/bin/q++)

# Add libraries
# Linkage against regex is required for GTest
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -l regex -l socket -l c")

# Add compiler options
add_compile_options("-Vgcc_ntox86_64_cxx")

# Add definitions
add_compile_definitions(_QNX_SOURCE)

# Set C++ standard
set(CMAKE_CXX_STANDARD 14)

Test Execution

Once Safe DDS and its test suite are built, a set of executables are generated in the build directory. Those executables contain the test suite for each module of Safe DDS.

Executing this test suite may imply copying the executables to the target platform and executing them there.

It is also possible to run them using QEMU and QNX provided tools. For this purpose, the following procedure can be taken as reference:

set -e

source "$SAFEDDS_SRC_PATH/resources/ci_runners/qnx_runner/qnx_safe_dds_common.sh"

mkdir "$VM_FOLDER"
pushd "$VM_FOLDER" || exit

    # Create QNX VM
    __run_qnx_machine

    # Run unit tests
    __run_command_on_target "export LD_LIBRARY_PATH=\$(pwd)/build && find build/test/unit_test -type file -name safeddstest_* | while read C
        do
        set -e
        \$C
        done"

    # Run module tests
    __run_command_on_target "export LD_LIBRARY_PATH=\$(pwd)/build && find build/test/module_test -type file -name safeddstest_mod_* | while read C
        do
        set -e
        \$C
        done"

    # Run system tests
    __run_command_on_target "export LD_LIBRARY_PATH=\$(pwd)/build && find build/test/system_test -type file -name safeddstest_sys_* | while read C
        do
        set -e
        \$C
        done"

    # Tool qualification tests
    __run_qualification_tests

    # Stop QNX VM
    __stop_qnx_machine

popd || exit