.. _tutorial:

==========
 Tutorial
==========

C++
===

In order to use the |project| library in a C++ project based on the
CMake build system, add the following lines to you
: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 makes the include directories
available.

In case you also want to use 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} ${RSTSANDBOX_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.

Afterwards you can construct a usual target in `CMake`_ and finally
link it against |project|:

.. code-block:: cmake

   ADD_EXECUTABLE(tester tester.cpp)
   TARGET_LINK_LIBRARIES(tester ${RST_LIBRARIES}) # only stable
   TARGET_LINK_LIBRARIES(tester ${RST_LIBRARIES} ${RSTSANDBOX_LIBRARIES}) # only stable

Java
====

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.

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:

.. code-block:: sh

   export PYTHONPATH=$prefix/lib/python2.7/dist-packages/:$prefix/lib/python2.7/dist-packages/rst-0.7*.egg:$prefix/lib/python2.7/dist-packages/rstsandbox-0.7*.egg:$PYTHONPATH
   python2

.. note::

   The installation path 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``:

.. code-block:: python

   import rst
   import rstsandbox

.. important::

   Always access all types, also the ones originating from
   ``rstsandbox`` 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 types from
   :term:`sandbox` to :term:`stable`, which would otherwise required
   changes to your code.

   E.g. assuming you want to access the type ``rstsandbox.foo.Bar``,
   use the following ``import`` statements in your code:

   .. code-block:: python

      import rst
      import rstsandbox
      from rst.foo.Bar_pb2 import Bar