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

Initial contribution

Browse source
This commit is contained in:
Michiel Beemster 2018-04-10 17:03:59 +02:00
parent 7b5cc4fa59
commit 11d9ce37aa
580 changed files with 155133 additions and 162 deletions
Download patch file Download diff file Expand all files Collapse all files

319
src/docs/GettingStartedGuide/helloworld.rst Normal file
View file

@ -0,0 +1,319 @@
..
Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0 which is available at
http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
v. 1.0 which is available at
http://www.eclipse.org/org/documents/edl-v10.php.
SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
.. _`HelloWorld`:
.. raw:: latex
\newpage
###############################
Building CycloneDDS applications
###############################
.. .. contents::
***********************************
Building the *Hello World!* example
***********************************
To test the :ref:`installation <TestYourInstallation>`, a small
*Hello World!* application is used. This application will also be used
as an introduction to DDS.
This chapter explains how to build this example, without details
regarding the source code. The next chapter will explain what has
to be done to code the *Hello World!* example.
The procedure used to build the *Hello World!* example can also be
used for building your own applications.
:Windows: It is advised to have the CycloneDDS examples component installed (see
:ref:`Windows installation <WindowsInstallMSI>`) when actively
building the CycloneDDS examples on Windows. This chapter refers to the
CycloneDDS examples installed in the User Profile directory on Windows.
:Linux: It is advised to have copied the CycloneDDS examples to a user-friendly
location as described in :ref:`this <CopyLinuxExamplesToUserFriendlyLocation>`
paragraph when actively building the CycloneDDS examples on Linux.
This chapter refers to the CycloneDDS examples installed
in the user-defined location.
Build Files
===========
Three files are available *Hello World!* root directory to support
building the example. Both
:ref:`Windows native <WindowsNativeBuild>` (HelloWorld.sln) and
:ref:`Linux native <LinuxNativeBuild>` (Makefile) build files
will only be available for this *Hello World!* example. All the
other examples make use of the :ref:`CMake <CMakeIntro>` build
system and thus only have the CMakeLists.txt build related file.
.. _`LinuxNativeBuild`:
Linux Native Build
==================
A Linux native :code:`Makefile` is provided in the
:code:`examples/helloworld` directory within the destination location
entered in the
:ref:`vdds_install_examples script <CopyLinuxExamplesToUserFriendlyLocation>`.
In a terminal, go to that directory and type
::
make
The build process should have access to the include files and
the ddsc library. The Makefile expects them to be present at
system default locations so that it can find them automatically.
If this isn't the case on your machine, then please
update the commented out :code:`CFLAGS` and :code:`LDFLAGS` within the
:code:`Makefile` to point to the proper locations.
This will build the HelloworldSubscriber and HelloworldPublisher
executables in the helloworld source directory (not the bin
directory that contains the pre-build binaries).
The *Hello World!* example can now be executed,
like described in :ref:`Test your installation <TestYourInstallation>`,
using the binaries that were just build. Be sure to use the right directories.
.. _`WindowsNativeBuild`:
Windows Native Build
====================
For the Windows Native Build, a Visual Studio solution file is
available in the :code:`examples/helloworld` directory. Use a
file explorer to navigate to that directory and double click on
the :code:`HelloWorld.sln` file. Visual Studio should now start
with the HelloWorld solution that contains three projects.
+----------------------+-------------------------------------------------+
| Project | Description |
+======================+=================================================+
| HelloWorldPublisher | Information to build the example publisher. |
+----------------------+-------------------------------------------------+
| HelloWorldSubscriber | Information to build the example subcriber. |
+----------------------+-------------------------------------------------+
| HelloWorldType | Information to (re)generate |
| | :ref:`HelloWorldData_Msg <HelloWorldDataFiles>` |
| | data type. |
+----------------------+-------------------------------------------------+
Creating the *Hello World!* example executables is as simple as
selecting the required configuration and building the solution.
:code:`helloworld\vs\directories.props` contains the location of where
the CycloneDDS header files and libraries are be placed. These locations
are based on the default installation directory structure. When CycloneDDS
is installed in a different directory, the following paths in
:code:`helloworld\vs\directories.props` should be changed, like:
.. code-block:: xml
<CycloneDDS_lib_dir>C:/Path/To/CycloneDDS/Installation/lib</CycloneDDS_lib_dir>
<CycloneDDS_inc_dir>C:/Path/To/CycloneDDS/Installation/include</CycloneDDS_inc_dir>
<CycloneDDS_idlc_dir>C:/Path/To/CycloneDDS/Installation/share/CycloneDDS/idlc</CycloneDDS_idlc_dir>
To run the example, Visual Studio should run both the publisher
and subscriber simultaneously. It is capable of doing so, but
it's not its default setting. To change it, open the HelloWorld
solution property page by right clicking the solution and
selecting :code:`Properties`. Then go to :code:`Common Properties`
-> :code:`Startup Project`, select :code:`Multiple startup project`
and set :code:`Action "Start"` for HelloWorldPublisher and
HelloWorldSubscriber. Finish the change by selecting :code:`OK`.
Visual Studio is now ready to actually run the *Hello World!*
example, which can be done by selecting :code:`Debug` ->
:code:`Start without debugging`.
Both the HelloworldSubscriber and the HelloworldPublisher will be
started and the HelloworldPublisher will write a message that is
received by the HelloworldSubscriber.
.. _`BuildingWithCMake`:
*******************
Building With CMake
*******************
In the earlier chapters, building the *Hello World!* example is done
natively. However, the *Hello World!* example can also be build using the
`CMake tool <http://cmake.org>`_. This is what is recommended. In fact,
all the other examples don't provide native makefiles, only CMake files.
.. _`CMakeIntro`:
CMake
=====
`CMake <http://cmake.org>`_ is an open-source, cross-platform
family of tools designed to build, test and package software.
CMake is used to control the software compilation process using
simple platform and compiler independent configuration files,
and generate native makefiles and workspaces that can be used
in the compiler environment of your choice.
In other words, CMake's main strength is build portability.
CMake uses the native tools, and other than requiring itself,
does not require any additional tools to be installed. The same
CMake input files will build with GNU make, Visual studio 6,7,8
IDEs, borland make, nmake, and XCode.
An other advantage of CMake is building out-of-source. It simply
works out-of-the-box. There are two important reasons to choose
this:
1. Easy cleanup (no cluttering the source tree). Simply remove
the build directory if you want to start from scratch.
2. Multiple build targets. It's possible to have up-to-date
Debug and Release targets, without having to recompile the
entire tree. For systems that do cross-platform compilation,
it is easy to have up-to-date builds for the host and target
platform.
There are a few other benefits to CMake, but that is out of the
scope of this document.
.. _`CycloneDdsPackage`:
Hello World! CMake (CycloneDDS Package)
======================================
After the CMake digression, we're back with the *Hello World!*
example. Apart from the native build files, CMake build files
are provided as well. See
:code:`examples/helloworld/CMakeLists.txt`
.. literalinclude:: ../../examples/helloworld/CMakeLists.export
:linenos:
:language: cmake
It will try to find the :code:`CycloneDDS` CMake package. When it
has found it, every path and dependencies are automatically set.
After that, an application can use it without fuss. CMake will
look in the default locations for the code:`CycloneDDS` package.
.. _`IdlcGenerate`:
The :code:`CycloneDDS` package provides the :code:`ddsc` library
that contains the DDS API that the application needs. But apart
from that, it also contains helper functionality
(:code:`idlc_generate`) to generate library targets from IDL
files. These library targets can be easily used when compiling
an application that depends on a data type described
in an IDL file.
Two applications will be created, :code:`HelloworldPublisher`
and :code:`HelloworldSubscriber`. Both consist only out of one
source file.
Both applications need to be linked to the :code:`ddsc` library
in the :code:`CycloneDDS` package and :code:`HelloWorldData_lib`
that was generated by the call to :code:`idlc_generate`.
.. _`HelloWorldBuilding`:
Hello World! Configuration
==========================
The *Hello World!* example is prepared to be built by CMake
through the use of its :code:`CMakeLists.txt` file. The first
step is letting CMake configure the build environment.
It's good practice to build examples or applications
out-of-source. In order to do that, create a :code:`build`
directory in the :code:`examples/helloworld` directory and go
there, making our location :code:`examples/helloworld/build`.
Here, we can let CMake configure the build environment for
us by typing:
::
cmake ../
.. note::
CMake does a pretty good job at guessing which generator to use, but some
environments require that you supply a specific generator. For example, only
64-bit libraries are shipped for Windows, but CMake will generate a 32-bit
project by default, resulting in linker errors. When generating a
Visual Studio project keep in mind to append **Win64** to the generator.
The example below shows how to generate a Visual Studio 2015 project.
::
cmake -G "Visual Studio 14 2015 Win64" ..
.. note::
CMake generators can also create IDE environments. For instance,
the "Visual Studio 14 2015 Win64" will generate a Visual Studio
solution file. Other IDE's are also possible, like Eclipse.
CMake will use the CMakeLists.txt in the helloworld directory
to create makefiles that fit the native platform.
Since everything is prepared, we can actually build the
applications (HelloworldPublisher and HelloworldSubscriber in
this case).
Hello World! Build
==================
After the configuration step, building the example is as easy
as typing:
::
cmake --build .
.. note::
On Windows, it is likely that you have to supply the config
of Visual Studio:
::
cmake --build . --config "Release"
while being in the build directory created during the
configuration step: :code:`examples/helloworld/build`.
The resulting Publisher and Subscriber applications can be found
in:
:Windows: :code:`examples\helloworld\build\Release`.
:Linux: :code:`examples/helloworld/build`.
The *Hello World!* example can now be executed,
like described in :ref:`Test your installation <TestYourInstallation>`,
using the binaries that were just build. Be sure to use the right directories.
*******
Summary
*******
We've seen that a CycloneDDS application can be build by using a Makefile on Linux
or a Visual Studio Solutions on Windows. Also CMake can be used to build a CycloneDDS
application. In fact, it is the preferred way of building.
In the end, a predefined way of generating and building the source code should
be followed when building CycloneDDS applications. The figure below shows how a
typical CycloneDDS application is build.
.. image:: ../_static/pictures/BuildSchema.png
:scale: 30 %
:align: center
Next chapter will provide an overview of all steps mentioned in the figure above.

