Warning
In preparation for v3.0.0, Fast DDS' master branch is undergoing major changes entailing API breaks. Until Fast DDS v3.0.0 is released, it is strongly advisable to use the latest stable branch, 2.14.x.
eprosima Fast DDS (formerly Fast RTPS) is a C++ implementation of the DDS (Data Distribution Service) standard of the OMG (Object Management Group). eProsima Fast DDS implements the RTPS (Real Time Publish Subscribe) protocol, which provides publisher-subscriber communications over unreliable transports such as UDP, as defined and maintained by the Object Management Group (OMG) consortium. RTPS is also the wire interoperability protocol defined for the Data Distribution Service (DDS) standard. eProsima Fast DDS exposes an API to access the RTPS protocol directly, giving the user full access to the protocol internals.
Some of the main features of this library are:
- Configurable best-effort and reliable publish-subscribe communication policies for real-time applications.
- Plug and play connectivity so that any new applications are automatically discovered by any other members of the network.
- Modularity and scalability to allow continuous growth with complex and simple devices in the network.
- Configurable network behavior and interchangeable transport layer: Choose the best protocol and system input/output channel combination for each deployment.
- Two API Layers: a high-level Publisher-Subscriber one focused on usability (DDS) and a lower-level Writer-Reader one that provides finer access to the inner workings of the RTPS protocol.
eProsima Fast DDS has been adopted by multiple organizations in many sectors including these important cases:
- Robotics: ROS (Robotic Operating System) as their default middleware for ROS2.
- EU R&D: FIWARE Incubated GE.
You can find all the library's source code on our GitHub repository.
The documentation is built using Sphinx, and it is hosted at Read the Docs. The online documentation generated with this project can be found in Fast DDS documentation.
The following guide has been developed and tested in Ubuntu 20.04. It covers two mechanisms for build and testing the documentation (colcon and CMake), and one that just generates the HTML, which can be used to simulate the process followed in ReadTheDocs. Contributors are asked to not only generate the HTML, but to also build and test their changes locally following one of the two first methods.
- Install common dependencies
- Python virtual environment
- Colcon installation
- CMake installation
- Simulating Read the Docs
- Generating documentation in other formats
Install dependencies common to all methods:
sudo apt update
sudo apt install -y \
git \
curl \
wget \
doxygen \
python3-doc8 \
python3 \
python3-pip \
python3-venv \
imagemagick \
libenchant-2-2 \
plantumlIn order to build the documentation, some python3 dependencies are required. This guide uses a python3 virtual environment to install such dependencies, thus avoiding polluting the user's installation. Create a virtual environment and install python3 dependencies.
python3 -m venv fastdds-docs-venv
source fastdds-docs-venv/bin/activate
wget https://raw.githubusercontent.com/eProsima/Fast-DDS-docs/master/docs/requirements.txt
pip3 install -r requirements.txtThe version of python3 used in the virtual environment can be seen by running the following command within the virtual environment:
python3 -V-
Fast DDS-docs depends on Fast DDS, so its dependencies must be installed alongside some required building tools.
sudo apt update sudo apt install -y \ # Build tools gcc \ g++ \ cmake \ # Fast DDS dependencies libasio-dev \ libtinyxml2-dev \ libssl-dev \ # Fast DDS-Docs dependencies python3-sphinx -
Create a colcon workspace containing Fast DDS and Fast DDS-docs:
mkdir -p <path_to_ws>/fastdds-docs_ws/src cd <path_to_ws>/fastdds-docs_ws wget https://raw.githubusercontent.com/eProsima/Fast-DDS-docs/<version>/colcon.meta wget https://raw.githubusercontent.com/eProsima/Fast-DDS/<version>/fastdds.repos vcs import src < fastdds.repos cd src git clone https://github.com/eProsima/Fast-DDS-docs fastdds-docs
-
[OPTIONAL]: You can checkout to different Fast DDS and Fast DDS-docs branches within the appropriate repositories located in
<path_to_ws>/fastdds-docs_ws/src -
Build the workspace using colcon1
source <path_to_venv>/fastdds-docs-venv/bin/activate cd <path_to_ws>/fastdds-docs_ws colcon build
-
Run documentation tests:
source <path_to_venv>/fastdds-docs-venv/bin/activate cd <path_to_ws>/fastdds-docs_ws colcon test --packages-select fastdds-docs --event-handlers=console_direct+
Fast DDS-docs is a CMake project, and as such it can be build using CMake directly.
This guide does not cover building Fast DDS or installing its dependencies.
However, it is required to have a Fast DDS installation built with option -DSECURITY=ON.
It is up to the user to link to the appropriate Fast DDS installation using, for instance,
CMAKE_PREFIX_PATH.
source <path_to_venv>/fastdds-docs-venv/bin/activate
git clone https://github.com/eProsima/Fast-DDS-docs fastdds-docs
cd fastdds-docs
mkdir build
cd build
cmake .. -DBUILD_DOCUMENTATION=ON -DCOMPILE_TESTS=ON
cmake --build .Now, you can run documentation tests:
source <path_to_venv>/fastdds-docs-venv/bin/activate
cd <path_to_repo>/fastdds-docs/build
ctest -VVReadTheDocs generates the documentation using Sphinx and conf.py.
This means that it does not execute any colcon or CMake commands.
Furthermore, Fast DDS is not available for API reference documentation generation.
conf.py provides some extra logic to download Fast DDS and generate the Doxygen documentation when running on a Read the Docs environment.
This is done by means of the environment variable READTHEDOCS.
When this variable is set to True, conf.py will clone Fast DDS in build/fastdds/ and will set it to a specific branch according to the following criteria:
- Try to checkout to the branch specified by environment variable
FASTDDS_BRANCH. - If the variable is not set, or the branch does not exist, try to checkout to a branch with the same name as the current branch on this repository.
- If the previous fails, fallback to
master.
Also Fast DDS Python bindings is cloned and follows a similar criteria:
- Try to checkout to the branch specified by environment variable
FASTDDS_PYTHON_BRANCH. - If the variable is not set, or the branch does not exist, try to checkout to a branch with the same name as the current branch on this repository.
- If the previous fails, fallback to
main.
To simulate ReadTheDocs operation, make sure you do not have a build directory.
Then, set READTHEDOCS, FASTDDS_BRANCH and FASTDDS_PYTHON_BRANCH and run sphinx:
source <path_to_venv>/fastdds-docs-venv/bin/activate
cd <path_to_docs_repo>/fastdds-docs
rm -rf build
READTHEDOCS=True FASTDDS_BRANCH=<branch> FASTDDS_PYTHON_BRANCH=<branch> sphinx-build \
-b html \
-D breathe_projects.FastDDS=<abs_path_to_docs_repo>/fastdds-docs/build/doxygen/xml \
-d <abs_path_to_docs_repo>/fastdds-docs/build/doctrees \
docs <abs_path_to_docs_repo>/fastdds-docs/build/htmlUsing either CMake or colcon, the documentation is built using Sphinx's html builder.
However, Sphinx supports several other building formats, which are enabled through Sphinx builders.
Once a builder is selected, the documentation can be built using the Simulating Read the Docs approach, specifying the appropriate builder with the -b CLI option
The project is structured as follows:
- The root directory contains global scope files, such as this one.
- The docs directory contains all documentation source code.
- Code snippets and testing code is located in the code directory.
The docs directory contains:
- _static: For HTML theme related files.
- 01-figures: For all the documentation figures. SVG files are the preferred format since the XML can be modified or otherwise checked for differences.
- 02-formalia: Must-have pages such as Introduction.
- 03-exports: Files for common aliases so they can be included when needed
- fastdds: Fast DDS documentation.
- fastddscli: Fast DDS CLI documentation.
- fastddsgen: Fast DDS-Gen documentation.
- installation: Installation manual.
- notes: Release notes.
All new documentation must fall into one of these directories, with the exception of those contributions which are not related to any of the given descriptions.
Keep in mind that this is an Sphinx based project, and as such, all the documentation is written in reStructuredText.
All unrecognized words must be added to the spelling_wordlist.txt dictionary in alphabetical order, with exception of the ones coming from the API reference documentation, which must be added to docs/fastdds/api_reference/spelling_wordlist.txt.
The code directory contains all the files related to code snippets and CI testing. Files of particular importance are:
- CodeTester.cpp: Contains all Fast DDS pub-sub and RTPS layer snippets. It is a buildable file, so it can be compiled and linked against the Fast DDS to verify that all samples of code are up to date. Furthermore, it is used to create an executable that is then used to generate Ctest tests.
- DDSCodeTester.cpp: Contains Fast DDS DDS layer snippets.
- XMLTester.xml: Contains XML snippets.
- doxygen-config.in: Doxyfile to configure Doxygen for creating Fast DDS API reference.
If you are interested in making some contributions, either in the form of an issue or a pull request, please refer to our Contribution Guidelines.
Footnotes
-
If the virtual environment is placed within the colcon workspace, it is recommended to add an empty
COLCON_IGNOREfile in the root of the virtual environment so that colcon does not inspect it. ↩
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent