.. _installing:

============
 Installing
============

There are a few different ways to install Total Open Station,
depending on your operating system. If you are on GNU/Linux or Mac
OSX, you should already have Python installed on your
system. Instructions for Microsoft Windows are below.

Using ``pip``
=============

Until your operating system's packaging tools (e.g. ``apt`` or
``yum``) allow you to install Total Open Station along with other
programs, the recommended way to install is using ``pip``, like::

  pip install totalopenstation

This will install all the other required Python packages as
well. ``pip`` is complementary with virtualenv_, and it is encouraged
that you use virtualenv to isolate your installation::

  pip -E tops install totalopenstation

where ``-E tops`` creates a virtual environment named ``tops`` and
installs totalopenstation into it.

.. _virtualenv: http://pypi.python.org/pypi/virtualenv

Read more about ``pip`` at http://pip.openplans.org/ and
http://guide.python-distribute.org/pip.html .

Manual install with ``setup.py``
================================

If you manually download the source distribution file from PyPI or
from the mercurial repository, first make sure you have installed all
the :ref:`required packages <requirements>`. Then, just ``cd`` into
the uncompressed directory and::

  python setup.py install

Again, it's strongly recommended to avoid a system-wide install. Use
``virtualenv``.

Windows
=======

There is a binary installer available at PyPI_. This requires you to
install a Python_ distribution (latest available is 2.7.1 ‒ do not
install Python 3 as we don't support it yet), and the pyserial_ and
setuptools_ modules.

.. _PyPI: http://pypi.python.org/pypi/totalopenstation#downloads
.. _Python: http://www.python.org/getit/windows/
.. _pyserial: http://pypi.python.org/pypi/pyserial#downloads
.. _setuptools: http://pypi.python.org/pypi/setuptools#downloads
