Installing Formic
=================

Prequisites
-----------

Platform and dependencies:

* Formic requires Python 2.7
* It has been tested on

  * Mac OS X (Lion)
  * Ubuntu 11.10 and 12.04LTS
  * Windows XP and Windows 7 (Home Premium).

Formic should work on any Python 2.7 system; if not, please contact the
maintainer or `file an issue
<https://bitbucket.org/aviser/formic/issues/new>`_.

Formic has no runtime dependencies outside the Python system libraries.

Installation options
--------------------

There are three ways to obtain Formic shown below, in increasing difficulty
and complexity. You need only pick one:

**Option 1: Automated install**

Simplest: use::

    $ easy_install formic

or::

    $ pip install formic

**Option 2: Source install**

1. Download the appropriate package from Formics page on the `Python
   Package Index <http://pypi.python.org/pypi/formic>`_. This is a GZipped TAR
   file.
2. Extract the package using your preferred GZip utility.
3. Navigate into the extracted directory and perform the installation::

    $ python setup.py install

**Option 3: Check out the project**

If you like, you could download the source and compile it yourself. The
source is on a Mercurial DVCS at `Atlassian BitBucket
<https://bitbucket.org/aviser/formic.>`_. BitBucket provides several different
approaches for download on the site.

.. note:: To build, Formic requires setuptools, setuptools-hg and distribute.

After checking out the source, navigate to the top level directory and build::

    $ python setup.py install

Validating the installation
---------------------------

After installing, you should be able to execute Formic from the command line::

    $ formic --version
    formic 0.9beta2 http://www.aviser.asia/formic

If you downloaded the source, you can additionally run the unit tests. This
requires py.test::

    $ easy_install pytest
    $ cd formic
    $ py.test
    ========================== test session starts ==========================
    platform darwin -- Python 2.7.1 -- pytest-2.2.3
    collected 40 items

    test_formic.py ........................................

    ======================= 40 passed in 2.55 seconds =======================

Compiling the documentation
---------------------------

Formic uses `Sphinx <http://sphinx.pocoo.org/>`_ for documentation. The source
files are in the 'doc' subdirectory. To build the documentation, navigate to the
top level directory in the source, then::

    $ sphinx-build doc htmlout

The documentation will be in the ./htmlout subdirectory.

.. note:: Only HTML generation has been tested.
