.. _overview:

Overview
========

.. highlight:: c

Directories
-----------

docs
^^^^

The documentation for xy resides in the *docs* directory.

XY's documentation is managed by Sphinx_; the latest version is always
available online_.

.. _online: http://xy.readthedocs.org

examples
^^^^^^^^

Various examples for interacting and integrating with xy live in the *examples*
directory.

lib
^^^

The core of xy is housed in the *lib* directory. The real parts of xy live here
-- from utilities and library interefaces to modules like xy's broadcasting
engine.

resources
^^^^^^^^^

The *resources* directory contains xy's ancillary files. Resources for
build automation and testing, images, and runtime resources are all held here.

src
^^^

The *src* directory contains xy's *main* function - the application's entry
point. The main executable is built independently of xy's libraries and tests
to allow for things like parallel builds and a robust level of testing.

tests
^^^^^

The *tests* directory contains binaries that test pieces of xy. The same tests
are used to exercise various components and identify potential memory leaks or
performance problems.

XY supports testing via the Check_ unit testing framework.

.. _Check: http://check.sourceforge.net/

Requirements
------------

*TODO* - *requirements currently in flux* (njb)

Building
--------

The xy source tree is managed by Autotools_. It follows a standard
configure-and-build approach.

.. code-block:: bash

    # ./configure --quiet
    xy build configuration
    ----------------------
    version         : 2012
    cflags          : -pipe -std=c99 -Wall -Wunused -Wextra -Wno-unused-parameter -O0 -g3
    tests           : yes
    optimizations   : no

The default build configuration targets developers. To build xy for production
use:

.. code-block:: bash

    # ./configure --enable-optimizations --disable-tests --quiet
    xy build configuration
    ----------------------
    version         : 2012
    cflags          : -pipe -std=c99 -Wall -Wunused -Wextra -Wno-unused-parameter -O3
    tests           : no
    optimizations   : yes

.. _Autotools: http://en.wikipedia.org/wiki/GNU_build_system

Running
-------

XY can be launched using *ck-launch-session* and a ``Xclients`` or ``xsession``
file in your home directory. Your login manager can also be configured to start
xy for you. Refer to your distribution's documentation for more information.

Under Valgrind
^^^^^^^^^^^^^^

You can run xy under Valgrind_, to help isolate memory leaks or troubleshoot
performance problems. The overhead of running xy with Valgrind will make the
interface cumbersome making xy unsuitable for regular use.

.. code-block:: bash

  valgrind --tool=memcheck --leak-check=full --log-file=$HOME/valgrind.xy.log xy


Documenting
-----------

Documentation can be generated by using the *html* make target.

.. code-block:: bash

    # make html

Use of this target requires Sphinx_. The HTML-based documentation will be
located in ``docs/build/html``.

.. _Sphinx: http://sphinx.pocoo.org/index.html
.. _Valgrind: http://valgrind.org