.. _user-tutorial:
.. _tutorial:

===============
 User Tutorial
===============

.. seealso::

   :ref:`developer-tutorial`
     Extending |project| by adding :term:`types <data type>` or
     :term:`converters <converter>`

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 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 :term:`data types <data type>` 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.

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

.. _user-tutorial-java:

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.

.. _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 <data type>` 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