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

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

.. _install:

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

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

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

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/pyhetdex/>`_. A specific version can be
installed using `specifiers
<https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers>`_,
e.g. issuing ``pip install vdat==0.4``.

``pip`` will take care of installing all the :ref:`VDAT dependances
<Dependances>`, except for the ``Qt`` bindings. Instructions about the ``Qt``
binding and how to install them can be found in :ref:`qt_bind`.  Also, if you want
to run commands in VDAT you will also need to install :ref:`Cure <Cure>`.

If the ``pyds9`` package, VDAT will be able to send fits files to DS9. See
:ref:`pyds9` for instructions on how to install the package

We suggest you install VDAT 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 VDAT without any of the above with::

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

This way the VDAT executables 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.

.. _svninst:

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

These steps are to be followed if you want to install the latest version.

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

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

Similarly you can check out any branch. Now you can install with::

  pip install /path/to/vdat

or::

  cd /path/to/vdat
  pip install .

It's also possible to install vdat directly from the svn repository without
checking it out::

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

If necessary replace ``trunk`` with the desired tag or branch to checkout and
install.

.. _Dependances:

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

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

::

    pyhetdex>=0.12
    astropy
    colorama
    numpy
    six
    peewee
    ginga
    pyyaml
    qimage2ndarray>=1.5.1
    qtpy >= 1.1


.. _qt_bind:

``Qt`` bindings
^^^^^^^^^^^^^^^

Starting with version 0.9.0, VDAT makes use of the `qtpy
<https://github.com/spyder-ide/qtpy>`_ abstraction layer to communicate with
the `Qt <https://www.qt.io/>`_ instead of using directly some of the available
python bindings. This allows the user to decide which version of ``Qt`` to use
and which binding you use. ``qtpy`` automatically detects which ``Qt`` binding
to use and defaults to ``PyQt5`` if multiple are present. It is possible to
select a specific binding using the ``QT_API`` environment variable; see `here
<https://github.com/spyder-ide/qtpy#requirements>`_ for more details.

Available bindings and current status:

* `PyQt4 <http://pyqt.sourceforge.net/Docs/PyQt4/index.html>`_, ``Qt4``
  bindings: fully supported. Unfortunately ``PyQt4`` cannot be installed using
  pip; also `SIP library <https://riverbankcomputing.com/software/sip/intro>`_
  one of his dependences, cannot be installed with pip for python < 3.5. To our
  knowledge it is possible to obtain ``PyQt4`` in one of the following ways:

    * 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>`_ distribution or the `conda
      <http://www.continuum.io/blog/conda>`_ package manager
* `PyQt5 <http://pyqt.sourceforge.net/Docs/PyQt5/>`_, ``Qt5`` bindings: fully
  supported.  ``PyQt5`` provides wheels for 32- and 64-bit Windows, 64-bit
  macOS and 64-bit Linux under python v3.5 or later. Thus it is possible to
  install ``Qt5`` bindings using::

    pip install pyqt5

  ``PyQt5`` is also available in ``anaconda``/``conda``
* `PySide <https://wiki.qt.io/PySide>`_, ``Qt4`` bindings: not supported.
  We were not able to run unit test for ``PySide`` because of problems with the
  underlying C/C++ library (see :issue:`2607`). Attempts to run VDAT directly
  with ``PySide`` cause errors (:issue:`2598` and :issue:`2606`). ``PySide``
  can be installed using ``pip`` (see :ref:`pyside_inst` if there are problems).
* `PySide2 <https://wiki.qt.io/Qt_for_Python>`_, ``Qt5`` bindings: not
  supported. It is not yet supported by some dependences (:issue:`2597`).
  ``PySide2`` can be installed using pip::

    pip install --index-url=http://download.qt.io/snapshots/ci/pyside/5.11/latest/ pyside2 --trusted-host download.qt.io

.. _optdep:

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

.. _pyds9: 

``pyds9``
^^^^^^^^^

``pyds9`` allows to communicate between python and DS9 and is use to send fits
and region files from VDAT to DS9. If the package is not installed, VDAT works.

You can install ``pyds9`` together with the rest of VDAT with::

    pip install vdat[ds9]

or alone with::

    pip install pyds9

.. _cure: 

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

``cure`` is a C++ code that provides utilities that are executed in subprocesses
by most of the VDAT commands and depends on ``ltl``.
However VDAT doesn't depend on ``cure``.

Detailed information on how to install ``ltl`` and ``cure`` can be found `here
<https://luna.mpe.mpg.de/wikihetdex/index.php/Cure_Cookbook#Obtaining_Cure>`_.
Here we report the basic steps for completeness.

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

Python dependences
^^^^^^^^^^^^^^^^^^

* testing::

   pytest>=3.3
   pytest-qt>=2.0
   pytest-cov
   pytest-xdist
   coverage

   tox  # for automatizing the tests

* documentation::

    sphinx
    numpydoc
    alabaster
    pyhetdex

* automatic documentation build::

    sphinx-autobuild => 0.5.2

.. _inst_devel:

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

If you develop ``pyhetdex`` and/or ``vdat`` we suggest you checkout both svn
repositories and install them in `"editable" mode
<https://pip.pypa.io/en/latest/reference/pip_install.html#editable-installs>`_
. We also recommend installing all of the optional dependances::

  cd /path/to/vdat
  pip install -e .

It is possible to also install 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
==================

* It is possible to change the version to install from svn by 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