Build Configuration¶
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)
# Set the Safe DDS datasharing to none
set(SAFEDDS_DATASHARING "none" CACHE STRING "")
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 |
|---|---|---|---|
|
Builds unit tests suite |
|
|
|
Builds module tests suite |
|
|
|
Builds system tests suite |
|
|
|
Builds examples |
|
|
|
Builds tests with coverage support |
|
|
|
Builds tests with address sanitizer support |
|
|
|
Adds custom compile options |
|
|
|
Adds custom private compile options |
|
|
|
Sets the target platform |
|
|
|
Sets the target platform from a custom directory. Takes precedence over |
|
|
|
Sets the transport to use |
|
|
|
Sets the transport from a custom directory. Takes precedence over |
|
|
|
Sets the data sharing backend to use |
|
|
|
Sets the data sharing backend from a custom directory. Takes precedence over |
|
|
By default, Safe DDS is built with the posix/udpv4_sharedmemory transport, which creates the built-in transport::posix::UDPv4_SharedMemory transport and combines UDPv4 and POSIX shared memory communication in a single transport::ITransport implementation.
Data sharing support is configured independently through SAFEDDS_DATASHARING, which currently defaults to the built-in posix/fifo backend.
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