438
src/docs/GettingStartedGuide/helloworld_indepth.rst Normal file
View file

@ -0,0 +1,438 @@
..
Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0 which is available at
http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
v. 1.0 which is available at
http://www.eclipse.org/org/documents/edl-v10.php.
SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
.. _`HelloWorldInDepth`:
.. raw:: latex
\newpage
###########################
Hello World! in more detail
###########################
.. .. contents::
The previous chapter focused on building the *Hello World!* example while
this chapter will focus on the code itself; what has to be done to code
this small example.
.. _`HelloWorldDataType`:
*********************
Hello World! DataType
*********************
Data-Centric Architecture
=========================
By creating a Data-centric architecture, you get a loosely
coupled information-driven system. It emphasizes a data layer
that is common for all distributed applications within the
system. Because there is no direct coupling among the
applications in the DDS model, they can be added and removed
easily in a modular and scalable manner. This makes that the
complexity of a data-centric architecture doesn't really
increase when more and more publishers/subscribers are added.
The *Hello World!* example has a very simple 'data layer' of only
one data type :code:`HelloWorldData_Msg` (please read on).
The subscriber and publisher are not aware of each other.
The former just waits until somebody provides the data it
requires, while the latter just publishes the data without
considering the number of interested parties. In other words,
it doesn't matter for the publisher if there are none or
multiple subscribers (try running the *Hello World!* example
by starting multiple HelloworldSubscribers before starting a
HelloworldPublisher). A publisher just writes the data. The
DDS middleware takes care of delivering the data when needed.
******************
HelloWorldData.idl
******************
To be able to sent data from a writer to a reader, DDS needs to
know the data type. For the *Hello World!* example, this data type
is described using `IDL <http://www.omg.org/gettingstarted/omg_idl.htm>`_
and is located in HelloWorldData.idl. This IDL file will be compiled by
a IDL compiler which in turn generates a C language source and header
file. These generated source and header file will be used by the
HelloworldSubscriber and HelloworldPublisher in order to communicate
the *Hello World!* message between the HelloworldPublisher
and the HelloworldSubscriber.
Hello World! IDL
================
There are a few ways to describe the structures that make up the
data layer. The HelloWorld uses the IDL language to describe the
data type in HelloWorldData.idl:
.. literalinclude:: ../../examples/helloworld/HelloWorldData.idl
:linenos:
:language: idl
An extensive explanation of IDL lies outside the scope of this
example. Nevertheless, a quick overview of this example is given
anyway.
First, there's the :code:`module HelloWorldData`. This is a kind
of namespace or scope or similar.
Within that module, there's the :code:`struct Msg`. This is the
actual data structure that is used for the communication. In
this case, it contains a :code:`userID` and :code:`message`.
The combination of this module and struct translates to the
following when using the c language.
::
typedef struct HelloWorldData_Msg
{
int32_t userID;
char * message;
} HelloWorldData_Msg;
When it is translated to a different language, it will look
different and more tailored towards that language. This is the
advantage of using a data oriented language, like IDL, to
describe the data layer. It can be translated into different
languages after which the resulting applications can communicate
without concerns about the (possible different) programming
languages these application are written in.
.. _`IdlCompiler`:
Generate Sources and Headers
============================
Like already mentioned in the `Hello World! IDL`_ chapter, an IDL
file contains the description of data type(s). This needs to be
translated into programming languages to be useful in the
creation of DDS applications.
To be able to do that, there's a pre-compile step that actually
compiles the IDL file into the desired programming language.
A java application :code:`org.eclipse.cyclonedds.compilers.Idlc`
is supplied to support this pre-compile step. This is available
in :code:`idlc-jar-with-dependencies.jar`
The compilation from IDL into c source code is as simple as
starting that java application with an IDL file. In the case of
the *Hello World!* example, that IDL file is HelloWorldData.idl.
::
java -classpath "<install_dir>/share/CycloneDDS/idlc/idlc-jar-with-dependencies.jar" org.eclipse.cyclonedds.compilers.Idlc HelloWorldData.idl
:Windows: The :code:`HelloWorldType` project within the HelloWorld solution.
:Linux: The :code:`make datatype` command.
This will result in new :code:`generated/HelloWorldData.c` and
:code:`generated/HelloWorldData.h`
files that can be used in the *Hello World!* publisher and
subscriber applications.
The application has to be rebuild when the data type source
files were re-generated.
Again, this is all for the native builds. When using CMake, all
this is done automatically.
.. _`HelloWorldDataFiles`:
HelloWorldData.c & HelloWorldData.h
===================================
As described in the :ref:`Hello World! DataType <HelloWorldDataType>`
paragraph, the IDL compiler will generate this source and header
file. These files contain the data type of the messages that are sent
and received.
While the c source has no interest for the application
developers, HelloWorldData.h contains some information that they
depend on. For example, it contains the actual message structure
that is used when writing or reading data.
::
typedef struct HelloWorldData_Msg
{
int32_t userID;
char * message;
} HelloWorldData_Msg;
It also contains convenience macros to allocate and free memory
space for the specific data types.
::
HelloWorldData_Msg__alloc()
HelloWorldData_Msg_free(d,o)
It contains an extern variable that describes the data type to
the DDS middleware as well.
::
HelloWorldData_Msg_desc
***************************
Hello World! Business Logic
***************************
Apart from the
:ref:`HelloWorldData data type files <HelloWorldDataFiles>` that
the *Hello World!* example uses to send messages, the *Hello World!*
example also contains two (user) source files
(:ref:`subscriber.c <HelloWorldSubscriberSource>` and
:ref:`publisher.c <HelloWorldPublisherSource>`), containing the
business logic.
.. _`HelloWorldSubscriberSource`:
*Hello World!* Subscriber Source Code
=====================================
Subscriber.c contains the source that will wait for a *Hello World!*
message and reads it when it receives one.
.. literalinclude:: ../../examples/helloworld/subscriber.c
:linenos:
:language: c
We will be using the DDS API and the
:ref:`HelloWorldData_Msg <HelloWorldDataFiles>` type
to receive data. For that, we need to include the
appropriate header files.
::
#include "ddsc/dds.h"
#include "HelloWorldData.h"
The main starts with defining a few variables that will be used for
reading the *Hello World!* message.
The entities are needed to create a reader.
::
dds_entity_t participant;
dds_entity_t topic;
dds_entity_t reader;
Then there are some buffers that are needed to actually read the
data.
::
HelloWorldData_Msg *msg;
void *samples[MAX_SAMPLES];
dds_sample_info_t info[MAX_SAMPLES];
To be able to create a reader, we first need a participant. This
participant is part of a specific communication domain. In the
*Hello World!* example case, it is part of the default domain.
::
participant = dds_create_participant (DDS_DOMAIN_DEFAULT, NULL, NULL);
The another requisite is the topic which basically describes the
data type that is used by the reader. When creating the topic,
the :ref:`data description <HelloWorldDataFiles>` for the DDS
middleware that is present in the
:ref:`HelloWorldData.h <HelloWorldDataFiles>` is used.
The topic also has a name. Topics with the same data type
description, but with different names, are considered
different topics. This means that readers/writers created with a
topic named "A" will not interfere with readers/writers created
with a topic named "B".
::
topic = dds_create_topic (participant, &HelloWorldData_Msg_desc,
"HelloWorldData_Msg", NULL, NULL);
When we have a participant and a topic, we then can create
the reader. Since the order in which the *Hello World!* Publisher and
*Hello World!* Subscriber are started shouldn't matter, we need to create
a so called 'reliable' reader. Without going into details, the reader
will be created like this
::
dds_qos_t *qos = dds_qos_create ();
dds_qset_reliability (qos, DDS_RELIABILITY_RELIABLE, DDS_SECS (10));
reader = dds_create_reader (participant, topic, qos, NULL);
dds_qos_delete(qos);
We are almost able to read data. However, the read expects an
array of pointers to valid memory locations. This means the
samples array needs initialization. In this example, we have
an array of only one element: :code:`#define MAX_SAMPLES 1`.
So, we only need to initialize one element.
::
samples[0] = HelloWorldData_Msg__alloc ();
Now everything is ready for reading data. But we don't know if
there is any data. To simplify things, we enter a polling loop
that will exit when data has been read.
Within the polling loop, we do the actual read. We provide the
initialized array of pointers (:code:`samples`), an array that
holds information about the read sample(s) (:code:`info`), the
size of the arrays and the maximum number of samples to read.
Every read sample in the samples array has related information
in the info array at the same index.
::
ret = dds_read (reader, samples, info, MAX_SAMPLES, MAX_SAMPLES);
The :code:`dds_read` function returns the number of samples it
actually read. We can use that to determine if the function actually
read some data. When it has, then it is still possible that the
data part of the sample is not valid. This has some use cases
when there is no real data, but still the state of the related
sample has changed (for instance it was deleted). This will
normally not happen in the *Hello World!* example. But we check
for it anyway.
::
if ((ret > 0) && (info[0].valid_data))
If data has been read, then we can cast the void pointer to the
actual message data type and display the contents. The polling
loop is quit as well in this case.
::
msg = (HelloWorldData_Msg*) samples[0];
printf ("=== [Subscriber] Received : ");
printf ("Message (%d, %s)\n", msg->userID, msg->message);
break;
When data is received and the polling loop is stopped, we need to
clean up.
::
HelloWorldData_Msg_free (samples[0], DDS_FREE_ALL);
dds_delete (participant);
All the entities that are created using the participant are also
deleted. This means that deleting the participant will
automatically delete the topic and reader as well.
.. _`HelloWorldPublisherSource`:
*Hello World!* Publisher Source Code
====================================
Publisher.c contains the source that will write an *Hello World!* message
on which the subscriber is waiting.
.. literalinclude:: ../../examples/helloworld/publisher.c
:linenos:
:language: c
We will be using the DDS API and the
:ref:`HelloWorldData_Msg <HelloWorldDataFiles>` type
to sent data. For that, we need to include the
appropriate header files.
::
#include "ddsc/dds.h"
#include "HelloWorldData.h"
Just like with the
:ref:`reader in subscriber.c <HelloWorldSubscriberSource>`,
we need a participant and a topic to be able to create a writer.
We use the same topic name as in subscriber.c. Otherwise the
reader and writer are not considered related and data will not
be sent between them.
::
dds_entity_t participant;
dds_entity_t topic;
dds_entity_t writer;
participant = dds_create_participant (DDS_DOMAIN_DEFAULT, NULL, NULL);
topic = dds_create_topic (participant, &HelloWorldData_Msg_desc,
"HelloWorldData_Msg", NULL, NULL);
writer = dds_create_writer (participant, topic, NULL, NULL);
The DDS middleware is a publication/subscription implementation.
This means that it will discover related readers and writers
(i.e. readers and writers sharing the same data type and topic name)
and connect them so that written data can be received by readers
without the application having to worry about it. There is a catch though:
this discovery and coupling takes a small amount of
time. There are various ways to work around this problem. The following
can be done to properly connect readers and writers:
* Wait for the publication/subscription matched events
* The Subscriber should wait for a subscription matched event
* The Publisher should wait for a publication matched event.
The use of these events will be outside the scope of this example
* Poll for the publication/subscription matches statusses
* The Subscriber should poll for a subscription matched status to be set
* The Publisher should poll for a publication matched status to be set
The Publisher in this example uses the polling schema.
* Let the publisher sleep for a second before writing a sample. This
is not recommended since a second may not be enough on several networks
* Accept that the reader miss a few samples at startup. This may be
acceptable in cases where the publishing rate is high enough.
As said, the publisher of this example polls for the publication matched status.
To make this happen, the writer must be instructed to 'listen' for this status.
The following line of code makes sure the writer does so.
::
dds_set_enabled_status(writer, DDS_PUBLICATION_MATCHED_STATUS);
Now the polling may start:
::
while(true)
{
uint32_t status;
ret = dds_get_status_changes (writer, &status);
DDS_ERR_CHECK(ret, DDS_CHECK_REPORT | DDS_CHECK_EXIT);
if (status == DDS_PUBLICATION_MATCHED_STATUS) {
break;
}
/* Polling sleep. */
dds_sleepfor (DDS_MSECS (20));
}
After this loop, we are sure that a matching reader has been started.
Now, we commence to writing the data. First the data must be initialized
::
HelloWorldData_Msg msg;
msg.userID = 1;
msg.message = "Hello World";
Then we can actually sent the message to be received by the
subscriber.
::
ret = dds_write (writer, &msg);
After the sample is written, we need to clean up.
::
ret = dds_delete (participant);
All the entities that are created using the participant are also
deleted. This means that deleting the participant will
automatically delete the topic and writer as well.

