Python binding for Eclipse Cyclone DDS

A Python binding for Eclipse Cyclone DDS.

Getting Started

Eclipse CycloneDDS Python requires Python version 3.7 or higher. You can install with included Cyclone DDS binaries or leveraging an existing Cyclone DDS installation by installing from source via PyPi.

Installing with pre-built Cyclone DDS binaries

This is the most straightforward method to install Cyclone DDS Python, but there are a couple of caveats. The pre-built package:

• has no support for DDS Security,
• has no support for shared memory via Iceoryx,
• comes with generic Cyclone DDS binaries that are not optimized per-platform.

If these are of concern, proceed with an installation from source. If not, running this installation is as simple as:

    $ pip install cyclonedds

Installing from source

When installing from source you can make use of the full list of features offered by Cyclone DDS. First install Cyclone DDS as normal. Then continue by setting the CYCLONEDDS_HOME environment variable to the installation location of Cyclone DDS, which is the same as what was used for CMAKE_INSTALL_PREFIX. You will have to have this variable active any time you run Python code that depends on cyclonedds so adding it to .bashrc on Linux, ~/bash_profile on MacOS or the System Variables in Windows can be helpful. This also allows you to switch, move or update Cyclone DDS without recompiling the Python package.

via PyPi

You can install the source from the latest release from pypi, or use a tag to get a specific version. A full example (for linux) is shown below

$ git clone https://github.com/eclipse-cyclonedds/cyclonedds
$ cd cyclonedds && mkdir build install && cd build
$ cmake .. -DCMAKE_INSTALL_PREFIX=../install
$ cmake --build . --target install
$ cd ..
$ export CYCLONEDDS_HOME="$(pwd)/install"
$ pip3 install cyclonedds --no-binary cyclonedds

via git

A full example installation of the quickest way to get started via git is shown below:

$ git clone https://github.com/eclipse-cyclonedds/cyclonedds
$ cd cyclonedds && mkdir build install && cd build
$ cmake .. -DCMAKE_INSTALL_PREFIX=../install
$ cmake --build . --target install
$ cd ..
$ export CYCLONEDDS_HOME="$(pwd)/install"
$ pip3 install git+https://github.com/eclipse-cyclonedds/cyclonedds-python

Extra dependencies

The cyclonedds package defines two sets of optional dependencies, dev and docs, used for developing cyclonedds and building the documentation, respectively. If you want to install with development tools add the component to your installation, for example:

$ pip3 install --user "cyclonedds[dev] @ git+https://github.com/eclipse-cyclonedds/cyclonedds-python"

Or when installing from a local git clone, which is recommended when developing or building the docs:

$ cd /path/to/git/clone
# for development:
$ pip3 install --user ".[dev]"
# for documentation generation
$ pip3 install --user ".[docs]"
# or for both
$ pip3 install --user ".[dev,docs]"

For more information see the packaging guide information on optional dependencies.

IDL compiler

You can also run the idl compiler in Python mode if it the Python package is installed. Simply run idlc -l py file.idl and a Python module with your types will be generated in the current working directory. If you wish to nest the resulting Python module inside an existing package you can specify the path from the intended root. So if you have a package 'wubble' with a submodule 'fruzzy' and want the generated modules and types under there you can do idlc -l py -p py-root-prefix=wubble.fruzzy file.idl.