niklas/cyclonedds
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update README prerequisites and build info

Browse source 
The build information in the README was very limited (now it is less
limited) and, the list of prerequisites was incomplete, documentation
link was out of date ...  This cleans it up a bit.

Signed-off-by: Erik Boasson <eb@ilities.com>
This commit is contained in:
Erik Boasson 2019-02-15 16:20:40 +01:00
parent 76ca027340
commit e54b9ec715
1 changed files with 117 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

143
README.md
View file

@ -1,52 +1,140 @@
# Eclipse Cyclone DDS
Eclipse Cyclone DDS is by far the most performant and robust DDS implementation available on the market.
Beside, Cyclone DDS is developed completely in the open and is undergoing the acceptance process to become part of Eclipse IoT (see [eclipse-cyclone-dds](https://projects.eclipse.org/proposals/eclipse-cyclone-dds)).
Eclipse Cyclone DDS is by far the most performant and robust DDS implementation available on the
market. Moreover, Eclipse Cyclone DDS is developed completely in the open as an Eclipse IoT project
(see [eclipse-cyclone-dds](https://projects.eclipse.org/projects/iot.cyclonedds)).
# Getting Started
## Building Cyclone DDS
In order to build cyclone DDS you need to have installed on your host [cmake](https://cmake.org/download/) **v3.6.0** or higher, the [Java 8 JDK](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) or simply the [Java 8 RE](http://www.oracle.com/technetwork/java/javase/downloads/server-jre8-downloads-2133154.html), and [Apache Maven 3.5.x or higher](http://maven.apache.org/download.cgi).
## Building Eclipse Cyclone DDS
Assuming that **git** is also available on your machine then, simply do:
In order to build Eclipse Cyclone DDS you need a Linux, Mac or Windows 10 machine with the following
installed on your host:
$ git clone https://github.com/eclipse/cyclonedds.git
* [cmake](https://cmake.org/download/), version 3.7 or later. (Version 3.6 should work but you
will have to edit the ``cmake_minimum_required`` version and may have to disable building the
tests.)
* [OpenSSL](https://www.openssl.org/), preferably version 1.1 or later. If you wish, you can
build without support for OpenSSL by setting DDSC\_ENABLE\_OPENSSL to FALSE on the ``cmake ``
command line (i.e., ``cmake -DDDSC_ENABLE_OPENSSL=FALSE`` ../src). In that, there is no need to
have openssl available.
* Java JDK, version 8 or later, e.g., [OpenJDK 11](http://jdk.java.net/11/).
* [Apache Maven 3.5 or higher](http://maven.apache.org/download.cgi), version 3.5 or later.
The Java-based components are the preprocessor and a configurator tool. The run-time libraries are
pure C code, so there is no need to have Java available on "target" machines.
To obtain Eclipse Cyclone DDS, do
$ git clone https://github.com/eclipse-cyclonedds/cyclonedds.git
$ cd cyclonedds
$ mkdir build
Depending on whether you want to develop applications using Eclipse Cyclone DDS or contribute to
Eclipse Cyclone DDS you can follow different procedures
### For application developers
To build and install the required libraries needed to develop your own applications that use Eclipe Cyclone DDS
On Linux:
$ cd build
$ cmake ../src
$ make
$ make install
$ cmake -DCMAKE_INSTALL_PREFIX=<install-location> ../src
$ cmake --build .
At this point you are ready to use **cyclonedds** for your next DDS project!
On Windows:
$ cd build
$ cmake -G "<generator-name>" -DCMAKE_INSTALL_PREFIX=<install-location> ../src
$ cmake --build .
where you should replace ``<install-location>`` by the directory under which you would like to
install Eclipse Cyclone DDS and ``<generator-name>`` by one of the ways
CMake [generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html) offer for
generating build files. For example, "Visual Studio 15 2017 Win64" would target a 64-bit build
using Visual Studio 2017.
To install it after a successful build, do:
$ cmake --build . --target install
which will copy everything to:
* ``<install-location>/lib``
* ``<install-location>/bin``
* ``<install-location>/include/ddsc``
* ``<install-location>/share/CycloneDDS``
* ``<install-location>/etc/CycloneDDS``
Depending on the installation location you may need administrator privileges.
At this point you are ready to use **Cyclone DDS** in your own projects.
Note that the default build type is a release build with debug information included
(RelWithDebInfo), which is generally the most convenient type of build to use from applications
because of a good mix between performance and still being able to debug things. If you'd rather
have a Debug or pure Release build, set ``CMAKE_BUILD_TYPE`` accordingly.
### Contributing to Eclipse Cyclone DDS
We very much welcome all contributions to the project, whether that is questions, examples, bug
fixes, enhancements or improvements to the documentation, or anything else really. When considering
contributing code, it might be good to know that build configurations for Travis CI and AppVeyor are
present in the repository and that there is a test suite using CTest and CUnit that can be built
locally if desired. To build it, set the cmake variable ``BUILD_TESTING`` to on when configuring, e.g.:
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON ../src
$ cmake --build .
$ ctest
Such a build requires the presence of [CUnit](http://cunit.sourceforge.net/). You can install this
yourself, or you can choose to instead rely on the [Conan](https://conan.io) packaging system that
the CI build infrastructure also uses. In that case, install Conan and do:
$ conan install ..
in the build directory prior to running cmake. This will automatically download and/or build cunit
(and, at the moment, openssl).
## Documentation
The Eclipse Cyclone DDS documentation is still rather limited, and at the moment only available in
the sources (in the form of restructured text files in ``src/docs`` and Doxygen comments in the
header files), or as
a
[PDF](https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/assets/pdf/CycloneDDS-0.1.0.pdf). The
intent is to automate the process of building the documentations and have them available in more
convenient formats and in the usual locations.
## Performance
Median small message throughput measured using the Throughput example between two Intel(R) Xeon(R)
CPU E3-1270 V2 @ 3.50GHz (that's 2012 hardware ...) running Linux 3.8.13-rt14.20.el6rt.x86_64,
connected via a quiet GbE and when using gcc-6.2.0 for a RelWithDebInfo build is:
connected via a quiet GbE and when using gcc-6.2.0 for a defuault (i.e., "RelWithDebInfo") build is:
![Throughput](https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/assets/performance/throughput-polling.png)
<img src="https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/assets/performance/throughput-polling.png" alt="Throughput" height="400">
This is with the subscriber in polling mode. Listener mode is marginally slower; using a waitset the
message rate for minimal size messages drops to 600k sample/s in synchronous delivery mode and about
750k samples/s in asynchronous delivery mode. The configuration is an out-of-the-box configuration,
tweaked only to increase the high-water mark for the reliability window on the writer side. For
details, see the scripts in the ``performance`` directory and the [data](https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/assets/performance/throughput.txt).
details, see the scripts in the ``performance`` directory and
the
[data](https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/assets/performance/throughput.txt).
There is some data on roundtrip latency below.
## Examples
Now that you have built and installed **cyclonecdds** it is time to experiment with some examples.
Now that you have built and installed **Cyclone DDS** it is time to experiment with some examples.
### Building and Running the Roundtrip Example
The first example we will show you how to build and run, measures cyclonedds latency and will allow you to see with your eyes how fast it is!
Do as follows:
The first example we will show you how to build and run an example program that measures latency.
The examples are built automatically when you build Cyclone DDS, so you don't need to follow these
steps to be able to run the program, it is merely to illustrate the process.
$ cd cyclonedds/src/examples/roundtrip
$ mkdir build
@ -54,12 +142,11 @@ Do as follows:
$ cmake ..
$ make
Now that you've build the roundtrip example it is time to run it.
On one terminal start the application that will be responding to Cyclone DDS pings:
On one terminal start the applications that will be responding to **cyclonedds** pings.
$ ./RoundtripPong
On another terminal, start the application that will be sending the ping.
On another terminal, start the application that will be sending the pings:
$ ./RoundtripPing 0 0 0
# payloadSize: 0 | numSamples: 0 | timeOut: 0
@ -79,8 +166,12 @@ On another terminal, start the application that will be sending the ping.
9 28242 17 16 24 132 28242 8 6 28242 1 0
10 28075 17 16 23 46 28075 8 6 28075 1 0
The number above were measure on Mac running a 4,2 GHz Intel Core i7 on December 12th 2018. From these number you can see how the roundtrip is incredibly stable and the minimal latency is now down to 17 micro-seconds (used to be 25 micro-seconds) on this HW.
The numbers above were measured on Mac running a 4.2 GHz Intel Core i7 on December 12th 2018. From
these number you can see how the roundtrip is very stable and the minimal latency is now down to 17
micro-seconds (used to be 25 micro-seconds) on this HW.
## Documentation
The Cyclone DDS documentation is available [here](http://cdds.io/docs).
# Trademarks
* "Eclipse Cyclone DDS" and "Cyclone DDS" are trademarks of the Eclipse Foundation.
* "DDS" is a trademark of the Object Management Group, Inc.