21
src/docs/GettingStartedGuide/index.rst Normal file
View file

@ -0,0 +1,21 @@
..
Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0 which is available at
http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
v. 1.0 which is available at
http://www.eclipse.org/org/documents/edl-v10.php.
SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
.. _`GettingStarted`:
.. toctree::
:maxdepth: 4
installation.rst
helloworld.rst
helloworld_indepth.rst
next_steps.rst
uninstall.rst

208
src/docs/GettingStartedGuide/installation.rst Normal file
View file

@ -0,0 +1,208 @@
..
Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0 which is available at
http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
v. 1.0 which is available at
http://www.eclipse.org/org/documents/edl-v10.php.
SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
.. _`Installation`:
.. raw:: latex
\newpage
#################
Install CycloneDDS
#################
.. .. contents::
.. _`SystemRequirements`:
*******************
System requirements
*******************
Currently AdLink CycloneDDS is supported on the following platforms:
+-------------------+--------------+--------------------+
| Operating systems | Architecture | Compiler |
+===================+==============+====================+
| Ubuntu 16.04 LTS | 64-bit | gcc 5.4 or later |
+-------------------+--------------+--------------------+
| Windows 10 | 64 -bit | VS2015 |
+-------------------+--------------+--------------------+
*****
Linux
*****
Ubuntu
======
On Ubuntu and other debian-derived platforms, the product can be installed using a native package.
::
sudo dpkg -i cyclonedds_<version>_<architecture>.deb
sudo dpkg -i cyclonedds-dev_<version>_<architecture>.deb
.. _`CopyLinuxExamplesToUserFriendlyLocation`:
Post install steps
~~~~~~~~~~~~~~~~~~
The installation package installs examples in system directories.
In order to have a better user experience when building the CycloneDDS
examples, it is advised to copy the examples to a user-defined location.
This is to be able to build the examples natively and experiment with
the example source code.
For this, the installation package provides the vdds_install_examples
script, located in /usr/bin.
Create an user writable directory where the examples should go. Navigate
to that directory and execute the script. Answer 'yes' to the questions
and the examples will be installed in the current location.
Type :code:`vdds_install_examples -h` for more information.
Red Hat
=======
Not supported yet (CHAM-326).
Tarball
=======
For more generic Linux installations, different tar-balls (with the same
content) are provided.
+----------------------------------+---------------------------------------+
| Tarball | Description |
+==================================+=======================================+
| CycloneDDS-<version>-Linux.tar.Z | Tar Compress compression. |
+----------------------------------+---------------------------------------+
| CycloneDDS-<version>-Linux.tar.gz | Tar GZip compression. |
+----------------------------------+---------------------------------------+
| CycloneDDS-<version>-Linux.tar.sh | Self extracting Tar GZip compression. |
+----------------------------------+---------------------------------------+
By extracting one of them at any preferred location, CycloneDDS can be used.
.. _`LinuxSetLibPath`:
Paths
=====
To be able to run CycloneDDS executables, the required libraries (like
libddsc.so) need to be available to the executables.
Normally, these are installed in system default locations and it works
out-of-the-box. However, if they are not installed in those locations,
it is possible that the library search path has to be changed.
This can be achieved by executing the command:
::
export LD_LIBRARY_PATH=<install_dir>/lib:$LD_LIBRARY_PATH
*******
Windows
*******
.. _`WindowsInstallMSI`:
MSI
===
The default deployment method on Windows is to install the product using the MSI installer.
The installation process is self-explanatory. Three components are available:
1. a runtime component, containing the runtime libraries
2. a development component, containing the header files, the IDL compiler,
a precompiled Hello Word! example and other examples.
3. an examples component, containing the source code of the CycloneDDS examples.
The runtime and development components are (by default) installed in "Program Files" while
the CycloneDDS example component will be installed in the User Profile directory.
The CycloneDDS example code in the User Profile directory can be changed by the user.
ZIP
===
The Windows installation is also provided as a ZIP file. By extracting it
at any preferred location, CycloneDDS can be used.
.. _`WindowsSetLibPath`:
Paths
~~~~~
To be able to run CycloneDDS executables, the required libraries (like
ddsc.dll) need to be available to the executables.
Normally, these are installed in system default locations and it works
out-of-the-box. However, if they are not installed on those locations,
it is possible that the library search path has to be changed.
This can be achieved by executing the command:
::
set PATH=<install_dir>/bin;%PATH%
.. note::
The MSI installer will add this path to the PATH environment
variable automatically.
.. _`TestYourInstallation`:
**********************
Test your installation
**********************
The installation provides a simple prebuilt :ref:`Hello World! <HelloWorld>` application which
can be run in order to test your installation. The *Hello World!* application consists of two
executables: a so called HelloworldPublisher and a HelloworldSubscriber, typically located in
:code:`/usr/share/CycloneDDS/examples/helloworld/bin` on Linux and in
:code:`C:\Program Files\ADLINK\Cyclone DDS\share\CycloneDDS\examples\helloworld\bin` on Windows.
To run the example application, please open two console windows and navigate to the appropriate
directory in both console windows. Run the HelloworldSubscriber in one of the console windows by the
typing following command:
:Windows: :code:`HelloworldSubscriber.exe`
:Linux: :code:`./HelloworldSubscriber`
and the HelloworldPublisher in the other console window by typing:
:Windows: :code:`HelloworldPublisher.exe`
:Linux: :code:`./HelloworldPublisher`
The output HelloworldPublisher should look like
.. image:: ../_static/pictures/HelloworldPublisherWindows.png
while the HelloworldSubscriber will be looking like this
.. image:: ../_static/pictures/HelloworldSubscriberWindows.png
For more information on how to build this application your own and the code which has
been used, please have a look at the :ref:`Hello World! <HelloWorld>` chapter.
*******
License
*******
TODO: CHAM-325

