.. _preparation:

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

.. warning::

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

.. _installation:

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

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

* Binary downloads
* Debian packages
* From source

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

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

   * `Linux i686 <https://ci.cor-lab.de/job/rsbag-tools-cl-0.7/label=ubuntu_precise_32bit/>`_
   * `Linux x86_64 <https://ci.cor-lab.de/job/rsbag-tools-cl-0.7/label=ubuntu_precise_64bit/>`_
   * `MacOS x86_64 <https://ci.cor-lab.de/job/rsbag-tools-cl-0.7-macos/label=MAC_OS_lion_64bit/>`_

#. After the download, the ``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.

#. The various ``bag-*`` tools are provided as `symbolic links
   <http://en.wikipedia.org/wiki/Symbolic_link>`_ to the single
   |main_binary| binary. When invoked, it prints a list of these links
   and offers to create them:

   .. code-block:: sh

      $ ./bag
      [...]
      Create missing links now [yes/no]? y
      Creating symbolic link bag-info -> bag
      [...]

   .. note::

      The links can also be created as follows:

      Non-interactively

        .. code-block:: sh

           $ ./bag create-links

      Manually

        .. code-block:: sh

           $ for alias in bag-{record,info,merge,cat,play} ; do ln -s bag ${alias} ; done

#. 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
   ``/etc/apt/sources.list``::

     deb http://packages.cor-lab.de/ubuntu/ RELEASENAME testing

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

.. warning::

   This installation method only works with |ubuntu|.

.. note::

   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

   $ bag-cat --version
   bag-cat version       0.6.0
   SBCL version          1.0.55
   RSB version           0.6.0
   RSBAG version         0.6.0
   RSBAG-TIDELOG version 0.6.0

.. _troubleshooting:

Troubleshooting
===============

#. Problem

     Calling any of the ``bag-*`` :ref:`tools <tools>`, the following
     happens:

     .. code-block:: sh

        $ bag-cat my-log-file.tide
        WARNING:
          Failed to load Spread library: Unable to load any of the alternatives:
          ("libspread-without-signal-blocking.so" "libspread.so" "libspread.so.2"
           "libspread.so.2.0" "libspread.so.1").
          Did you set LD_LIBRARY_PATH?
          Spread transport will now be disabled.
        [execution continues, but Spread transport does not work]

   Solution

     Place one of the mentioned :term:`Spread` libraries on the system
     library search path or set ``LD_LIBRARY_PATH`` appropriately.

#. Problem

     We would like also to know how to record with
     :ref:`bag-record`. We have tried:

     .. code-block:: sh

        $ bag-record -o test.tide                         \
                     'spread://remote:4803/nao/vision/0'  \
                     'spread://remote:4803/nao/vision/1'  \
                     'spread://remote:4803/nao/audio/all'

     with no success: ``ILLEGAL SPREAD``.

   Solution

     Most likely, there is no :term:`Spread daemon` running on host
     ``remote`` (or not on port ``4803``).