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

To run Sumatra you will need Python installed on your machine. If you are running
Linux or OS X, you almost certainly already have it. If you don't have Python,
you can install it from `python.org`_, or install one of the
"value-added" distributions aimed at scientific users of Python: `Enthought`_,
`Python(x,y)`_ or Anaconda_.

The easiest way to install Sumatra is directly from the `Python Package Index`_
(PyPI)::

    $ pip install sumatra


Alternatively, you can download the Sumatra package from either PyPI or the
`INCF Software Centre`_ and install it as follows::

    $ tar xzf Sumatra-0.7.0.tar.gz
    $ cd Sumatra-0.7.0
    # python setup.py install

The last step may need to be run as root, or using sudo, although in general
we recommend installing in an isolated environment created using virtualenv or conda.


Installing Django
-----------------

If you wish to use the web interface, you will also need to install Django_
version 1.6 or later. On Linux, you may be able to do this via your package
management system: see https://code.djangoproject.com/wiki/Distributions.

Otherwise, it is very easy to install manually: see
https://docs.djangoproject.com/en/dev/topics/install/#installing-official-release

You will also need to install the `parameters`, `django-tagging`_ and docutils_ packages,
which may be in your package management system, otherwise they can be installed
using pip::

    $ pip install parameters
    $ pip install django-tagging
    $ pip install docutils


Installing Python bindings for your version control system
----------------------------------------------------------

Sumatra currently supports Mercurial_, Subversion_, Git_ and Bazaar_.
If you are using Subversion, you will need to install the `pysvn bindings`_.
Since Bazaar is mostly written in Python, just installing the main Bazaar
package is sufficient. For Git, you need to install the GitPython_ package.
For Mercurial, you need to install the hgapi_ package.


Command completion for bash
---------------------------

Sumatra comes with a limited bash completion facility.
You can install it to you system by sourcing the file
`smt-completion.sh` in your `.bashrc` or `.profile.
By default, Sumatra installs this script to your
`/usr/bin` directory by default but moving it
elsewhere (e.g. to `~/.bash_completion.d/`)
is recommended.


.. _python.org: https://www.python.org
.. _Django: https://www.djangoproject.com
.. _Mercurial: https://mercurial.selenic.com/
.. _Subversion: http://subversion.tigris.org/
.. _Git: http://git-scm.com/
.. _Bazaar: http://bazaar.canonical.com/
.. _`Python Package Index`: https://pypi.python.org/pypi/Sumatra/
.. _`INCF Software Centre`: http://software.incf.org/software/sumatra/download
.. _`django-tagging`: https://pypi.python.org/pypi/django-tagging/
.. _`pysvn bindings`: http://pysvn.tigris.org/project_downloads.html
.. _`GitPython`: https://pypi.python.org/pypi/GitPython/
.. _`hgapi`: https://pypi.python.org/pypi/hgapi/
.. _`Enthought`: http://www.enthought.com/products/epd/
.. _`Python(x,y)`: http://code.google.com/p/pythonxy/
.. _Anaconda: http://docs.continuum.io/anaconda/
.. _docutils: http://docutils.sourceforge.net