Installation
************

Instructions
============

.. _install:

The recommended way
-------------------

The recommended way to install ``tcs_lib`` is using `pip <https://pip.pypa.io/en/latest/>`_::

    pip install --extra-index-url https://gate.mpe.mpg.de/pypi/simple/ tcs_lib

It's possible to set the extra index URL permanently by adding the following lines
to the ``$HOME/.pip/pip.conf`` file::

    [global]
    extra-index-url = https://gate.mpe.mpg.de/pypi/simple

or exporting the environment variable::

    export PIP_EXTRA_INDEX_URL=https://gate.mpe.mpg.de/pypi/simple

The list of released versions can be seen `on the MPE pypi server
<https://gate.mpe.mpg.de/pypi/simple/tcs_lib/>`_. A specific version can be
installed using `specifiers
<https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers>`_,
e.g. issuing ``pip install tcs_lib==0.1``.

``pip`` will take care of installing :ref:`tcs_lib dependances <Dependances>`.

We suggest you install ``tcs_lib`` into a `virtualenv
<https://virtualenv.pypa.io/en/stable/>`_, in an `anaconda
<https://www.continuum.io/downloads>`_/`conda
<http://conda.pydata.org/docs/index.html>`_ or in similar environments.

Of course it is also possible to install ``tcs_lib`` without any of the above with::

    pip install --user --extra-index-url https://gate.mpe.mpg.de/pypi/simple/ tcs_lib

This way the executables shipped with ``tcs_lib`` are installed in
``$HOME/.local/bin``, so make sure to add this to the environment variable
``PATH`` to be able to easily use them on the command line.

The use of ``sudo`` when installing with pip is `discouraged
<http://stackoverflow.com/questions/21055859/what-are-the-risks-of-running-sudo-pip>`_
and potentially harmful.

.. _sourceinst:

From local ``tcs_lib`` copy
---------------------------

If you develop ``tcs_lib`` or want to use always the latest version, you can
install it directly from the checked out svn repository.
First you can obtain the source ``tcs_lib`` code with ::

  svn checkout svn://luna.mpe.mpg.de/tcs_lib/trunk tcs_lib

If you already have the repository, you can of course keep it up to date with
``svn update``

Then you can install the library with::

  pip install /path/to/tcs_lib

or ::

  cd /path/to/tcs_lib
  pip install .

where ``/path/to/tcs_lib`` is the base directory containing the ``setup.py``
file.

.. _svninst:

From online svn repository
--------------------------

It is also possible to install ``tcs_lib`` directly from the svn repository
with ::

  pip install svn+svn://luna.mpe.mpg.de/tcs_lib/trunk#egg=tcs_lib

If you want to install a specific commit or from a different branch or tag, you
can do it issuing one of the following commands ::

    pip install svn+svn://luna.mpe.mpg.de/tcs_lib/trunk@5#egg=tcs_lib
    pip install svn+svn://luna.mpe.mpg.de/tcs_lib/tag/v0.0.0#egg=tcs_lib

Other ways
----------

Once you obtained the source code as in :ref:`sourceinst`, you can install the
code also using the good old ::

    cd /path/to/tcs_lib
    python setup.py build
    python setup.py install

We do not recommend this method.

.. _Dependances:

Dependances
===========

Mandatory dependences
---------------------

::
    
    pyzmq
    six

.. _optdep:

Optional dependences
--------------------

* testing::

   pytest
   pytest-cov

   tox

* documentation::

    sphinx
    numpydoc

* automatic documentation build::

    sphinx-autobuild

.. _inst_devel:

Development
===========

If you develop ``tcs_lib`` we suggest to checkout the svn
repository and to install it in `"editable" mode
<https://pip.pypa.io/en/latest/reference/pip_install.html#editable-installs>`_
and to install all the optional dependances::

  cd /path/to/tcs_lib
  pip install -e .[livedoc]

You can also use [not recommended] ::

    python setup.py develop

See :doc:`contributions` for more information.