diff --git a/docs/04-common/python_requirements.rst b/docs/04-common/python_requirements.rst index 093aa7971..b9113460f 100644 --- a/docs/04-common/python_requirements.rst +++ b/docs/04-common/python_requirements.rst @@ -7,6 +7,13 @@ SWIG_ is a development tool that allows connecting programs written in C/C++ wit other programming languages, among them Python. SWIG 4.0 is required in order to build Fast DDS Python bindings. +.. note:: + + More recent SWIG_ releases are not yet supported. + Please, ensure to be using SWIG 4.0. + +.. end-windows-swig + SWIG_ can be installed directly from the package manager of the appropriate Linux distribution. For Ubuntu, please run: diff --git a/docs/installation/sources/sources_linux.rst b/docs/installation/sources/sources_linux.rst index a7cd6c368..9f0a7f124 100644 --- a/docs/installation/sources/sources_linux.rst +++ b/docs/installation/sources/sources_linux.rst @@ -18,8 +18,8 @@ It is organized as follows: Fast DDS library installation """"""""""""""""""""""""""""" -This section describes the instructions for installing *eProsima Fast DDS* in a Linux environment from -sources. The following packages will be installed: +This section describes the instructions for installing *eProsima Fast DDS* in a Linux environment from sources. +The following packages will be installed: * :code:`foonathan_memory_vendor`, an STL compatible C++ memory allocator `library `_. @@ -49,7 +49,8 @@ CMake, g++, pip3, wget and git These packages provide the tools required to install *eProsima Fast DDS* and its dependencies from command line. Install CMake_, `g++ `_, pip3_, wget_ and git_ using the package manager of the appropriate -Linux distribution. For example, on Ubuntu use the command: +Linux distribution. +For example, on Ubuntu use the command: .. code-block:: bash @@ -101,8 +102,8 @@ For example, on Ubuntu use the command: 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. +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. Install libp11_ using the package manager of the appropriate Linux distribution. For example, on Ubuntu use the command: @@ -122,8 +123,8 @@ For example, on Ubuntu use the command: sudo apt install softhsm2 -Note that the *softhsm2* package creates a new group called *softhsm*. In order -to grant access to the HSM module a user must belong to this group. +Note that the *softhsm2* package creates a new group called *softhsm*. +In order to grant access to the HSM module a user must belong to this group. .. code-block:: bash @@ -135,8 +136,9 @@ must be updated specifying the libp11_ and hardware module (here SoftHSM_) dynam location. This configuration step can be avoided using p11kit_ which allows OpenSSL to find PKCS#11 -devices on runtime without static configuration. This kit is often available through -the Linux distribution package manager. On Ubuntu, for example: +devices on runtime without static configuration. +This kit is often available through the Linux distribution package manager. +On Ubuntu, for example: .. code-block:: bash @@ -223,8 +225,8 @@ This section explains how to use it to compile *eProsima Fast DDS* and its depen .. 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 + 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. @@ -324,12 +326,14 @@ configuration step of :code:`foonathan_memory_vendor` to the following: -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`. +.. note:: - .. code-block:: bash + 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 + sudo cmake --build . --target install .. _run_app_cmake_sl: @@ -439,8 +443,8 @@ This section explains how to use it to compile *Fast DDS Python bindings* and it .. 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 + 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. @@ -543,12 +547,14 @@ first in the configuration step of :code:`foonathan_memory_vendor` to the follow -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`. +.. note:: - .. code-block:: bash + 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 + sudo cmake --build . --target install Run an application ^^^^^^^^^^^^^^^^^^ diff --git a/docs/installation/sources/sources_windows.rst b/docs/installation/sources/sources_windows.rst index 917d8b157..dcd9f863a 100644 --- a/docs/installation/sources/sources_windows.rst +++ b/docs/installation/sources/sources_windows.rst @@ -17,8 +17,8 @@ It is organized as follows: 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: +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 `_. @@ -27,8 +27,8 @@ sources. The following packages will be installed: * :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. +Afterwards, the user can choose whether to follow either the :ref:`colcon ` +or the :ref:`CMake ` installation instructions. .. _requirements_sw: @@ -50,20 +50,22 @@ installed in the system: 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. +`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. +: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. +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: @@ -164,8 +166,8 @@ For example: 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. +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 `__ @@ -179,19 +181,20 @@ 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 +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: +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: +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 @@ -201,15 +204,15 @@ any other we must set the variable: 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: +replacing the binaries path with the proper ones. +For example, before any section in the configuration file we introduce: .. code-block:: cfg 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. +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:: cfg @@ -241,8 +244,8 @@ This section explains how to use it to compile *eProsima Fast DDS* and its depen .. important:: - Run colcon within a Visual Studio prompt. To do so, launch a *Developer Command Prompt* from the - search engine. + 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: @@ -276,8 +279,8 @@ This section explains how to use it to compile *eProsima Fast DDS* and its depen .. 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 + 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. @@ -379,12 +382,225 @@ 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: +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 + +.. 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: