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

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

.. _svninst:

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

The easiest way to install the development version of VDAT is using `pip
<https://pip.pypa.io/en/latest/>`_ This will take care of installing 
:ref:`VDAT dependances <Dependances>`, except for ``ltl``, ``cure``,
``pyhetdex`` [#pyhet]_ and ``PyQt4``. Installation instructions 
for these are given in the cure_ section, `here <http://pyqt.sourceforge.net/Docs/PyQt4/installation.html>`_
and below. During installation, unless you want to use root privileges we suggest you use either 
virtual environments or the ``--user`` flag (see notes_).

First get a local copy of ``VDAT``, you can checkout the repository with::

  svn checkout svn://luna.mpe.mpg.de/vdat

or::

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

if only the trunk is desired. Now you can install with::

  pip install /path/to/vdat

or::

  cd /path/to/vdat
  pip install .

With the ``vdat`` repository we distribute a ``requirements.txt`` file, that can
be copied and/or edited to install ``pyhetdex`` via::

  pip install -r requirements.txt svn+svn://luna.mpe.mpg.de/vdat/trunk

.. _Dependances:

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

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

::

  PyQt4
  pyhetdex
  ltl
  cure
  astropy
  matplotlib
  aplpy
  numpy 

``cure`` is a C++ code that provides utilities that are executed in subprocesses
by most of the ``vdat`` commands. ``cure`` depends on ``ltl``.

.. _cure: 

Install ``ltl`` and ``cure``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Check out and compile ``ltl``::

  cd /path/to/project
  svn checkout svn://luna.mpe.mpg.de/ltl/trunk ltl
  cd ltl
  ./bootstrap
  ./configure
  make
  cd ..

Check out and compile ``cure``::

  svn checkout svn://luna.mpe.mpg.de/cure/trunk cure
  cd cure
  make install

This will install the binaries into ``bin`` directory. If you don't have OpenGL
libraries installed, run::

  make install HAVE_OPENGL=no

as last step. You can use ``make -j N`` to speed up the build process using N
cores.

After it is installed, you might want to::

  export CUREBIN=/path/to/project/cure/bin

Install ``PyQt4``
^^^^^^^^^^^^^^^^^

`PyQt4 <http://pyqt.sourceforge.net/Docs/PyQt4/index.html>`_ is a set of Python
bindings for `the C++ Qt application framework
<http://doc.qt.io/qt-4.8/index.html>`_. It relies on the `SIP library
<https://riverbankcomputing.com/software/sip/intro>`_ to bind the python and
the C++ code. Because of the dependence to the ``Qt4`` framework and the
unusual package structure, when writing is not possible to install ``PyQt4``
and ``SIP`` using ``pip``. To our knowledge you can install them in one of the
following way:

* If you feel brave you can try to install them by hand following e.g. `these
  instructions
  <http://movingthelamppost.com/blog/html/2013/07/12/installing_pyqt____because_it_s_too_good_for_pip_or_easy_install_.html>`_
* use a package manager; most, if not all, Linux distributions, as well as Mac
  packet managers like ``homebrew`` and ``macports``, provide ``PyQt4``
* use tools like the [anaconda](https://store.continuum.io/cshop/anaconda)
  python distribution or the [conda](http://www.continuum.io/blog/conda)
  package manager

.. _optdep:

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

* testing::

   pytest>=1
   pytest-qt>=1.7
   pytest-cov
   pytest-capturelog

   tox  # for automatizing the tests

* documentation::

    sphinx
    numpydoc
    alabaster
    pyhetdex

* automatic documentation build::

    sphinx-autobuild

.. _inst_devel:

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

If you develop ``pyhetdex`` and/or ``vdat`` we suggest to checkout both svn
repositories and to install them 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/vdat
  pip install -e .

It is possible to install also the ``pyhetdex`` software in editable mode adding
``-e`` in the ``requirements.txt`` file before the url or path, e.g.::

  ~> cat requirements.txt
  -e /path/to/pyhetdex

and adding the options ``-r requirements.txt`` in the ``pip`` call.

See :doc:`contributions` for more information.

.. _notes:

Notes and problems
==================

* We suggest using a `virtual environment
  <https://virtualenv.pypa.io/en/latest/>`_ [#venvw]_. Outside a virtual
  environment the above command installs in a system directory, so might be
  necessary to use superuser powers, a.k.a. ``sudo``. Alternatively, it is possible to install
  the software in the user directory, usually ``$HOME/.local`` by adding the option
  ``--user``.
* It is possible to change the version to install from svn selecting a specific
  commit::

    pip install svn+svn://luna.mpe.mpg.de/vdat/trunk@5#egg=vhc

  or a different branch/tag::

    pip install svn+svn://luna.mpe.mpg.de/vdat/tag/v0.0.0#egg=vhc

* If the installation gets interrupted with an error like::

    ImportError: No module named 'numpy'

  run ``pip install numpy`` and then retry ``vdat`` installation

.. rubric:: Footnotes

.. [#pyhet] We will try to automatize also the ``pyhetdex`` installation via pip
.. [#venvw] Maybe with the help of `virtualenvwrapper
  <http://virtualenvwrapper.readthedocs.org/en/latest/index.html>`_


.. To do this
   create a file ``requirements.txt`` with one of the following lines::

.. svn+svn://luna.mpe.mpg.de/pyhetdex/trunk#egg=pyhetdex

.. to fetch ``pyhetdex`` from the svn repository, or::

.. /path/to/pyhetdex 

.. if you have a version of the code on your file system (it must be the directory
   containing the ``setup.py`` file). Then you can install it all
   in one go with::

.. pip install -r requirements.txt svn+svn://luna.mpe.mpg.de/vdat/trunk

.. From local ``VDAT`` copy

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