81
src/docs/GettingStartedGuide/next_steps.rst Normal file
View file

@ -0,0 +1,81 @@
..
Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0 which is available at
http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
v. 1.0 which is available at
http://www.eclipse.org/org/documents/edl-v10.php.
SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
.. _`WhatsNext`:
.. raw:: latex
\newpage
############
What's next?
############
Want to know more about CycloneDDS? Please consider following a tutorial or
visit some of the pages listed below. The Vortex DDS Launcher (provided with
this installation) is also a good starting point.
:Windows: The Vortex DDS Launcher can be started from within the Windows Start Menu
:Linux: Type 'vortexddslauncher' in a console window
*************************
The OMG DDS Specification
*************************
PrismTech (aquired by AdLink) has been an active member of the Object Management
Group® (OMG®) for over several years and is heavily involved in the development of the
DDS specification. Please visit the OMG website at http://www.omg.org and
specifically the
`DDS Getting Started <http://www.omg.org/gettingstarted/omg_idl.htm>`_
page and the `DDS specification <http://www.omg.org/spec/DDS/>`_ itself.
*************************************
AdLink Documentation and Tutorials
*************************************
* `Documentation <http://www.prismtech.com/vortex/resources/documentation>`_
* `DDS Tutorial <http://download.prismtech.com/docs/Vortex/html/ospl/DDSTutorial/index.html>`_
********************************
AdLink on Youtube and Slideshare
********************************
AdLink is also active on Youtube and Slideshare. Please following
the links below to view some interesting videos and presentations.
* `Overview <http://www.prismtech.com/vortex/resources/presentations>`_
* `Vortex Youtube <https://www.youtube.com/channel/UCqADOYgcicDgASLjNxww-Ww>`_
* `Vortex Slideshare <https://www.slideshare.net/prismtech1/presentations>`_
* `Vortex Demo <http://www.prismtech.com/vortex/vortex-demo>`_
**********************
AdLink on Social Media
**********************
* `Twitter (@ADLINKTech_usa) <https://twitter.com/ADLINKTech_usa>`_
* `Facebook <https://www.facebook.com/ADLINKTECH/>`_
* `LinkedIn <https://www.linkedin.com/company/79111/>`_
*****************
The DDS community
*****************
* `The AdLink DDS-community <http://www.prismtech.com/dds-community>`_
* `The AdLink DDS Forum <http://www.prismtech.com/dds-community/community-interaction>`_
*******
Support
*******
* `Knowledge base <https://kb.prismtech.com/>`_
* `Support (registered users) <http://www.prismtech.com/support>`_

