.. _preparation:

=============
 Preparation
=============

.. warning::

   :term:`Log files <log file>` produced by the |version| version of
   the |project| tools cannot be processed using the older
   versions. However, the opposite direction should work.

.. _install:

Installation
============

There are currently three different ways to install the |version|
version of the |project| tools:

* Binary downloads
* Debian packages
* From source

The client API for Python :ref:`is available via PyPi <install-pypi>`.

Binary Downloads
----------------

#. Download the :file:`bag` binary from the appropriate location:

   * `Linux i686 <https://ci.cor-lab.de/job/rsbag-tools-cl-trunk/label=ubuntu_xenial_32bit/lastSuccessfulBuild>`_
   * `Linux x86_64 <https://ci.cor-lab.de/job/rsbag-tools-cl-trunk/label=ubuntu_xenial_64bit/lastSuccessfulBuild>`_
   * `MacOS x86_64 <https://ci.cor-lab.de/job/rsbag-tools-cl-trunk-macos/label=MAC_OS_lion_64bit/lastSuccessfulBuild>`_

#. After the download, the :file:`bag` file has to be made executable
   in most cases. This can be done for example by executing

   .. code-block:: sh

      $ chmod +x bag

   in the download directory.

#. If required, download scripts from the locations given above.

Debian Packages
---------------

Debian packages for several versions of |ubuntu| are available from
the `CoR-Lab package repository
<http://packages.cor-lab.de/ubuntu/dists/>`_.

#. The following repository source line has to be added to
   :file:`/etc/apt/sources.list`

   .. parsed-literal::

      deb http://packages.cor-lab.de/ubuntu/ :samp:`{RELEASENAME}` main

   where :samp:`{RELEASENAME}` is the appropriate Ubuntu release name.

#. After that, packages can be installed via

   .. code-block:: sh

      $ sudo apt-get install PACKAGENAME

   where :samp:`{PACKAGENAME}` is |package_name| for this release of
   |project|.

.. note::

   This installation method only works with |ubuntu|. More information
   can be found `here
   <https://support.cor-lab.org/projects/ciserver/wiki/RepositoryUsage>`_.

From Source
-----------

.. note::

   Building and installing |project| and the associated tools from source
   requires the `SBCL`_ `Common Lisp`_ implementation and additional
   projects which can be downloaded from TODO. All remaining
   dependencies should be installable via `Quicklisp`_.

#. The entire source code of |project| (for version |version|) along
   with associated support files and this manual is available at
   |repository_versioned|.

#. Build and install |project|

   .. code-block:: sh

      $ mkdir -p build && cd build
      $ cmake ..
      $ make
      $ make install

Testing the Installation
========================

The success of the installation can be tested as follows:

.. code-block:: sh

   $ rsbag cat --version
   rsbag cat version     0.15.6-g8be064f
   SBCL version          1.3.3.debian
   RSB version           0.15.2-g1c67d1e
   RSBAG version         0.15.8-g228292e
   RSBAG-TIDELOG version 0.15.8-g228292e

.. _install-pypi:

Python PyPI Packages
====================

For the |project| client API for Python, a platform-independent
package called ``rsbag-python`` is pushed to the central repository
server and can be installed with :program:`pip` or
:program:`easy_install`.

.. note::

   :program:`pip` is the recommended way of installing Python packages
   since some time and preferred over :program:`easy_install`. On
   |ubuntu| systems, :program:`pip` can be installed via the package
   ``python-pip``.

.. note::

   The Python implementation of |project| is currently only available
   for Python 2.X. If the default Python version on your system is
   Python 3, ensure that you call the respective
   :program:`easy_install` or :program:`pip` version. These usually
   contain the Python version as a suffix to the name, e.g.:
   ``easy_install-2.7``.

#. ``rsbag-python`` depends on ``rsb-python`` which is also
   :ref:`installable via PyPI <rsb:install-pypi>`.

#. The ``rsbag-python`` module can be installed by using one of the
   following functions:

   .. parsed-literal::

      $ easy_install "rsbag-python<=\ :samp:`{VERSION}`\ .99999"

   .. parsed-literal::

      $ pip install "rsbag-python<=\ :samp:`{VERSION}`\ .99999"

   where :samp:`{VERSION}` needs to be replaced with |version|.

   .. note::

      Development versions of |project| are not deployed on PyPI. These
      commands will revert to the latest stable version.