.. _user-tutorial: .. _tutorial: =============== User Tutorial =============== .. seealso:: :ref:`developer-tutorial` Extending |project| by adding :term:`types ` or :term:`converters ` This tutorial explains using |project| in programs. .. _user-tutorial-cpp: C++ === #. In order to use the |project| library in a C++ project based on the `CMake`_ build system, add the following lines to your :file:`CMakeLists.txt` file: .. code-block:: cmake FIND_PACKAGE(RST REQUIRED) INCLUDE_DIRECTORIES(BEFORE SYSTEM ${RST_INCLUDE_DIRS}) ADD_DEFINITIONS(${RST_CFLAGS}) This will search for |project| and make its include directories available. In case you also want to use :term:`data types ` from the :term:`sandbox`, use these lines instead: .. code-block:: cmake 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 |project| :term:`data types `, statements along the following lines have to be added: .. code-block:: cmake ADD_EXECUTABLE(tester tester.cpp) TARGET_LINK_LIBRARIES(tester ${RST_LIBRARIES}) To enable use of :term:`data types ` from the :term:`sandbox`, use these statements instead: .. code-block:: cmake ADD_EXECUTABLE(tester tester.cpp) TARGET_LINK_LIBRARIES(tester ${RST_LIBRARIES} ${RSTSANDBOX_LIBRARIES}) .. _user-tutorial-java: Java ==== Installed JAR files ------------------- Add :file:`rst.jar` and if you need :term:`sandbox` types :file:`rstsandbox.jar` to your project's classpath. These jars are installed under :samp:`{PREFIX}/share/java/`, where :samp:`{PREFIX}` was chosen by you during the installation as described in :ref:`installation`. |project| 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 |project|. Maven Artifacts from the CITEC Repository ----------------------------------------- |project| 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 :file:`pom.xml` of your project. .. edit-on-version-bump: Change version of dependencies to something like [0.7,0.8-SNAPSHOT) disable snapshots #. In the dependencies section: .. code-block:: xml rsb rst 0.19-SNAPSHOT rsb rst-sandbox 0.19-SNAPSHOT #. In the repositories section: .. code-block:: xml citec-releases CITEC Maven Repository Server https://mvn.cit-ec.de/nexus/content/repositories/releases/ default true citec-snapshots CITEC Maven Repository Server https://mvn.cit-ec.de/nexus/content/repositories/snapshots/ default true .. _user-tutorial-python: Python ====== The installation installs Python `eggs` to :samp:`{PREFIX}/lib/python2.7/dist-packages/` or :samp:`{PREFIX}/lib/python2.7/site-packages/` (depending on your Python installation, watch the `CMake`_ installation output), where :samp:`{PREFIX}` was chosen by you during the installation as described in :ref:`installation`. Add this path to your :envvar:`PYTHONPATH` as well as all contained ``*.egg`` files, e.g. by executing this code before launching the Python interpreter: .. parsed-literal:: $ export :envvar:`PYTHONPATH`\ =\ :samp:`{PREFIX}`/lib/python2.7/dist-packages/::samp:`{PREFIX}`/lib/python2.7/dist-packages/rst-\ |version|\ \*.egg::samp:`{PREFIX}`/lib/python2.7/dist-packages/rstsandbox-\ |version|\ \*.egg:$\ :envvar:`PYTHONPATH` $ python2 .. note:: The installation path :samp:`{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 :py:mod:`rst` and optionally :py:mod:`rstsandbox`: .. code-block:: python import rst import rstsandbox .. important:: Always access all types, also the ones contained in the :py:mod:`rstsandbox` module, through the :py:mod:`rst` module. We have implemented special support for this non-standard behavior. By doing so, you shield your Python project against potential moves of :term:`data types ` from :term:`sandbox` to :term:`stable`, which would otherwise require changes to your code. E.g. assuming you want to access the :term:`sandbox` :term:`data type` ``rst.foo.Bar``, use the following ``import`` statements in your code: .. code-block:: python import rst import rstsandbox from rst.foo.Bar_pb2 import Bar