67
src/docs/GettingStartedGuide/uninstall.rst Normal file
View file

@ -0,0 +1,67 @@
..
Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0 which is available at
http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
v. 1.0 which is available at
http://www.eclipse.org/org/documents/edl-v10.php.
SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
.. _`Uninstall`:
.. raw:: latex
\newpage
######################
Uninstalling CycloneDDS
######################
*****
Linux
*****
Uninstalling CycloneDDS on Linux can be established by invoking
the following two commands (of which the first is optional):
::
sudo dpkg --remove cyclonedds-dev
sudo dpkg --remove cyclonedds
.. note::
Mind the order in which these commands are run. The development
package (:code:`cyclonedds-dev`) need to be removed first since
it depends on the library version (:code:`cyclonedds`).
*******
Windows
*******
There are two ways to uninstall CycloneDDS from Windows
1. By using the original CycloneDDS :ref:`MSI <WindowsInstallMSI>` file
2. By using Windows "Apps & features"
Original MSI
============
Locate the original CycloneDDS MSI file on your system and start it.
After clicking :code:`Next`, an overview of options appears, amongst which
is the remove option. By clicking :code:`Remove`, all files and folders are
removed, except the CycloneDDS examples (if installed).
Apps & features
===============
Go to :code:`Windows Settings` by clicking the :code:`Settings`-icon ( |settings_icon| )
in the Windows Start Menu. Choose :code:`Apps` in the
:code:`Windows Settings` screen. A list of all installed apps
and programs pops up. Select :code:`CycloneDDS` and choose :code:`Uninstall`.
All installed files and folders will be removed, except the
CycloneDDS examples (if installed).
.. |settings_icon| image:: ../_static/pictures/settings-icon.png
:height: 9
:width: 9