User Tutorial

See also

Developer Tutorial
Extending RST by adding types or converters

This tutorial explains using RST in programs.

C++

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

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

  1. In the dependencies section:

    <dependencies>
        <dependency>
            <groupId>rsb</groupId>
            <artifactId>rst</artifactId>
            <version>[0.17,0.18-SNAPSHOT)</version>
        </dependency>
        <!-- if sandbox is required -->
        <dependency>
            <groupId>rsb</groupId>
            <artifactId>rst-sandbox</artifactId>
            <version>[0.17,0.18-SNAPSHOT)</version>
        </dependency>
    </dependencies>
    
  2. 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:

$ export PYTHONPATH=PREFIX/lib/python2.7/dist-packages/:PREFIX/lib/python2.7/dist-packages/rst-0.17*.egg:PREFIX/lib/python2.7/dist-packages/rstsandbox-0.17*.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