.. _installation:

Installation
============

This part of the documentation covers the installation of the relayr 
library. If you are an experienced Python user or developer you will likely
already be familiar with much of the information below. In case you are not you may find
the below information useful.


Installing the installer
------------------------

The recommended installation tool for Python packages today is `pip_`.

.. code-block:: console

    $ wget https://bootstrap.pypa.io/get-pip.py
    $ python get-pip.py

Using ``easy_install`` from setuptools_ is deprecated for `various reasons
<http://stackoverflow.com/questions/3220404/why-use-pip-over-easy-install>`_ 
see also `here 
<https://python-packaging-user-guide.readthedocs.org/en/latest/technical.html#pip-vs-easy-install>`_.


Creating a virtual environment
------------------------------

In order not to risk the existing
Python installation we recommend creating a virtual Python environment
(a ``virtualenv``) in which you can install the relayr library:

.. code-block:: console

    $ virtualenv rvenv
    New python executable in rvenv/bin/python
    Installing setuptools, pip...done.
    $ 

If ``virtualenv`` is not already installed on your system, you can install it
with ``pip install virtualenv``. The above lines will create a subfolder
named ``rvenv`` containing a separate Python installation. You can activate and
deactivate this environment using the following:

.. code-block:: console

    $ source rvenv/bin/activate
    (rvenv) $ # do some work... download, test, install, use...
    (rvenv) $ deactivate
    $ 


Installing a release
--------------------

You are able to install a release of the relayr library from PyPI_ with a single pip_ command. 
Inside a virtual Python environment this should be done after activating that
environment first (at the point of ``# do some work...`` in the previous section
above). This will install the latest version:

.. code-block:: console

    $ pip install relayr

You can also run a source distribution of a release from PyPI_ if you want to
run the test suite and/or generate the documentation yourself (more about
that see below). Just download a tarball of the sources and unpack as follows:

.. code-block:: console

    $ wget https://pypi.python.org/packages/source/r/relayr/relayr-0.2.0.tgz
    $ tar xfz relayr-0.2.0.tgz
    $ cd relayr-0.2.0
    $ python setup.py install


Installing a development version
--------------------------------

The relayr library is hosted and developed on `GitHub
<https://github.com/relayr/python-sdk>`_. If you wish to work with the
development version of relayr, there are two ways (again, both recommended
for a virtual environment). 

1. Checking out from the repository with git
............................................

You can operate on a ``git`` checkout. This will pull in the dependencies and
activate the ``git`` head as the current version inside the virtualenv. Then all 
you have to do is run ``git pull origin`` to update to the latest version,
before installing the package itself:

.. code-block:: console

    $ git clone http://github.com/relayr/python-sdk.git
    Cloning into 'python-sdk'...
    [...]
    $ cd python-sdk
    $ git pull origin
    $ python setup.py install

2. Downloading  the repository with pip
.......................................

You could also let ``pip`` itself pull in the development version without git:

.. code-block:: console

    $ pip install git+git://github.com/relayr/python-sdk.git
    [...]
    Cleaning up...
    $ python setup.py install

If you want to create the local documentation using Sphinx_ and/or run the
test suite using pytest_ please read the respective sections,
:ref:`documentation` and :ref:`testing`.

.. _pip: https://pip.pypa.io/
.. _setuptools: https://pypi.python.org/pypi/setuptools/
.. _PyPI: https://pypi.python.org/
.. _Sphinx: http://sphinx-doc.org/
.. _tox: http://tox.readthedocs.org/en/latest/
.. _pytest: http://pytest.org/
