.. _installation: 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. .. _installation_minimum_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 :ref:`platform_support_portability` section. .. include:: ../safety_manual/rules/RULE_PLATFORMS_ALLOWED.inc .. _installation_build: 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: .. literalinclude:: ../code/build_documentation_code.sh :language: bash :start-after: # INSTALLATION_CMAKE_COMMAND :end-before: #! INSTALLATION_CMAKE_COMMAND 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. .. _installation_crosscompile: 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: .. literalinclude:: ../code/cortex_m3_crosscompilation/toolchain.cmake :language: cmake :start-after: # CROSSCOMPILATION_TOOLCHAIN_CMAKE_EXAMPLE :end-before: #! CROSSCOMPILATION_TOOLCHAIN_CMAKE_EXAMPLE 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: .. literalinclude:: ../code/build_documentation_code.sh :language: bash :dedent: 4 :start-after: # INSTALLATION_CROSSCOMPILATION_TOOLCHAIN_CMAKE_COMMAND :end-before: #! INSTALLATION_CROSSCOMPILATION_TOOLCHAIN_CMAKE_COMMAND .. _installation_override_cpp_standard_library: Override C++ Standard Library ----------------------------- As mentioned in the :ref:`architecture_portable` 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: .. literalinclude:: ../code/cortex_m3_crosscompilation/toolchain.cmake :language: cmake :start-after: # OVERRIDE_STL_TOOLCHAIN_CMAKE_EXAMPLE :end-before: #! OVERRIDE_STL_TOOLCHAIN_CMAKE_EXAMPLE 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. .. _installation_cmake_options: 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: .. list-table:: :header-rows: 1 * - 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 - ```` - ``"-fno-exceptions -fno-rtti -Wall -Werror -Wextra -Wpedantic -Wsuggest-override"`` * - ``SAFEDDS_COMPILE_OPTIONS_PRIVATE`` - Adds custom private compile options - ```` - ``"-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 -------------------------- .. _installation_qnx: QNX ^^^ Installation ~~~~~~~~~~~~ Safe DDS can be built for QNX platforms listed in :ref:`supported_platforms`. To build Safe DDS and its test suite for QNX, it is first required to build Google Test for QNX: .. literalinclude:: ../../../resources/ci_runners/qnx_runner/build_googletest.sh :language: bash :start-after: # BUILD_QNX_GOOGLETEST :end-before: #! BUILD_QNX_GOOGLETEST Once Google Test is built and installed in the required location, Safe DDS and its whole test suite can be built for QNX: .. literalinclude:: ../../../resources/ci_runners/qnx_runner/build_safedds.sh :language: bash :start-after: # BUILD_QNX_SAFEDDS :end-before: #! BUILD_QNX_SAFEDDS For reference a basic toolchain for building the library targeting the QNX platform can be found below: .. literalinclude:: ../../../resources/ci_runners/qnx_runner/toolchain.cmake :language: cmake :start-after: # BUILD_QNX_SAFEDDS_TOOLCHAIN :end-before: #! BUILD_QNX_SAFEDDS_TOOLCHAIN 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: .. literalinclude:: ../../../resources/ci_runners/qnx_runner/run_safedds_tests.sh :language: bash :start-after: # RUN_QNX_SAFEDDS_TESTS :end-before: #! RUN_QNX_SAFEDDS_TESTS