.. _windows_sources: Windows installation from sources ================================= The instructions for installing both the :ref:`Fast DDS library ` and the :ref:`Fast DDS-Gen ` generation tool from sources are provided in this page. It is organized as follows: .. contents:: :local: :backlinks: none :depth: 2 .. _fastdds_lib_sw: Fast DDS library installation """"""""""""""""""""""""""""" This section provides the instructions for installing *eProsima Fast DDS* in a Windows environment from sources. The following packages will be installed: * :code:`foonathan_memory_vendor`, an STL compatible C++ memory allocator `library `_. * :code:`fastdds_gen`, a Java application that generates source code using the data types defined in an IDL file. * :code:`fastcdr`, a C++ library that serializes according to the `standard CDR `_ serialization mechanism. * :code:`fastrtps`, the core library of *eProsima Fast DDS* library. First of all, the :ref:`requirements_sw` and :ref:`dependencies_sw` 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_sw: Requirements ------------ The installation of *eProsima Fast DDS* in a Windows environment from sources requires the following tools to be installed in the system: * :ref:`visual_studio_sw` * :ref:`chocolatey_sw` * :ref:`cmake_pip3_wget_git_sw` * :ref:`gtest_sw` [optional] .. _visual_studio_sw: 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. .. _chocolatey_sw: 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 `_. .. _cmake_pip3_wget_git_sw: 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. .. _gtest_sw: Gtest ^^^^^ GTest is a unit testing library for C++. By default, *eProsima Fast DDS* does not compile tests. It is possible to activate them with the opportune `CMake configuration options `_ when calling colcon_ or CMake_. For more details, please refer to the :ref:`cmake_options` section. Also add the `Gtest repository `_ into the workspace directory. .. code-block:: bash git clone --branch release-1.11.0 https://github.com/google/googletest src/googletest-distribution and add next argument to the `colcon` call .. code-block:: bash colcon build --cmake-args -Dgtest_force_shared_crt=ON .. _dependencies_sw: Dependencies ------------ *eProsima Fast RTPS* has the following dependencies, when installed from sources in a Windows environment: * :ref:`asiotinyxml2_sw` * :ref:`openssl_sw` .. _asiotinyxml2_sw: 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. .. _openssl_sw: OpenSSL ^^^^^^^ OpenSSL is a robust toolkit for the TLS and SSL protocols and a general-purpose cryptography library. Install it by running the following command inside an administrative shell with *PowerShell*: .. code-block:: bash choco install -y openssl .. _libp11_sw: Libp11 and SoftHSM libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Libp11 provides PKCS#11 support for OpenSSL. This is an optional dependency, that is needed only when *eprosima Fast DDS* is used with security and PKCS#11 URIs. Download the latest libp11_ version for Windows from this `repository `__ and follow the `installation instructions `_ SoftHSM is a software implementation of an HSM (Hardware Security Module). If *eProsima Fast DDS* tests are activated and *libp11* is installed on the system, SoftHSM is additionally required to run tests of PKCS#11 features. Download the SoftHSM_ for Windows installer from this `repository `__. Execute the installer and follow the installation instructions. OpenSSL access HSM and other hardware devices through its engine functionality. In order to set up a new engine the OpenSSL configuration files must be updated specifying the libp11_ and hardware module (here SoftHSM_) dynamic libraries location. OpenSSL on Windows references its default configuration file through the `OPENSSL_CONF` environment variable. By default OpenSSL installs two identical default configuration files: * `C:\\Program Files\\OpenSSL-Win64\\bin\\cnf\\openssl.cnf` mimics the Linux distributions one. * `C:\\Program Files\\OpenSSL-Win64\\bin\\openssl.cfg` kept for backward compatibility. Neither of them are loaded by default. In order to direct OpenSSL to load one of them or any other we must set the variable: .. code-block:: console cmd> set OPENSSL_CONF=C:\Program Files\OpenSSL-Win64\bin\cnf\openssl.cnf powershell> $Env:OPENSSL_CONF="C:\Program Files\OpenSSL-Win64\bin\cnf\openssl.cnf" Once we have hinted OpenSSL the configuration file to use we must modify it to set up the new PKCS#11 engine following the `OpenSSL guidelines `_ replacing the binaries path with the proper ones. For example, before any section in the configuration file we introduce: .. code-block:: idl openssl_conf = openssl_init at the end of the file we include the engine devoted sections. Note to use POSIX path separator instead of the windows one. .. code-block:: idl [openssl_init] engines = engine_section [engine_section] pkcs11 = pkcs11_section [pkcs11_section] engine_id = pkcs11 dynamic_path = C:/Program Files/libp11/src/pkcs11.dll MODULE_PATH = C:/Program Files (x86)/SoftHSM2/lib/softhsm2-x64.dll init = 0 A proper set up can be verified using OpenSSL command line tool: .. code-block:: console openssl engine pkcs11 -t .. _colcon_installation_windows: Colcon installation ------------------- colcon_ is a command line tool based on CMake_ aimed at building sets of software packages. This section explains how to use it to compile *eProsima Fast DDS* and its dependencies. .. important:: Run colcon within a Visual Studio prompt. To do so, launch a *Developer Command Prompt* from the search engine. #. Install the ROS 2 development tools (colcon_ and vcstool_) by executing the following command: .. code-block:: bash pip3 install -U colcon-common-extensions vcstool and add the path to the :code:`vcs` executable to the :code:`PATH` from the *Edit the system environment variables* control panel. .. note:: If this fails due to an Environment Error, add the :code:`--user` flag to the :code:`pip3` installation command. #. Create a :code:`Fast-DDS` directory and download the repos file that will be used to install *eProsima Fast DDS* and its dependencies: .. code-block:: bash mkdir ~\Fast-DDS cd ~\Fast-DDS wget https://raw.githubusercontent.com/eProsima/Fast-DDS/master/fastrtps.repos -output fastrtps.repos mkdir src vcs import src --input fastrtps.repos Finally, use colcon_ to compile all software: .. code-block:: bash colcon build --packages-up-to fastrtps .. 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. .. _run_app_colcon_sw: Run an application ^^^^^^^^^^^^^^^^^^ When running an instance of an application using *eProsima Fast DDS*, the colcon overlay built in the dedicated :code:`Fast-DDS` 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 :code:`~/Fast-DDS/install/setup.bat` to the :code:`PATH`. .. _cmake_installation_windows: CMake installation ------------------- This section explains how to compile *eProsima Fast DDS* with CMake_, either :ref:`locally ` or :ref:`globally `. .. _local_installation_sw: Local installation ^^^^^^^^^^^^^^^^^^ #. Open a command prompt, and create a :code:`Fast-DDS` directory where to download and build *eProsima Fast DDS* and its dependencies: .. code-block:: bash mkdir %USERPROFILE%\Fast-DDS #. Clone the following dependencies and compile them using CMake_. * Fast DDS depends on `Foonathan memory `_. To ease the dependency management, *eProsima* provides a vendor package `Foonathan memory vendor `_, which downloads and builds a specific revision of *Foonathan memory* if the library is not found in the system. .. code-block:: bash cd %USERPROFILE%\Fast-DDS git clone https://github.com/eProsima/foonathan_memory_vendor.git cd foonathan_memory_vendor mkdir build && cd build cmake -DCMAKE_INSTALL_PREFIX=%USERPROFILE%/Fast-DDS/install .. cmake --build . --target install * `Fast CDR `_ .. code-block:: bash cd %USERPROFILE%\Fast-DDS git clone https://github.com/eProsima/Fast-CDR.git cd Fast-CDR mkdir build && cd build cmake -DCMAKE_INSTALL_PREFIX=%USERPROFILE%/Fast-DDS/install .. cmake --build . --target install #. Once all dependencies are installed, install *eProsima Fast DDS*: .. code-block:: bash cd %USERPROFILE%\Fast-DDS git clone https://github.com/eProsima/Fast-DDS.git cd Fast-DDS mkdir build && cd build cmake -DCMAKE_INSTALL_PREFIX=%USERPROFILE%/Fast-DDS/install .. cmake --build . --target install .. _global_installation_sw: Global installation ^^^^^^^^^^^^^^^^^^^ To install *eProsima Fast DDS* system-wide instead of locally, remove the ``CMAKE_INSTALL_PREFIX`` flags that appear in the configuration steps of ``Fast-CDR`` and ``Fast-DDS``. .. note:: By default, *eProsima Fast DDS* does not compile tests. However, they can be activated by downloading and installing `Gtest `_. .. _run_app_cmake_sw: Run an application ^^^^^^^^^^^^^^^^^^ When running an instance of an application using *eProsima Fast DDS*, it must be linked with the library where the packages have been installed. This can be done by opening the *Edit system environment variables* control panel and adding to the ``PATH`` the *Fast DDS* and *Fast CDR* installation directories: * *Fast DDS*: C:\\Program Files\\fastrtps * *Fast CDR*: C:\\Program Files\\fastcdr .. _fastdds_python_sw: Fast DDS Python bindings installation """"""""""""""""""""""""""""""""""""" This section provides the instructions for installing *Fast DDS Python bindings* in a Windows environment from sources. *Fast DDS Python bindings* is an extension of *Fast DDS* which provides access to the Fast DDS API through Python. Therefore, its installation is an extension of the installation of :ref:`Fast DDS `. *Fast DDS Python bindings* source code consists on several `.i` files which will be processed by SWIG_. Then C++ files (for connecting C++ and Python) and Python files (Python module for Fast DDS) will be generated. First of all, the :ref:`requirements_python_sw` and :ref:`dependencies_python_sw` 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_python_sw: Requirements ------------ The installation of *Fast DDS Python bindings* in a Windows environment from sources requires the following tools to be installed in the system: - :ref:`Fast DDS requirements ` - :ref:`swig_python_sw` .. _swig_python_sw: .. include:: ../../04-common/python_requirements.rst :start-after: .. begin-swig :end-before: .. end-windows-swig .. _dependencies_python_sw: Dependencies ------------ *Fast DDS Python bindings* has the following dependencies, when installed from sources in a Windows environment: - :ref:`Fast DDS dependencies ` .. _colcon_installation_python_windows: Colcon installation ------------------- colcon_ is a command line tool based on CMake_ aimed at building sets of software packages. This section explains how to use it to compile *Fast DDS Python bindings* and its dependencies. .. important:: Run colcon within a Visual Studio prompt. To do so, launch a *Developer Command Prompt* from the search engine. #. Install the ROS 2 development tools (colcon_ and vcstool_) by executing the following command: .. code-block:: bash pip3 install -U colcon-common-extensions vcstool and add the path to the :code:`vcs` executable to the :code:`PATH` from the *Edit the system environment variables* control panel. .. note:: If this fails due to an Environment Error, add the :code:`--user` flag to the :code:`pip3` installation command. #. Create a :code:`Fast-DDS-python` directory and download the repos file that will be used to install *Fast DDS Python bindings* and its dependencies: .. code-block:: bash mkdir ~\Fast-DDS-python cd ~\Fast-DDS-python wget https://raw.githubusercontent.com/eProsima/Fast-DDS-python/main/fastdds_python.repos mkdir src vcs import src --input fastdds_python.repos #. Build the packages: .. code-block:: bash colcon build --packages-up-to fastdds_python .. note:: Being based on CMake_, it is possible to pass 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. Run an application ^^^^^^^^^^^^^^^^^^ When running an instance of an application using *Fast DDS Python bindings*, the colcon overlay built in the dedicated :code:`Fast-DDS-python` 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 :code:`~/Fast-DDS/install/setup.bat` to the :code:`PATH`. .. _cmake_installation_python_windows: CMake installation ------------------ This section explains how to compile *Fast DDS Python bindings* with CMake_, either :ref:`locally ` or :ref:`globally `. .. _local_installation_python_sw: Local installation ^^^^^^^^^^^^^^^^^^ #. Open a command prompt, and create a :code:`Fast-DDS-python` directory where to download and build *Fast DDS Python bindings* and its dependencies: .. code-block:: bash mkdir %USERPROFILE%\Fast-DDS-python #. Clone the following dependencies and compile them using CMake_. * Fast DDS depends on `Foonathan memory `_. To ease the dependency management, *eProsima* provides a vendor package `Foonathan memory vendor `_, which downloads and builds a specific revision of *Foonathan memory* if the library is not found in the system. .. code-block:: bash cd %USERPROFILE%\Fast-DDS-python git clone https://github.com/eProsima/foonathan_memory_vendor.git cd foonathan_memory_vendor mkdir build && cd build cmake -DCMAKE_INSTALL_PREFIX=%USERPROFILE%/Fast-DDS-python/install .. cmake --build . --target install * `Fast CDR `_ .. code-block:: bash cd %USERPROFILE%\Fast-DDS-python git clone https://github.com/eProsima/Fast-CDR.git cd Fast-CDR mkdir build && cd build cmake -DCMAKE_INSTALL_PREFIX=%USERPROFILE%/Fast-DDS-python/install .. cmake --build . --target install * `Fast DDS `_ .. code-block:: bash cd %USERPROFILE%\Fast-DDS-python git clone https://github.com/eProsima/Fast-DDS.git cd Fast-DDS mkdir build && cd build cmake -DCMAKE_INSTALL_PREFIX=%USERPROFILE%/Fast-DDS-python/install .. cmake --build . --target install #. Once all dependencies are installed, install *Fast DDS Python bindings*: .. code-block:: bash cd ~/Fast-DDS-python git clone https://github.com/eProsima/Fast-DDS-python.git cd Fast-DDS-python mkdir build && cd build cmake -DCMAKE_INSTALL_PREFIX=%USERPROFILE%/Fast-DDS-python/install .. cmake --build . --target install .. _global_installation_python_sw: Global installation ^^^^^^^^^^^^^^^^^^^ To install *Fast DDS Python bindings* system-wide instead of locally, remove all the flags that appear in the configuration steps of :code:`Fast-CDR`, :code:`Fast-DDS` and :code:`Fast-DDS-python`, 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 .. note:: Installation on system directories may need of permissions. Maybe permissions have to be granted through :code:`sudo`. .. code-block:: bash sudo cmake --build . --target install Run an application ^^^^^^^^^^^^^^^^^^ When running an instance of an application using *Fast DDS Python bindings*, it must be linked with the library where the packages have been installed. This can be done by opening the *Edit system environment variables* control panel and adding to the ``PATH`` the *Fast DDS python*, *Fast CDR* and *Fast DDS* installation directories: * *Fast DDS python*: C:\\Program Files\\fastdds_python * *Fast DDS*: C:\\Program Files\\fastrtps * *Fast CDR*: C:\\Program Files\\fastcdr .. _fastddsgen_sw: Fast DDS-Gen installation """"""""""""""""""""""""" This section outlines the instructions for installing *Fast DDS-Gen* in a Windows environment from sources. *Fast DDS-Gen* is a Java application that generates source code using the data types defined in an IDL file. Please refer to :ref:`fastddsgen_intro` for more information. Requirements ------------ In order to compile *Fast DDS-Gen*, the following packages need to be installed in the system: * :ref:`java_sb` * :ref:`gradle_sb` .. _java_sb: Java JDK ^^^^^^^^ The JDK is a development environment for building applications and components using the Java language. Download and install it at the following the steps given in the `Oracle website `_. .. _gradle_sb: Gradle ^^^^^^ Gradle is an open-source build automation tool. Download and install the last stable version of `Gradle `_ in the preferred way. Compiling Fast DDS-Gen ---------------------- Once the requirements above are met, install *Fast DDS-Gen* by following the steps below: .. code-block:: bash mkdir -p ~/Fast-DDS/src cd ~/Fast-DDS/src git clone --recursive https://github.com/eProsima/Fast-DDS-Gen.git fastddsgen cd fastddsgen gradlew assemble Contents ^^^^^^^^ The ``Fast-DDS-Gen`` folder contains the following packages: * ``share/fastddsgen``, where the generated Java application is. * ``scripts``, containing some user friendly scripts. .. note:: To make these scripts accessible from any directory, add the ``scripts`` folder path to the ``PATH`` environment variable. .. 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 .. _libp11: https://github.com/OpenSC/libp11/ .. _SoftHSM: https://www.opendnssec.org/softhsm/