User Tutorial¶
See also
- Developer Tutorial
- Extending RST by adding types or converters
This tutorial explains using RST in programs.
C++¶
In order to use the RST library in a C++ project based on the CMake build system, add the following lines to your
CMakeLists.txt
file:FIND_PACKAGE(RST REQUIRED) INCLUDE_DIRECTORIES(BEFORE SYSTEM ${RST_INCLUDE_DIRS}) ADD_DEFINITIONS(${RST_CFLAGS})
This will search for RST and make its include directories available.
In case you also want to use data types from the sandbox, use these lines instead:
FIND_PACKAGE(RST REQUIRED COMPONENTS sandbox) INCLUDE_DIRECTORIES(BEFORE SYSTEM ${RST_INCLUDE_DIRS}) ADD_DEFINITIONS(${RST_CFLAGS} ${RSTSANDBOX_CFLAGS})
Important
Do not omit the
ADD_DEFINITIONS
line. Otherwise you end up with hard to interpret compiler errors.For each CMake target using RST data types, statements along the following lines have to be added:
ADD_EXECUTABLE(tester tester.cpp) TARGET_LINK_LIBRARIES(tester ${RST_LIBRARIES})
To enable use of data types from the sandbox, use these statements instead:
ADD_EXECUTABLE(tester tester.cpp) TARGET_LINK_LIBRARIES(tester ${RST_LIBRARIES} ${RSTSANDBOX_LIBRARIES})
Java¶
Installed JAR files¶
Add rst.jar
and if you need sandbox types
rstsandbox.jar
to your project’s classpath. These jars are
installed under PREFIX/share/java/
, where PREFIX
was chosen by you during the installation as described in
Installing RST.
RST depends on Google Protocol Buffers. So make sure that their jar file is also available on the classpath. The version of this jar file must match the version of protoc that was used to compile RST.
Maven Artifacts from the CITEC Repository¶
RST java bindings are also deployed to the CITEC `Maven`_
repository at https://mvn.cit-ec.de/. In order to use the version
deployed there, include the following fragments in the pom.xml
of your project.
In the dependencies section:
<dependencies> <dependency> <groupId>rsb</groupId> <artifactId>rst</artifactId> <version>[0.12,0.13-SNAPSHOT)</version> </dependency> <!-- if sandbox is required --> <dependency> <groupId>rsb</groupId> <artifactId>rst-sandbox</artifactId> <version>[0.12,0.13-SNAPSHOT)</version> </dependency> </dependencies>
In the repositories section:
<repositories> <repository> <id>citec-releases</id> <name>CITEC Maven Repository Server</name> <url>https://mvn.cit-ec.de/nexus/content/repositories/releases/</url> <layout>default</layout> <releases> <enabled>true</enabled> </releases> </repository> <repository> <id>citec-snapshots</id> <name>CITEC Maven Repository Server</name> <url>https://mvn.cit-ec.de/nexus/content/repositories/snapshots/</url> <layout>default</layout> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories>
Python¶
The installation installs Python eggs to
PREFIX/lib/python2.7/dist-packages/
or
PREFIX/lib/python2.7/site-packages/
(depending on your
Python installation, watch the CMake installation output), where
PREFIX
was chosen by you during the installation as
described in Installing RST. Add this path to your
PYTHONPATH
as well as all contained *.egg
files, e.g. by
executing this code before launching the Python interpreter:
$ exportPYTHONPATH
=PREFIX
/lib/python2.7/dist-packages/:PREFIX
/lib/python2.7/dist-packages/rst-0.12*.egg:PREFIX
/lib/python2.7/dist-packages/rstsandbox-0.12*.egg:$PYTHONPATH
$ python2
Note
The installation path PREFIX
mentioned above depends on
your system’s Python 2 version. Please verify this version with
python2 --version
and adapt the path accordingly if necessary.
Inside your Python project you can afterwards import rst
and
optionally rstsandbox
:
import rst
import rstsandbox
Important
Always access all types, also the ones contained in the
rstsandbox
module, through the rst
module. We
have implemented special support for this non-standard behavior. By
doing so, you shield your Python project against potential moves of
data types from sandbox to
stable, which would otherwise require changes to your code.
E.g. assuming you want to access the sandbox data
type rst.foo.Bar
, use the following import
statements in
your code:
import rst
import rstsandbox
from rst.foo.Bar_pb2 import Bar