Skip to content

Commit

Permalink
Update README and set project status to Production in setup.py
Browse files Browse the repository at this point in the history
  • Loading branch information
@thijsmie @eboasson
thijsmie authored and eboasson committed Apr 11, 2022
1 parent 8ecafd9 commit 64d912f
Show file tree
Hide file tree
Showing 3 changed files with 64 additions and 57 deletions.
109 changes: 58 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,41 @@
[![License](https://img.shields.io/badge/License-EPL%202.0-blue)](https://choosealicense.com/licenses/epl-2.0/)
[![License](https://img.shields.io/badge/License-EDL%201.0-blue)](https://choosealicense.com/licenses/edl-1.0/)
[![Website](https://img.shields.io/badge/web-cyclonedds.io-blue)](https://cyclonedds.io)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cyclonedds)](https://pypi.org/project/cyclonedds/)
[![PyPI](https://img.shields.io/pypi/v/cyclonedds)](https://pypi.org/project/cyclonedds/)
[![Community](https://img.shields.io/badge/discord-join%20community-5865f2)](https://discord.gg/BkRYQPpZVV)

# Python binding for Eclipse Cyclone DDS

A **work in progress** Python binding for [Eclipse Cyclone DDS][1].
A Python binding for [Eclipse Cyclone DDS][1].

# Getting Started

Eclipse CycloneDDS Python requires Python version 3.7 or higher. You can install it directly from the git repo with pip or clone the git repo first and then install locally. When it is released it will be installable [with included Cyclone DDS binaries](#installing-with-pre-built-binaries) or leveraging an existing Cyclone DDS installation by [installing from source](#installing-from-source) via PyPi.
Eclipse CycloneDDS Python requires Python version 3.7 or higher. You can install [with included Cyclone DDS binaries](#installing-with-pre-built-binaries) or leveraging an existing Cyclone DDS installation by [installing from source](#installing-from-source) via PyPi.

<!----><a name="installing-with-pre-built-binaries"></a>
## Installing with pre-built Cyclone DDS binaries

## Installing from source via git
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.

To install CycloneDDS Python you will have to install [Cyclone DDS][1] first. Then set appropriate environment variables and install with pip. A full example installation of the quickest way to get started is shown below:
If these are of concern, proceed with an [installation from source](#installing-from-source). If not, running this installation is as simple as:

```bash
$ pip install cyclonedds
```

<!----><a name="installing-from-source"></a>
## Installing from source

When installing from source you can make use of the full list of features offered by [Cyclone DDS][1]. First install [Cyclone DDS][1] as normal. Then continue by setting the `CYCLONEDDS_HOME` environment variable to the installation location of [Cyclone DDS][1], 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][1] without recompiling the Python package.

<!----><a name="installing-from-source-via-pypi"></a>
### 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

```bash
$ git clone https://github.com/eclipse-cyclonedds/cyclonedds
Expand All @@ -21,66 +44,50 @@ $ cmake .. -DCMAKE_INSTALL_PREFIX=../install
$ cmake --build . --target install
$ cd ..
$ export CYCLONEDDS_HOME="$(pwd)/install"
$ pip3 install --user git+https://github.com/eclipse-cyclonedds/cyclonedds-python
$ pip3 install cyclonedds --no-binary cyclonedds
```

If you want to install with development tools add the `[dev]` component to your installation like so:

```bash
$ pip3 install --user "cyclonedds[dev] @ git+https://github.com/eclipse-cyclonedds/cyclonedds-python"
```
<!----><a name="installing-from-source-via-git"></a>
### via git

Installation from a local git clone:
A full example installation of the quickest way to get started via git is shown below:

```bash
$ cd /path/to/git/clone
$ pip3 install --user .
# or for development:
$ pip3 install --user .[dev]
# or for documentation generation
$ pip3 install --user .[docs]
$ 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
```

While the quickest way to get going is the `--user` flag it is not the recommended, we recommend using [a virtual environment][2], [poetry][3], [pipenv][4] or [pyenv][5]. After the installation is complete `import cyclonedds` should now work. Have a look at the [examples](examples/) to learn about how to use the Python API.
# Extra dependencies

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`.

## When released: Installing with pre-built Cyclone DDS binaries

⚠️ As long as this is unreleased this method is not yet available, please refer to the installation from source via git. ⚠️

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](#installing-from-source). If not, running this installation is as simple as:

$ pip install cyclonedds
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:

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

If you get permission errors you are using your system python. This is not recommended, we recommend using [a virtual environment][2], [poetry][3], [pipenv][4] or [pyenv][5]. If you _just_ want to get going, you can add `--user` to your pip command to install for the current user. See the [Installing Python Modules][6] Python documentation.


## When released: Installing from source via PyPi

⚠️ As long as this is unreleased this method is not yet available, please refer to the installation from source via git. ⚠️

When installing from source you can make use of the full list of features offered by [Cyclone DDS][1]. First install [Cyclone DDS][1] as normal. Then continue by setting the `CYCLONEDDS_HOME` environment variable to the installation location of [Cyclone DDS][1], 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][1] without recompiling the Python package.
Or when installing from a local git clone, which is recommended when developing or building the docs:

You can either install the source from the latest release from pypi (not yet available):
```bash
$ 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]"
```

$ CMAKE_PREFIX_PATH="/path/to/cyclone" pip install cyclonedds --no-binary cyclonedds
For more information see [the packaging guide information on optional dependencies][2].

or you can download the code from this repository to get the bleeding edge and directly install from your local filesystem:
# IDL compiler

$ CMAKE_PREFIX_PATH="/path/to/cyclone" pip install git+https://github.com/eclipse-cyclonedds/cyclonedds-python
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`.

If you get permission errors you are using your system python. This is not recommended, we recommend using [a virtual environment][2], [poetry][3], [pipenv][4] or [pyenv][5]. If you _just_ want to get going, you can add `--user` to your pip command to install for the current user. See the [Installing Python Modules][6] Python documentation.

[1]: https://github.com/eclipse-cyclonedds/cyclonedds/
[2]: https://docs.python.org/3/tutorial/venv.html
[3]: https://python-poetry.org/
[4]: https://pipenv.pypa.io/en/latest/
[5]: https://github.com/pyenv/pyenv
[6]: https://docs.python.org/3/installing/index.html
[1]: https://github.com/eclipse-cyclonedds/cyclonedds/#eclipse-cyclone-dds
[2]: https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies
10 changes: 5 additions & 5 deletions docs/source/intro.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,29 +10,29 @@ This is the documentation for Eclipse Cyclone DDS Python, wrapping the `Eclipse
Prerequisites
-------------

CycloneDDS Python requires Python version 3.7 or higher, with 3.11 support provisional. When CycloneDDS Python gets an official release the wheels on Pypi will contain a pre-built binary of the CycloneDDS C library and IDL compiler. These have a couple of caveats. The pre-built package:
CycloneDDS Python requires Python version 3.7 or higher, with 3.11 support provisional. The wheels on PyPi contain a pre-built binary of the CycloneDDS C library and IDL compiler. These have 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.

As long as it is not fully released you will have to build from source, requiring your own CycloneDDS installation. While installing the CycloneDDS Python library you need to set the environment variable ``CMAKE_PREFIX_PATH`` to allow the installer to locate the CycloneDDS C library if it is on a non-standard path, as with all CMake projects. At runtime we leverage several mechanisms to locate the library that are appropriate for the platform, such as ``LD_LIBRARY_PATH`` on linux and the Windows Registry CMake registry. If you get an exception about non-locatable libraries or wish to manage multiple CycloneDDS installations you can use the environment variable ``CYCLONEDDS_HOME`` to override the load location.
If you need these features or cannot use the binaries for other reasons you can install the Cyclone DDS Python library from source. You will need to set the environment variable ``CYCLONEDDS_HOME`` to allow the installer to locate the CycloneDDS C library if it is on a non-standard path. At runtime we leverage several mechanisms to locate the library that are appropriate for the platform. If you get an exception about non-locatable libraries or wish to manage multiple CycloneDDS installations you can use the environment variable ``CYCLONEDDS_HOME`` to override the load location.

Installation
------------

Pre-built binary installation from Pypi will be possible once released:
Simply install with pip from PyPi.

.. code-block:: shell
pip install cyclonedds
Right now you will need to install from source. You can install from the github link directly:
You can install from the github link directly:

.. code-block:: shell
CMAKE_PREFIX_PATH="/path/to/cyclonedds" pip install https://github.com/eclipse-cyclonedds/cyclonedds-python
CYCLONEDDS_HOME="/path/to/cyclonedds" pip install git+https://github.com/eclipse-cyclonedds/cyclonedds-python
If you wish to run the testsuite or build the documentation you will need additional dependencies. These can be installed by means of Python installation optional components:
Expand Down
2 changes: 1 addition & 1 deletion setup.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@
"idl", "middleware", "ros"
],
classifiers=[
"Development Status :: 4 - Beta",
"Development Status :: 5 - Production/Stable",
"License :: OSI Approved :: Eclipse Public License 2.0 (EPL-2.0)",
"Programming Language :: Python :: 3.7",
"Programming Language :: Python :: 3.8",
Expand Down

0 comments on commit 64d912f

Please sign in to comment.