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

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

.. _install:

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

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

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

Add the ``--upgrade\-U`` option to upgrade an existing installation.

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

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

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

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

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

.. _sourceinst:

From local VHC copy
-----------------------

First you need to obtain the source VHC code with ::

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

Once this command has finished you can install VHC using `pip
<https://pip.pypa.io/en/latest/>`_ :: 

  pip install /path/to/vhc

or ::

  cd /path/to/vhc
  pip install .

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

.. _svninst:

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

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

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

Except for fetching the code for you, it works exactly as before.

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/vhc/trunk@5#egg=vhc
    pip install svn+svn://luna.mpe.mpg.de/vhc/tag/v0.0.0#egg=vhc

 
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/vhc
    python setup.py build
    python setup.py install

We do not recommend this method, as you have to deal with dependences yourself.

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

      ImportError: No module named 'numpy'

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


.. _Dependances:

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

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

::

  vhc_config
  pyhetdex
  jinja2
  six

``vhc_config`` contains all the configuration and files needed to run ``vhc``
(see :doc:`configuration`).

.. _installcure:

``ltl`` and ``cure``
--------------------

``cure`` is a C++ code that provides utilities that are executed by almost all
the :ref:`drivers shipped with the code <input>`. Thus, although VHC does not
depend on it, we provide here instruction on how to install ``cure`` and
``ltl``, a library ``cure`` depends on.

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

.. _optdep:

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

* testing::

   pytest>=3.3
   pytest-cov
   pyhetdex>=0.8
   beautifulsoup

   tox

* documentation::

    sphinx
    numpydoc
    alabaster
    pyhetdex

* automatic documentation build::

    sphinx-autobuild

.. _inst_devel:

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

If you develop VHC 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/vhc
  pip install -e .[all]

You can also use [not recommended] ::

    python setup.py develop

See :doc:`contributions` for more information.