diff --git a/ddsenabler_docs/README.md b/ddsenabler_docs/README.md index 9563e624..cdd14ef1 100644 --- a/ddsenabler_docs/README.md +++ b/ddsenabler_docs/README.md @@ -22,7 +22,7 @@ sudo apt install -y \ python3-venv \ python3-sphinxcontrib.spelling \ imagemagick -pip3 install -U -r src/ddsenabler/docs/requirements.txt +pip3 install -U -r src/ddsenabler_docs/docs/requirements.txt ``` ### Build documentation diff --git a/ddsenabler_docs/docs/02-formalia/titlepage.rst b/ddsenabler_docs/docs/02-formalia/titlepage.rst index 2feb03c5..f1e97505 100644 --- a/ddsenabler_docs/docs/02-formalia/titlepage.rst +++ b/ddsenabler_docs/docs/02-formalia/titlepage.rst @@ -9,16 +9,8 @@ What is DDS Enabler? :alt: eProsima :target: http://www.eprosima.com/ - -**eProsima DDS Enabler** serves as a single point of entry for DDS communication, managing all necessary participants -and seamlessly routing data between a DDS network and FIWARE Context Brokers. It enables both publishing DDS samples -into NGSI-LD entities and injecting context-broker updates back into DDS topics, providing real-time, bidirectional -interoperability. - -Built on top of **eProsima Fast DDS**, DDS Enabler leverages the OMG DDS-XTypes standard for dynamic type discovery and -serialization. Its modular architecture and YAML-based configuration make it ideal for industrial scenarios requiring -low-latency, high-throughput data exchange, including human-robot interaction and OT/IT convergence under the ARISE -project. +**eProsima DDS Enabler** is a modular middleware framework that connects DDS networks with an external system or data platform, delivering real-time, bidirectional interoperability. +It orchestrates all necessary DDS participants, auto-discovers topics and types, and flexibly translates DDS samples into your target data model — and routes incoming context updates or events back into DDS topics. .. raw:: html @@ -31,38 +23,25 @@ Looking for commercial support? Write us at info@eprosima.com. Find more about us at `eProsima's webpage `_. -Overview -^^^^^^^^ - -*DDS Enabler* is one of the technical cornerstones in the ARISE project's vision for an all-in-one middleware -enabling **real-time industrial human-robot interaction**. Designed to unify **Operational Technologies (OT)** and -**Information Technologies (IT)**, it is a modular and open solution that integrates natively with **Fast DDS** and -**NGSI-LD**. - -Key characteristics include: - -- **Real-time publish-subscribe middleware**: Built on the DDS standard, enabling low-latency and reliable communication. -- **Seamless OT/IT integration**: Acts as a translator between DDS-based systems and NGSI-LD context brokers. -- **ROS 2 and FIWARE compatibility**: Enables industrial robots and context-aware applications to operate through the same infrastructure. -- **Scalable and extensible architecture**: Fully compatible with modern Industry 5.0 deployments, providing flexibility for growth and adaptation. - -Under the hood, DDS Enabler also provides: - -- **Transparent DDS Management.** - Auto-create and discover DomainParticipants, Publishers, Subscribers, topics and types without manual code. -- **Flexible YAML Configuration.** - Fine-tune QoS, network filters and discovery through a human-readable YAML file. -- **Dynamic Types via XTypes.** - Leverage `OMG DDS-XTypes 1.3 `_ and Fast DDS serialization utilities for - on-the-fly type registration. -- **Core Engine Powered by DDS-Pipe.** - Built on `eProsima DDS Pipe `_, ensuring high throughput and reliable - participant discovery. -- **Serialization Utilities.** +Key features +^^^^^^^^^^^^ + +- **Unified DDS Participant Management** + Auto-create and discover DomainParticipants, Publishers, Subscribers, Topics and Types without manual code. +- **Flexible YAML Configuration** + Fine-tune QoS, network filters, topic allow-listing/deny-listing and discovery via a human-readable YAML file. +- **Dynamic Types via XTypes** + Leverage [OMG DDS-XTypes 1.3](https://www.omg.org/spec/DDS-XTypes/1.3) and Fast DDS serialization utilities for runtime type registration and discovery. +- **Core Engine Powered by DDS-Pipe** + Built on [eProsima DDS Pipe](https://github.com/eProsima/DDS-Pipe), ensuring low-latency, high-throughput payload forwarding and reliable discovery across distributed systems. +- **Serialization Utilities** Convert DDS data to JSON and vice versa for REST integration and to human-readable IDL. -DDS Enabler is a flagship component of the ARISE project: -`ARISE Middleware `_. +Platforms using DDS Enabler +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- **FIWARE NGSI-LD Context Broker** + Developed in collaboration with the FIWARE Context Broker team, *eProsima DDS Enabler* routes DDS samples into the broker (via broker-side implementation) and propagates Context Broker's context updates back into DDS topics. + DDS Enabler is a flagship component of the ARISE project: `ARISE Middleware `_. Structure of the documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -70,4 +49,5 @@ Structure of the documentation This documentation is organized into the following main sections: * :ref:`Introduction ` +* :ref:`Installation ` * :ref:`API Reference ` diff --git a/ddsenabler_docs/docs/ddsenabler/api_reference/api_reference.rst b/ddsenabler_docs/docs/ddsenabler/api_reference/api_reference.rst index 1a2cfdc4..1f991434 100644 --- a/ddsenabler_docs/docs/ddsenabler/api_reference/api_reference.rst +++ b/ddsenabler_docs/docs/ddsenabler/api_reference/api_reference.rst @@ -19,4 +19,4 @@ The following pages document the classes, functions, and types exposed by *DDS E /ddsenabler/api_reference/dds_enabler/dds_enabler /ddsenabler/api_reference/callback_set/callback_set /ddsenabler/api_reference/dds_callbacks/dds_callbacks - /ddsenabler/api_reference/dds_callbacks/cb_callbacks + /ddsenabler/api_reference/dds_callbacks/callbacks diff --git a/ddsenabler_docs/docs/ddsenabler/installation/cmake_options.rst b/ddsenabler_docs/docs/ddsenabler/installation/cmake_options.rst new file mode 100644 index 00000000..86c35079 --- /dev/null +++ b/ddsenabler_docs/docs/ddsenabler/installation/cmake_options.rst @@ -0,0 +1,61 @@ +.. include:: ../../03-exports/alias.include +.. include:: ../../03-exports/roles.include + + +.. _cmake_options: + +############# +CMake options +############# + +*eProsima DDS Enabler* provides numerous CMake options for changing the behavior and configuration of *eProsima DDS Enabler*. +These options allow the developer to enable/disable certain *eProsima DDS Enabler* settings by defining these options to ``ON``/``OFF`` at the CMake execution, or set the required path to certain dependencies. + +.. warning:: + These options are only for developers who installed *eProsima DDS Enabler* following the compilation steps described in :ref:`installation_sources_linux`. + +.. list-table:: + :header-rows: 1 + + * - Option + - Description + - Possible values + - Default + * - :class:`CMAKE_BUILD_TYPE` + - CMake optimization build type. + - ``Release`` |br| + ``Debug`` + - ``Release`` + * - :class:`BUILD_DOCS` + - Build the *eProsima DDS Enabler* |br| documentation. |br| + - ``OFF`` |br| + ``ON`` + - ``OFF`` + * - :class:`BUILD_TESTS` + - Build the *eProsima DDS Enabler* tools and |br| documentation tests. + - ``OFF`` |br| + ``ON`` + - ``OFF`` + * - :class:`COMPILE_EXAMPLES` + - Build the *eProsima DDS Enabler* examples. + - ``OFF`` |br| + ``ON`` + - ``OFF`` + * - :class:`LOG_INFO` + - Activate *eProsima DDS Enabler* logs. It is |br| + set to ``ON`` if :class:`CMAKE_BUILD_TYPE` is set |br| + to ``Debug``. + - ``OFF`` |br| + ``ON`` + - ``ON`` if ``Debug`` |br| + ``OFF`` otherwise + * - :class:`ASAN_BUILD` + - Activate address sanitizer build. + - ``OFF`` |br| + ``ON`` + - ``OFF`` + * - :class:`TSAN_BUILD` + - Activate thread sanitizer build. + - ``OFF`` |br| + ``ON`` + - ``OFF`` diff --git a/ddsenabler_docs/docs/ddsenabler/installation/linux.rst b/ddsenabler_docs/docs/ddsenabler/installation/linux.rst new file mode 100644 index 00000000..9f4c4ef1 --- /dev/null +++ b/ddsenabler_docs/docs/ddsenabler/installation/linux.rst @@ -0,0 +1,307 @@ +.. _installation_sources_linux: + +############################### +Linux installation from sources +############################### + +The instructions for installing the *eProsima DDS Enabler* from sources and its required dependencies are provided in this page. + + +Dependencies installation +========================= + +*eProsima DDS Enabler* depends on *eProsima Fast DDS* library and certain Debian packages. +This section describes the instructions for installing *eProsima DDS Enabler* dependencies and requirements in a Linux environment from sources. +The following packages will be installed: + +- ``foonathan_memory_vendor``, an STL compatible C++ memory allocation library. +- ``fastcdr``, a C++ library that serializes according to the standard CDR serialization mechanism. +- ``fastdds``, the core library of eProsima Fast DDS library. +- ``cmake_utils``, an eProsima utils library for CMake. +- ``cpp_utils``, an eProsima utils library for C++. +- ``ddspipe``, an eProsima internal library that enables the communication of DDS interfaces. + +First of all, the :ref:`Requirements ` and :ref:`Dependencies ` detailed below need to be met. +Afterwards, the user can choose whether to follow either the :ref:`colcon ` or the +:ref:`CMake ` installation instructions. + +.. _requirements: + +Requirements +------------ + +The installation of *eProsima DDS Enabler* in a Linux environment from sources requires the following tools to be installed in the system: + +* CMake, g++, pip, wget and git +* Colcon [optional, for colcon installation only] + +.. code-block:: bash + + sudo apt install cmake g++ pip wget git + pip3 install -U colcon-common-extensions vcstool # optional, for colcon installation only + +.. _dependencies: + +Dependencies +------------ + +*eProsima DDS Enabler* has the following dependencies, when installed from sources in a Linux environment: + +* Asio and TinyXML2 libraries +* OpenSSL library +* YAML-CPP library + +.. code-block:: bash + + sudo apt install libasio-dev libtinyxml2-dev libssl-dev libyaml-cpp-dev + +.. _eprosima_dependencies: + +eProsima dependencies +^^^^^^^^^^^^^^^^^^^^^ + +If it already exists in the system an installation of *Fast DDS* and *DDS Pipe* libraries, just source these libraries when building *eProsima DDS Enabler* by running the following commands. +In other case, just skip this step. + +.. code-block:: bash + + source /install/setup.bash + source /install/setup.bash + +.. _gtest_sl: + +Gtest +^^^^^ + +Gtest_ is a unit testing library for C++. +By default, *eProsima DDS Enabler* does not compile tests. +It is possible to activate them with the opportune `CMake options `_ when calling colcon_ or CMake_. +For more details, please refer to the :ref:`cmake_options` section. +For a detailed description of the Gtest_ installation process, please refer to the `Gtest Installation Guide `_. + +It is also possible to clone the Gtest_ Github repository into the *eProsima DDS Enabler* workspace and compile it with colcon_ as a dependency package. +Use the following command to download the code: + +.. code-block:: bash + + git clone --branch release-1.12.0 https://github.com/google/googletest src/googletest-distribution + + + +.. _colcon_installation: + +Colcon installation (recommended) +================================= + +#. Create a :code:`DDS-Enabler` directory and download the :code:`.repos` file that will be used to install *eProsima DDS Enabler* and its dependencies: + + .. code-block:: bash + + mkdir -p ~/DDS-Enabler/src + cd ~/DDS-Enabler + wget https://raw.githubusercontent.com/eProsima/DDS-Enabler/main/ddsenabler.repos + vcs import src < ddsenabler.repos + + .. note:: + + In case there is already a *Fast DDS* installation in the system it is not required to download and build every dependency in the :code:`.repos` file. + It is just needed to download and build the *eProsima DDS Enabler* project having sourced its dependencies. + Refer to section :ref:`eprosima_dependencies` in order to check how to source *Fast DDS* library. + +#. Build the packages: + + .. code-block:: bash + + colcon build + +.. note:: + + Being based on CMake_, it is possible to pass the CMake configuration options to the :code:`colcon build` command. + For more information on the specific syntax, please refer to the `CMake specific arguments `_ page of the colcon_ manual. + + +.. _cmake_installation: + +CMake installation +================== + +This section explains how to compile *eProsima DDS Enabler* with CMake_, either :ref:`locally ` or :ref:`globally `. + +.. note:: + + This section is not required if you have already installed the *eProsima DDS Enabler* using Colcon. + +.. _local_installation_sl: + +Local installation +------------------ + +#. Create a :code:`DDS-Enabler` directory where to download and build *eProsima DDS Enabler* and its dependencies: + + .. code-block:: bash + + mkdir -p ~/DDS-Enabler/src + mkdir -p ~/DDS-Enabler/build + cd ~/DDS-Enabler + wget https://raw.githubusercontent.com/eProsima/DDS-Enabler/main/ddsenabler.repos + vcs import src < ddsenabler.repos + +#. Compile all dependencies using CMake_. + + * `Foonathan memory `_ + + .. code-block:: bash + + cd ~/DDS-Enabler + mkdir build/foonathan_memory_vendor + cd build/foonathan_memory_vendor + cmake ~/DDS-Enabler/src/foonathan_memory_vendor -DCMAKE_INSTALL_PREFIX=~/DDS-Enabler/install -DBUILD_SHARED_LIBS=ON + cmake --build . --target install + + * `Fast CDR `_ + + .. code-block:: bash + + cd ~/DDS-Enabler + mkdir build/fastcdr + cd build/fastcdr + cmake ~/DDS-Enabler/src/fastcdr -DCMAKE_INSTALL_PREFIX=~/DDS-Enabler/install + cmake --build . --target install + + * `Fast DDS `_ + + .. code-block:: bash + + cd ~/DDS-Enabler + mkdir build/fastdds + cd build/fastdds + cmake ~/DDS-Enabler/src/fastdds -DCMAKE_INSTALL_PREFIX=~/DDS-Enabler/install -DCMAKE_PREFIX_PATH=~/DDS-Enabler/install + cmake --build . --target install + + * `Dev Utils `_ + + .. code-block:: bash + + # CMake Utils + cd ~/DDS-Enabler + mkdir build/cmake_utils + cd build/cmake_utils + cmake ~/DDS-Enabler/src/dev-utils/cmake_utils -DCMAKE_INSTALL_PREFIX=~/DDS-Enabler/install -DCMAKE_PREFIX_PATH=~/DDS-Enabler/install + cmake --build . --target install + + # C++ Utils + cd ~/DDS-Enabler + mkdir build/cpp_utils + cd build/cpp_utils + cmake ~/DDS-Enabler/src/dev-utils/cpp_utils -DCMAKE_INSTALL_PREFIX=~/DDS-Enabler/install -DCMAKE_PREFIX_PATH=~/DDS-Enabler/install + cmake --build . --target install + + * `DDS Pipe `_ + + .. code-block:: bash + + # ddspipe_core + cd ~/DDS-Enabler + mkdir build/ddspipe_core + cd build/ddspipe_core + cmake ~/DDS-Enabler/src/ddspipe/ddspipe_core -DCMAKE_INSTALL_PREFIX=~/DDS-Enabler/install -DCMAKE_PREFIX_PATH=~/DDS-Enabler/install + cmake --build . --target install + + # ddspipe_participants + cd ~/DDS-Enabler + mkdir build/ddspipe_participants + cd build/ddspipe_participants + cmake ~/DDS-Enabler/src/ddspipe/ddspipe_participants -DCMAKE_INSTALL_PREFIX=~/DDS-Enabler/install -DCMAKE_PREFIX_PATH=~/DDS-Enabler/install + cmake --build . --target install + + # ddspipe_yaml + cd ~/DDS-Enabler + mkdir build/ddspipe_yaml + cd build/ddspipe_yaml + cmake ~/DDS-Enabler/src/ddspipe/ddspipe_yaml -DCMAKE_INSTALL_PREFIX=~/DDS-Enabler/install -DCMAKE_PREFIX_PATH=~/DDS-Enabler/install + cmake --build . --target install + +#. Once all dependencies are installed, install *eProsima DDS Enabler*: + + .. code-block:: bash + + # dds_enabler_participants + cd ~/DDS-Enabler + mkdir build/dds_enabler_participants + cd build/dds_enabler_participants + cmake ~/DDS-Enabler/src/dds_enabler/dds_enabler_participants -DCMAKE_INSTALL_PREFIX=~/DDS-Enabler/install -DCMAKE_PREFIX_PATH=~/DDS-Enabler/install + cmake --build . --target install + + # dds_enabler_yaml + cd ~/DDS-Enabler + mkdir build/dds_enabler_yaml + cd build/dds_enabler_yaml + cmake ~/DDS-Enabler/src/dds_enabler/dds_enabler_yaml -DCMAKE_INSTALL_PREFIX=~/DDS-Enabler/install -DCMAKE_PREFIX_PATH=~/DDS-Enabler/install + cmake --build . --target install + + # dds_enabler + cd ~/DDS-Enabler + mkdir build/dds_enabler_tool + cd build/dds_enabler_tool + cmake ~/DDS-Enabler/src/dds_enabler/dds_enabler -DCMAKE_INSTALL_PREFIX=~/DDS-Enabler/install -DCMAKE_PREFIX_PATH=~/DDS-Enabler/install + cmake --build . --target install + + .. note:: + + By default, *eProsima DDS Enabler* does not compile tests. + However, they can be activated by downloading and installing `Gtest `_ + and building with CMake option ``-DBUILD_TESTS=ON``. + +.. _global_installation_sl: + +Global installation +------------------- + +To install *eProsima DDS Enabler* system-wide instead of locally, remove all the flags that appear in the configuration steps of :code:`Fast-CDR`, :code:`Fast-DDS`, :code:`Dev-Utils`, :code:`DDS-Pipe`, and :code:`DDS-Enabler`, and change the first in the configuration step of :code:`foonathan_memory_vendor` to the following: + +.. code-block:: bash + + -DCMAKE_INSTALL_PREFIX=/usr/local/ -DBUILD_SHARED_LIBS=ON + +.. _run_app_colcon_sl: + +Run an example +============== + +In this section, we will run a publish example mimicking the behavior of the classic *Hello World* ROS 2 talker in a specific domain. For simplicity, we will use the *eProsima DDS Enabler* example application +with the already provided configuration file and sample data from a test case in the *dds_enabler_test* package. + +To run this *eProsima DDS Enabler* example, source the installation path and execute the executable file that has been installed in :code:`/dds_enabler_tool/bin/dds_enabler`: + +.. code-block:: bash + + # TERMINAL ROS2 LISTENER + source /setup.bash + export ROS_DOMAIN_ID=33 + ros2 run demo_nodes_cpp listener + + # TERMINAL DDS ENABLER + # If built has been done using colcon, all projects could be sourced as follows + cd + source install/setup.bash + export TEST_PATH=$PWD/src/FIWARE-DDS-Enabler/ddsenabler_test/compose/test_cases/publish/discovered_type + ./build/ddsenabler/examples/ddsenabler_example --config $TEST_PATH/config.yml --timeout 5 --expected-types 1 --expected-topics 1 --publish-path $TEST_PATH/samples --publish-topic rt/chatter --publish-period 200 --publish-initial-wait 2000 + +.. important:: + + To run the *eProsima DDS Enabler* examples, it is necessary to have compiled the *eProsima DDS Enabler* project with the CMake option ``-DCOMPILE_EXAMPLES=ON``. For more details, please refer to the :ref:`cmake_options` section. + +.. note:: + + Be sure that the executable have execution permissions. + +.. External links + +.. _colcon: https://colcon.readthedocs.io/en/released/ +.. _CMake: https://cmake.org +.. _pip: https://pypi.org/project/pip/ +.. _wget: https://www.gnu.org/software/wget/ +.. _git: https://git-scm.com/ +.. _OpenSSL: https://www.openssl.org/ +.. _Gtest: https://github.com/google/googletest +.. _vcstool: https://pypi.org/project/vcstool/ diff --git a/ddsenabler_docs/docs/ddsenabler/installation/windows.rst b/ddsenabler_docs/docs/ddsenabler/installation/windows.rst new file mode 100644 index 00000000..ac79c2fe --- /dev/null +++ b/ddsenabler_docs/docs/ddsenabler/installation/windows.rst @@ -0,0 +1,393 @@ +.. _developer_manual_installation_sources_windows: + +################################# +Windows installation from sources +################################# + +The instructions for installing the *eProsima DDS Enabler* application from sources and its required dependencies are provided in this page. + +Dependencies installation +========================= + +*eProsima DDS Enabler* depends on *eProsima Fast DDS* library and certain Debian packages. +This section describes the instructions for installing *eProsima DDS Enabler* dependencies and requirements in a Windows environment from sources. +The following packages will be installed: + +- ``foonathan_memory_vendor``, an STL compatible C++ memory allocation library. +- ``fastcdr``, a C++ library that serializes according to the standard CDR serialization mechanism. +- ``fastdds``, the core library of eProsima Fast DDS library. +- ``cmake_utils``, an eProsima utils library for CMake. +- ``cpp_utils``, an eProsima utils library for C++. +- ``ddspipe``, an eProsima internal library that enables the communication of DDS interfaces. + +First of all, the :ref:`Requirements ` and :ref:`Dependencies ` detailed below need to be met. +Afterwards, the user can choose whether to follow either the :ref:`colcon ` or the :ref:`CMake ` installation instructions. + + +.. _windows_sources_requirements: + +Requirements +------------ + +The installation of *eProsima Fast DDS* in a Windows environment from sources requires the following tools to be installed in the system: + +* :ref:`windows_sources_visual_studio` +* :ref:`windows_sources_chocolatey` +* :ref:`windows_sources_cmake_pip3_wget_git` +* :ref:`windows_sources_colcon_install` [optional] +* :ref:`windows_sources_gtest` [for test only] + +.. _windows_sources_visual_studio: + +Visual Studio +^^^^^^^^^^^^^ + +`Visual Studio `_ is required to have a C++ compiler in the system. For this purpose, make sure to check the :code:`Desktop development with C++` option during the Visual Studio installation process. + +If Visual Studio is already installed but the Visual C++ Redistributable packages are not, open Visual Studio and go to :code:`Tools` -> :code:`Get Tools and Features` and in the :code:`Workloads` tab enable :code:`Desktop development with C++`. +Finally, click :code:`Modify` at the bottom right. + +.. _windows_sources_chocolatey: + +Chocolatey +^^^^^^^^^^ + +Chocolatey is a Windows package manager. It is needed to install some of *eProsima Fast DDS*'s dependencies. +Download and install it directly from the `website `_. + +.. _windows_sources_cmake_pip3_wget_git: + +CMake, pip3, wget and git +^^^^^^^^^^^^^^^^^^^^^^^^^ + +These packages provide the tools required to install *eProsima Fast DDS* and its dependencies from command line. +Download and install CMake_, pip3_, wget_ and git_ by following the instructions detailed in the respective websites. +Once installed, add the path to the executables to the :code:`PATH` from the *Edit the system environment variables* control panel. + +.. _windows_sources_colcon_install: + +Colcon +^^^^^^ + +colcon_ is a command line tool based on CMake_ aimed at building sets of software packages. +Install the ROS 2 development tools (colcon_ and vcstool_) by executing the following command: + +.. code-block:: bash + + pip3 install -U colcon-common-extensions vcstool + +.. note:: + + If this fails due to an Environment Error, add the :code:`--user` flag to the :code:`pip3` installation command. + +.. _windows_sources_gtest: + +Gtest +^^^^^ + +Gtest is a unit testing library for C++. +By default, *eProsima DDS Enabler* does not compile tests. +It is possible to activate them with the opportune `CMake options `_ when calling colcon_ or CMake_. +For more details, please refer to the :ref:`cmake_options` section. + +Run the following commands on your workspace to install Gtest. + +.. code-block:: bash + + git clone https://github.com/google/googletest.git + cmake -DCMAKE_INSTALL_PREFIX='C:\Program Files\gtest' -Dgtest_force_shared_crt=ON -DBUILD_GMOCK=ON ^ + -B build\gtest -A x64 -T host=x64 googletest + cmake --build build\gtest --config Release --target install + +or refer to the `Gtest Installation Guide `_ for a detailed description of the Gtest installation process. + + +.. _windows_sources_dependencies: + +Dependencies +------------ + +*eProsima DDS Enabler* has the following dependencies, when installed from sources in a Windows environment: + +* :ref:`windows_sources_asiotinyxml2` +* :ref:`windows_sources_openssl` +* :ref:`windows_sources_yamlcpp` +* :ref:`windows_sources_eprosima_dependencies` + +.. _windows_sources_asiotinyxml2: + +Asio and TinyXML2 libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Asio is a cross-platform C++ library for network and low-level I/O programming, which provides a consistent asynchronous model. +TinyXML2 is a simple, small and efficient C++ XML parser. +They can be downloaded directly from the links below: + +* `Asio `_ +* `TinyXML2 `_ + +After downloading these packages, open an administrative shell with *PowerShell* and execute the following command: + +.. code-block:: bash + + choco install -y -s asio tinyxml2 + +where :code:`` is the folder into which the packages have been downloaded. + +.. _windows_sources_openssl: + +OpenSSL +^^^^^^^ + +OpenSSL is a robust toolkit for the TLS and SSL protocols and a general-purpose cryptography library. +Download and install the latest OpenSSL version for Windows at this `link `_. +After installing, add the environment variable :code:`OPENSSL_ROOT_DIR` pointing to the installation root directory. + +For example: + +.. code-block:: bash + + OPENSSL_ROOT_DIR=C:\Program Files\OpenSSL-Win64 + +.. _windows_sources_yamlcpp: + +yaml-cpp +^^^^^^^^ + +``yaml-cpp`` is a YAML parser and emitter in C++ matching the YAML 1.2 spec, and is used by *eProsima DDS Enabler* application to parse the provided configuration files. +From an administrative shell with *PowerShell*, execute the following commands in order to download and install ``yaml-cpp`` for Windows: + +.. code-block:: bash + + git clone --branch yaml-cpp-0.7.0 https://github.com/jbeder/yaml-cpp + cmake -DCMAKE_INSTALL_PREFIX='C:\Program Files\yamlcpp' -B build\yamlcpp yaml-cpp + cmake --build build\yamlcpp --target install # If building in Debug mode, add --config Debug + +.. _windows_sources_eprosima_dependencies: + +eProsima dependencies +^^^^^^^^^^^^^^^^^^^^^ + +If it already exists in the system an installation of *Fast DDS* and *DDS Pipe* libraries, just source this libraries when building the *eProsima DDS Enabler* application by using the command: + +.. code-block:: bash + + source /install/setup.bash + source /install/setup.bash + +In other case, just skip this step. + + +.. _windows_sources_colcon_installation: + +Colcon installation (recommended) +================================= + +.. important:: + + Run colcon within a Visual Studio prompt. + To do so, launch a *Developer Command Prompt* from the search engine. + +#. Create a :code:`DDS-Enabler` directory and download the :code:`.repos` file that will be used to install + *eProsima DDS Enabler* and its dependencies: + + .. code-block:: bash + + mkdir \DDS-Enabler + cd \DDS-Enabler + mkdir src + wget https://raw.githubusercontent.com/eProsima/DDS-Enabler/main/ddsenabler.repos ddsenabler.repos + vcs import src < ddsenabler.repos + + .. note:: + + In case there is already a *Fast DDS* installation in the system it is not required to download and build + every dependency in the :code:`.repos` file. + It is just needed to download and build the *eProsima DDS Enabler* project having sourced its dependencies. + Refer to section :ref:`eprosima_dependencies` in order to check how to source *Fast DDS* library. + +#. Build the packages: + + .. code-block:: bash + + colcon build + +.. note:: + + Being based on CMake_, it is possible to pass the CMake configuration options to the :code:`colcon build` command. + For more information on the specific syntax, please refer to the `CMake specific arguments `_ page of the colcon_ manual. + + +.. _windows_sources_cmake_installation: + +CMake installation +================== + +This section explains how to compile *eProsima DDS Enabler* with CMake_, either :ref:`locally ` or :ref:`globally `. + +.. note:: + + This section is not required if you have already installed the *eProsima DDS Enabler* using Colcon. + +.. _windows_sources_local_installation: + +Local installation +------------------ + +#. Open a command prompt, and create a :code:`DDS-Enabler` directory where to download and build *eProsima DDS Enabler* and its dependencies: + + .. code-block:: bash + + mkdir \DDS-Enabler + mkdir \DDS-Enabler\src + mkdir \DDS-Enabler\build + cd \DDS-Enabler + wget https://raw.githubusercontent.com/eProsima/DDS-Enabler/main/ddsenabler.repos ddsenabler.repos + vcs import src < ddsenabler.repos + +#. Compile all dependencies using CMake_. + + * `Foonathan memory `_ + + .. code-block:: bash + + cd \DDS-Enabler + mkdir build\foonathan_memory_vendor + cd build\foonathan_memory_vendor + cmake \DDS-Enabler\src\foonathan_memory_vendor -DCMAKE_INSTALL_PREFIX=\DDS-Enabler\install ^ + -DBUILD_SHARED_LIBS=ON + cmake --build . --config Release --target install + + * `Fast CDR `_ + + .. code-block:: bash + + cd \DDS-Enabler + mkdir build\fastcdr + cd build\fastcdr + cmake \DDS-Enabler\src\fastcdr -DCMAKE_INSTALL_PREFIX=\DDS-Enabler\install + cmake --build . --config Release --target install + + * `Fast DDS `_ + + .. code-block:: bash + + cd \DDS-Enabler + mkdir build\fastdds + cd build\fastdds + cmake \DDS-Enabler\src\fastdds -DCMAKE_INSTALL_PREFIX=\DDS-Enabler\install ^ + -DCMAKE_PREFIX_PATH=\DDS-Enabler\install + cmake --build . --config Release --target install + + * `Dev Utils `_ + + .. code-block:: bash + + # CMake Utils + cd \DDS-Enabler + mkdir build\cmake_utils + cd build\cmake_utils + cmake \DDS-Enabler\src\dev-utils\cmake_utils -DCMAKE_INSTALL_PREFIX=\DDS-Enabler\install ^ + -DCMAKE_PREFIX_PATH=\DDS-Enabler\install + cmake --build . --config Release --target install + + # C++ Utils + cd \DDS-Enabler + mkdir build\cpp_utils + cd build\cpp_utils + cmake \DDS-Enabler\src\dev-utils\cpp_utils -DCMAKE_INSTALL_PREFIX=\DDS-Enabler\install ^ + -DCMAKE_PREFIX_PATH=\DDS-Enabler\install + cmake --build . --config Release --target install + + * `DDS Pipe `_ + + .. code-block:: bash + + # ddspipe_core + cd \DDS-Enabler + mkdir build\ddspipe_core + cd build\ddspipe_core + cmake cd \DDS-Enabler\src\ddspipe\ddspipe_core -DCMAKE_INSTALL_PREFIX=\DDS-Enabler\install -DCMAKE_PREFIX_PATH=\DDS-Enabler\install + cmake --build . --target install + + # ddspipe_yaml + cd \DDS-Enabler + mkdir build\ddspipe_yaml + cd build\ddspipe_yaml + cmake \DDS-Enabler\src\ddspipe\ddspipe_yaml -DCMAKE_INSTALL_PREFIX=\DDS-Enabler\install -DCMAKE_PREFIX_PATH=\DDS-Enabler\install + cmake --build . --target install + + # ddspipe_participants + cd \DDS-Enabler + mkdir build\ddspipe_participants + cd build\ddspipe_participants + cmake \DDS-Enabler\src\ddspipe\ddspipe_participants -DCMAKE_INSTALL_PREFIX=\DDS-Enabler\install -DCMAKE_PREFIX_PATH=\DDS-Enabler\install + cmake --build . --target install + +#. Once all dependencies are installed, install *eProsima DDS Enabler*: + + .. code-block:: bash + + # ddsenabler_participants + cd \DDS-Enabler + mkdir build\ddsenabler_participants + cd build\ddsenabler_participants + cmake \DDS-Enabler\src\ddsenabler\ddsenabler_participants ^ + -DCMAKE_INSTALL_PREFIX=\DDS-Enabler\install -DCMAKE_PREFIX_PATH=\DDS-Enabler\install + cmake --build . --config Release --target install + + # ddsenabler_yaml + cd \DDS-Enabler + mkdir build\ddsenabler_yaml + cd build\ddsenabler_yaml + cmake \DDS-Enabler\src\ddsenabler\ddsenabler_yaml -DCMAKE_INSTALL_PREFIX=\DDS-Enabler\install ^ + -DCMAKE_PREFIX_PATH=\DDS-Enabler\install + cmake --build . --config Release --target install + + # ddsenabler + cd \DDS-Enabler + mkdir build\ddsenabler_tool + cd build\ddsenabler_tool + cmake \DDS-Enabler\src\ddsenabler\ddsenabler -DCMAKE_INSTALL_PREFIX=\DDS-Enabler\install ^ + -DCMAKE_PREFIX_PATH=\DDS-Enabler\install + cmake --build . --config Release --target install + + .. note:: + + By default, *eProsima DDS Enabler* does not compile tests. + However, they can be activated by downloading and installing `Gtest `_ + and building with CMake option ``-DBUILD_TESTS=ON``. + + +.. _windows_sources_global_installation: + +Global installation +------------------- + +To install *eProsima DDS Enabler* system-wide instead of locally, remove all the flags that appear in the configuration steps of :code:`Fast-CDR`, :code:`Fast-DDS`, :code:`Dev-Utils`, :code:`DDS-Pipe`, and :code:`DDS-Enabler` + + +Run an application +================== + +If *eProsima DDS Enabler* was compiled using colcon, when running an instance of *eProsima DDS Enabler*, the colcon overlay built in the dedicated :code:`DDS-Enabler` directory must be sourced. +There are two possibilities: + +* Every time a new shell is opened, prepare the environment locally by typing the command: + + .. code-block:: bash + + setup.bat + +* Add the sourcing of the colcon overlay permanently, by opening the *Edit the system environment variables* control panel, and adding the installation path to the :code:`PATH`. + + +.. External links + +.. _colcon: https://colcon.readthedocs.io/en/released/ +.. _CMake: https://cmake.org +.. _pip3: https://docs.python.org/3/installing/index.html +.. _wget: https://www.gnu.org/software/wget/ +.. _git: https://git-scm.com/ +.. _vcstool: https://pypi.org/project/vcstool/ +.. _Gtest: https://github.com/google/googletest diff --git a/ddsenabler_docs/docs/index.rst b/ddsenabler_docs/docs/index.rst index 44b54125..4610c45e 100644 --- a/ddsenabler_docs/docs/index.rst +++ b/ddsenabler_docs/docs/index.rst @@ -13,15 +13,17 @@ /02-formalia/titlepage -.. .. _index_installation: +.. _index_installation: -.. .. toctree:: -.. :caption: Installation Manual -.. :maxdepth: 2 -.. :numbered: 5 -.. :hidden: +.. toctree:: + :caption: Installation Manual + :maxdepth: 2 + :numbered: 5 + :hidden: -.. Linux + Linux installation from sources + Windows installation from sources + CMake Options .. .. _index_getting_started: