|
1 | | -# eProsima Fast RTPS |
| 1 | +# eProsima Fast RTPS Documentation |
2 | 2 |
|
3 | 3 | [](https://github.com/eProsima/Fast-RTPS/releases) |
4 | 4 | [](https://opensource.org/licenses/Apache-2.0) |
5 | 5 | [](http://jenkins.eprosima.com:8080/job/FastRTPS%20Docs%20Nightly%20Master) |
6 | 6 |
|
7 | 7 | <a href="http://www.eprosima.com"><img src="https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcSd0PDlVz1U_7MgdTe0FRIWD0Jc9_YH-gGi0ZpLkr-qgCI6ZEoJZ5GBqQ" align="left" hspace="8" vspace="2" width="100" height="100" ></a> |
8 | 8 |
|
9 | | -*eprosima Fast RTPS* is a C++ implementation of the RTPS (Real Time Publish Subscribe) protocol, which provides publisher-subscriber communications over unreliable transports such as UDP, |
10 | | -as defined and maintained by the Object Management Group (OMG) consortium. RTPS is also the wire interoperability protocol defined for the Data Distribution |
11 | | -Service (DDS) standard, again by the OMG. *eProsima Fast RTPS* holds the benefit of being standalone and up-to-date, as most vendor solutions either implement RTPS as a tool to implement |
12 | | -DDS or use past versions of the specification. |
| 9 | +eprosima Fast RTPS is a C++ implementation of 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, again by the OMG. eProsima Fast RTPS holds the benefit of being standalone and up-to-date, as most vendor solutions either implement RTPS as a tool to implement DDS or use past versions of the specification. |
13 | 10 |
|
14 | | -Some of the main features of this library are: |
| 11 | +For more information about the library, check out the [Fast-RTPS documentation](https://fast-rtps.docs.eprosima.com/en/latest/). |
| 12 | +You can find all the library's source code on our [GitHub repository](https://github.com/eProsima/Fast-RTPS). |
15 | 13 |
|
16 | | -* Configurable best-effort and reliable publish-subscribe communication policies for real-time |
17 | | -applications. |
18 | | -* Plug and play connectivity so that any new applications are automatically discovered by any other |
19 | | -members of the network. |
20 | | -* Modularity and scalability to allow continuous growth with complex and simple devices in the |
21 | | -network. |
22 | | -* Configurable network behavior and interchangeable transport layer: Choose the best protocol and |
23 | | -system input/output channel combination for each deployment. |
24 | | -* Two API Layers: a high-level Publisher-Subscriber one focused on usability and a lower-level Writer-Reader one that provides finer access to the inner workings of the RTPS protocol. |
| 14 | +1. [Installation Guide](#installation-guide) |
| 15 | +1. [Getting Started](#getting-started) |
| 16 | +1. [Generating documentation in other formats](#generating-documentation-in-other-formats) |
| 17 | +1. [Running documentation tests](#running-documentation-tests) |
| 18 | +1. [Simulating Read the Docs](#simulating-read-the-docs) |
25 | 19 |
|
26 | | -*eProsima Fast RTPS* has been adopted by multiple organizations in many sectors including these important cases: |
27 | | - |
28 | | -* Robotics: ROS (Robotic Operating System) as their default middleware for ROS2. |
29 | | -* EU R&D: FIWARE Incubated GE. |
| 20 | +## Installation Guide |
30 | 21 |
|
31 | | -## Supported platforms |
| 22 | +1. In order to build and test the documentation, some dependencies must be installed beforehand: |
32 | 23 |
|
33 | | -* Linux [](http://jenkins.eprosima.com:8080/job/FastRTPS%20Nightly%20Master%20Security%20Linux) |
34 | | -* Windows [](http://jenkins.eprosima.com:8080/job/FastRTPS%20Nightly%20Master%20Security%20Windows) |
35 | | -* Mac [](http://jenkins.eprosima.com:8080/job/FastRTPS%20Nightly%20Master%20Security%20Mac) |
| 24 | + ```bash |
| 25 | + sudo apt update |
| 26 | + sudo apt install -y \ |
| 27 | + git \ |
| 28 | + gcc \ |
| 29 | + g++ \ |
| 30 | + cmake \ |
| 31 | + curl \ |
| 32 | + wget \ |
| 33 | + libasio-dev \ |
| 34 | + libtinyxml2-dev \ |
| 35 | + doxygen \ |
| 36 | + python3 \ |
| 37 | + python3-pip \ |
| 38 | + python3-venv \ |
| 39 | + python3-sphinxcontrib.spelling \ |
| 40 | + imagemagick |
| 41 | + ``` |
36 | 42 |
|
37 | | -## Installation Guide |
38 | | -You can get either a binary distribution of *eprosima Fast RTPS* or compile the library yourself from source. |
| 43 | +1. Clone the repository |
39 | 44 |
|
40 | | -### Installation from binaries |
41 | | -The latest, up to date binary release of *eprosima Fast RTPS* can be obtained from the <a href='http://www.eprosima.com'>company website</a>. |
| 45 | + ```bash |
| 46 | + cd ~ |
| 47 | + git clone https://github.com/eProsima/Fast-RTPS-docs fastrtps-docs |
| 48 | + ``` |
42 | 49 |
|
43 | | -### Installation from Source |
| 50 | +1. Create a virtual environment and install python3 dependencies |
44 | 51 |
|
45 | | -#### Dependencies |
| 52 | + ```bash |
| 53 | + cd ~/fastrtps-docs |
| 54 | + python3 -m venv fastrtps-docs-venv |
| 55 | + source fastrtps-docs-venv/bin/activate |
| 56 | + pip3 install -r docs/requirements.txt |
| 57 | + ``` |
46 | 58 |
|
47 | | -##### Asio and TinyXML2 libraries |
| 59 | +## Getting Started |
48 | 60 |
|
49 | | -On Linux, you can install these libraries using the package manager of your Linux distribution. |
50 | | -For example, on Ubuntu you can install them by using its package manager with the next command. |
| 61 | +To generate the documentation in a HTML format for a specific branch of Fast-RTPS run: |
51 | 62 |
|
52 | 63 | ```bash |
53 | | -sudo apt install libasio-dev libtinyxml2-dev |
| 64 | +cd ~/fastrtps-docs |
| 65 | +source fastrtps-docs-venv/bin/activate |
| 66 | +make html |
54 | 67 | ``` |
55 | 68 |
|
56 | | -On Windows, you can install these libraries using [Chocolatey](https://chocolatey.org). |
57 | | -First, download the following chocolatey packages from this |
58 | | -[ROS2 Github repository](https://github.com/ros2/choco-packages/releases/latest). |
59 | | - |
60 | | -* asio.1.12.1.nupkg |
61 | | -* tinyxml2.6.0.0.nupkg |
| 69 | +### Selecting Fast-RTPS branch |
62 | 70 |
|
63 | | -Once these packages are downloaded, open an administrative shell and execute the following command: |
| 71 | +It is possible to specify the Fast-RTPS branch for which the documentation is generated via the environment variable `FASTRTPS_BRANCH`. |
64 | 72 |
|
65 | | -```batch |
66 | | -choco install -y -s <PATH\TO\DOWNLOADS\> asio tinyxml2 |
| 73 | +```bash |
| 74 | +cd ~/fastrtps-docs |
| 75 | +source fastrtps-docs-venv/bin/activate |
| 76 | +FASTRTPS_BRANCH=<branch> make help |
67 | 77 | ``` |
68 | 78 |
|
69 | | -Please replace `<PATH\TO\DOWNLOADS>` with the folder you downloaded the packages to. |
| 79 | +## Generating documentation in other formats |
70 | 80 |
|
71 | | -#### Colcon installation |
72 | | -******************* |
73 | | -[colcon](https://colcon.readthedocs.io) is a command line tool to build sets of software packages. |
74 | | -This section explains to use it to compile easily Fast-RTPS and its dependencies. |
75 | | -First install ROS2 development tools (colcon and vcstool): |
| 81 | +The documentation can be generated in several formats such as HTML, PDF, LaTex, etc. For a complete list of targets run: |
76 | 82 |
|
77 | 83 | ```bash |
78 | | -pip install -U colcon-common-extensions vcstool |
| 84 | +cd ~/fastrtps-docs |
| 85 | +make help |
79 | 86 | ``` |
80 | 87 |
|
81 | | -Download the repos file that will be used to download Fast RTPS and its dependencies: |
| 88 | +Once you have selected a format, generate the documentation with: |
82 | 89 |
|
83 | 90 | ```bash |
84 | | -$ wget https://raw.githubusercontent.com/eProsima/Fast-RTPS/master/fastrtps.repos |
85 | | -$ mkdir src |
86 | | -$ vcs import src < fastrtps.repos |
| 91 | +cd ~/fastrtps-docs |
| 92 | +source fastrtps-docs-venv/bin/activate |
| 93 | +FASTRTPS_BRANCH=<branch> make <output_format> |
87 | 94 | ``` |
88 | 95 |
|
89 | | -Finally, use colcon to compile all software: |
90 | | - |
91 | | -```bash |
92 | | -$ colcon build |
93 | | -``` |
| 96 | +## Running documentation tests |
94 | 97 |
|
95 | | -#### Manual installation |
96 | | -******************* |
97 | | -Before compiling manually Fast RTPS you need to clone the following dependencies and compile them using |
98 | | -[CMake](https://cmake.org). |
| 98 | +DISCLAIMER: In order to run documentation tests, access to eProsima's intranet is required. |
99 | 99 |
|
100 | | -* [Fast CDR](https://github.com/eProsima/Fast-CDR.git) |
| 100 | +This repository provides a set of tests that verify that: |
101 | 101 |
|
102 | | - ```bash |
103 | | - $ git clone https://github.com/eProsima/Fast-CDR.git |
104 | | - $ mkdir Fast-CDR/build && cd Fast-CDR/build |
105 | | - $ cmake .. |
106 | | - $ cmake --build . --target install |
107 | | - ``` |
| 102 | +1. The RST follows the style guidelines |
| 103 | +1. The HTML is built correctly |
| 104 | +1. The C++ snippets compile against the library's version |
| 105 | +1. The XML snippets define valid configurations |
108 | 106 |
|
109 | | -* [Foonathan memory](https://github.com/foonathan/memory) |
110 | | - |
111 | | - ```bash |
112 | | - $ git clone https://github.com/foonathan/memory.git |
113 | | - $ cd memory |
114 | | - $ git submodule update --init --recursive |
115 | | - $ mkdir build && cd build |
116 | | - $ cmake .. |
117 | | - $ cmake --build . --target install |
118 | | - ``` |
119 | | - |
120 | | -Once all dependencies are installed, you will be able to compile and install Fast RTPS. |
| 107 | +Run the tests by: |
121 | 108 |
|
122 | 109 | ```bash |
123 | | -$ git clone https://github.com/eProsima/Fast-RTPS.git |
124 | | -$ mkdir Fast-RTPS/build && cd Fast-RTPS/build |
125 | | -$ cmake .. |
126 | | -$ cmake --build . --target install |
| 110 | +cd ~/fastrtps-docs |
| 111 | +source fastrtps-docs-venv/bin/activate |
| 112 | +FASTRTPS_BRANCH=<branch> make test |
127 | 113 | ``` |
128 | 114 |
|
| 115 | +## Simulating Read the Docs |
129 | 116 |
|
130 | | -## Documentation |
131 | | - |
132 | | -You can access the documentation online, which is hosted on [Read the Docs](http://eprosima-fast-rtps.readthedocs.io). |
133 | | - |
134 | | -* [Start Page](http://eprosima-fast-rtps.readthedocs.io) |
135 | | -* [Installation manual](http://eprosima-fast-rtps.readthedocs.io/en/latest/requirements.html) |
136 | | -* [User manual](http://eprosima-fast-rtps.readthedocs.io/en/latest/introduction.html) |
137 | | -* [FastRTPSGen manual](http://eprosima-fast-rtps.readthedocs.io/en/latest/geninfo.html) |
138 | | -* [Release notes](http://eprosima-fast-rtps.readthedocs.io/en/latest/notes.html) |
139 | | - |
140 | | -## Quick Demo |
141 | | - |
142 | | -For those who want to try a quick demonstration of Fast-RTPS libraries on Ubuntu, here is a way to launch an example application. |
| 117 | +Read the Docs generates the documentation using Sphinx and [conf.py](docs/conf.py). |
| 118 | +This means that it does not execute `make` and therefore Fast DDS is not downloaded for API reference documentation generation. |
| 119 | +[conf.py](docs/conf.py) provides some extra logic to download Fast DDS and generate the Doxygen documentation when running on a Read the Docs environment. |
| 120 | +This is done by means of the environment variable `READTHEDOCS`. |
| 121 | +When this variable is set to `True`, [conf.py](docs/conf.py) will clone Fast DDS in `build/code/external/eprosima/src/` (same place as CMake) and will set it to a branch applying the following criteria: |
143 | 122 |
|
144 | | -First, download and install **docker** application. Open a terminal and type the following command |
| 123 | +1. Try to checkout to the branch specified by `FASTRTPS_BRANCH`. |
| 124 | +1. 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. |
| 125 | +1. If the previous fails, fallback to `master`. |
145 | 126 |
|
146 | | - $ sudo apt-get install docker.io |
| 127 | +To simulating Read the Docs operation, make sure you do not have a `build` directory. |
147 | 128 |
|
148 | | -Then, download the docker image file from https://eprosima.com/index.php/downloads-all |
149 | | - |
150 | | -Load the image and run it: |
151 | | - |
152 | | - $ docker load -i ubuntu-fast-rtps.tar |
153 | | - $ docker run -it ubuntu-fast-rtps |
154 | | - |
155 | | -You can run as many images as you want and check the communication between them. |
| 129 | +```bash |
| 130 | +cd ~/fastrtps-docs |
| 131 | +rm -rf build |
| 132 | +``` |
156 | 133 |
|
157 | | -## Getting Help |
| 134 | +Then, set `READTHEDOCS`, `FASTRTPS_BRANCH` and run sphinx: |
158 | 135 |
|
159 | | -If you need support you can reach us by mail at `[email protected]` or by phone at `+34 91 804 34 48`. |
| 136 | +```bash |
| 137 | +READTHEDOCS=True FASTRTPS_BRANCH=<branch> sphinx-build \ |
| 138 | + -b html \ |
| 139 | + -Dbreathe_projects.FastDDS=<abs_path_to_docs_repo>/fastrtps-docs/build/code/doxygen/xml \ |
| 140 | + -d <abs_path_to_docs_repo>/fastrtps-docs/build/doctrees \ |
| 141 | + docs <abs_path_to_docs_repo>/fastrtps-docs/build/html |
| 142 | +``` |
0 commit comments