Tawara - English
=================

.. toctree::
   :hidden:

   index_j
   specification

Introduction
============

Tawara is a library for recording and playing back data indexed along a
single axis, typically time. It is not described as "for storing and
retrieving;" the library is optimised for data streams, not data tables.
It is particularly suited to applications that must record one or more
streams of data in such a way that the data can be replayed at a later
date, maintaining the timing information of the data. A common
application is recording data streams from a robot's sensors and playing
those streams back in real-time later on for testing software.

Requirements
============

Tawara uses the `CMake build system`_. You will need at least version
2.8 to be able to build the component.

.. _`CMake build system`:
   http://www.cmake.org/

Tawara runs on Linux, Mac OS X and Windows.

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

Binary
------

No binary installers are currently available.

From source
-----------

Follow these steps to install Tawara from source in any operating
system:

- Download the source, either from the repository or a source archive,
  and extract it somewhere::

    tar -xvzf tawara-1.0.0.tar.gz

- Change to the directory containing the extracted source::

    cd tawara-1.0.0

- Create a directory called ``build``::

    mkdir build

- Change to that directory::

    cd build

- Run cmake or cmake-gui::

    cmake ../

- If no errors occurred, run make::

    make

- Finally, install the library. Ensure the necessary permissions to
  install into the chosen prefix are available::

    make install

- The install destination can be changed by executing ccmake and changing
  the variable ``CMAKE_INSTALL_PREFIX``::

    ccmake ../

The library is now ready to use. You can use it in your own CMake projects with
the following line::

  find_package(tawara)

If you are not using CMake, a pkg-config file is available,
``tawara.pc``.  Be sure to add the pkg-config location below the
Tawara install prefix to the ``PKG_CONFIG_PATH`` environment variable.
If you installed into ``/usr/local``, this will be::

  /usr/local/lib/pkgconfig

or::

  /usr/local/lib64/pkgconfig


APIs
====

Tawara features two APIs for the programmer:

  Tide
    This is the element-level API. It requires working with the EBML
    elements used in the Tawara format directly. It allows significant
    flexibility in how a Tawara document is written to disc or read
    from disc.  A reasonable knowledge of the Tawara format
    specification (:doc:`available here <specification>`) is necessary
    to use this interface effectively.

  HighTide
    This is the high-level API, providing an abstract interface into
    Tawara documents. For example, channels are abstracted into streams
    of data that can be individually iterated through. No knowledge of
    the Tawara format specification is necessary to use this API.


Documentation
-------------

Full API documentation is available with the library. It is generated
using Doxygen and Sphinx. If you installed from source, you must have
Doxygen and Sphinx installed and set ``BUILD_DOCUMENTATION`` to ``ON``
in CMake.

Click here_ to access the API documentation.

.. _here:
   doxygen/html/index.html

The documentation is also `available online`_.

.. _`available online`:
   http://gbiggs.github.com/tawara/


Examples
========

Simple usage examples are provided in the ``examples/`` directory of the
source. For more complex examples, see the sourcecode of the tools
included with Tawara.


Tools
=====

Tawara includes several useful tools. These tools are designed to
introspect and manipulate Tawara objects.


Format specification
====================

The Tawara format specification is :doc:`available online
<specification>`.


Changelog
=========

1.0
---

- Initial release.


License
=======

This software is developed at the National Institute of Advanced
Industrial Science and Technology. Approval number H22PRO-???? This
software is licensed under the New BSD License. See LICENSE.TXT for
license information.

