.. Copyright (C) ALbert Mietus, SoftwareBeterMaken.nl; 2016. Part of Pathways project -*- coding: utf-8 -*-

.. highlight:: shell-session

===================
Installing Pathways
===================

Installing the pathways-framework itself is trivial. It is a small pure-python package, which can be installed in any
working **python-3** (3.4 or later) environment. Most users will also need to install the examples. That is a bit more
complicated; as they depend on other tools. By example, for the webapp-examples, firefox and selenium are needed.

Installing pathways will install the package itself and a few (command-line) tools, like :command:`pw`: a driver to
start an (few) :term:`ATS`\es.

.. rubric:: virtual environment

It is advised to use a python virtual environment. There are several options; for a Unix (MacOS, FreeBSD, Linux etc)
*virtualenv* (with *virtualenvwrapper*) are good candidates. Whereas *conda* can be very helpful on windows. Read more
on the options on:

======================================================================	===================================
virtual environment							RTFD
======================================================================	===================================
`virtualenv        <https://pypi.python.org/pypi/virtualenv/>`_ 	http://virtualenv.rtfd.org/
`virtualenvwrapper <https://pypi.python.org/pypi/virtualenvwrapper/>`_ 	http://virtualenvwrapper.rtfd.org/
`conda             <http://conda.pydata.org/docs/>`_ 			http://conda.rtfd.org/
`(py)venv	   <https://docs.python.org/3.4/library/venv.html>`_    *pyenv is part of python, from 3.3*
======================================================================	===================================

.. note:: Python3 & pip3 ?

   The commands below have the  **3** suffix, to denote one have to use a python-3 (virtual) environment;  and the
   pip-3 version too. Depending on your environment, you may need to drop the *3*

   * When using pip as ``python3 -m pip``, the pip as argument has no suffix!
   * Below, we use the ``--upgrade`` argument (always); this make sure an already installed package will be upgraded.

Installing the framework
========================

The R&D distribution of pathways can be obtained from `Bitbucket <https://bitbucket.org/ALbert_Mietus/pathways-r-d>`__.
You can clone the repro, or download the source, there to get a “source” distribution. It is also possible to use a
*dist-file*, named like :samp:`pathways_framework-0.{Y.Z}.dev{DATE}.tar.gz`. Currently, that one is only hand-out by
Albert (during trainings, etc)) but will become downloadable from `Bitbucket
<https://bitbucket.org/ALbert_Mietus/pathways-r-d/downloads?tab=downloads>`__ soon.

Once a *real* "production" version will become available; then will become available on pypi too.

In all cases, pathways can be installed with pip.


dist-file
---------

Installing the pathways-framework from the dist-file is easy::

       [albert@Python3:]%  pip3 install --upgrade pathways_framework-0*.tar.gz


From source
-----------

Installing from source is a bit more complicated, as one has to select the correct branch first; currently that is
|branch| (but that will change!). And that install the "directory". Assuming you are the top directory, where the
file :file:`setup.py` is located, use::

     [albert@Python3:]%  hg checkout |branch| ## Select the 'correct' branch
     [albert@Python3:]%  pip3 install --upgrade --editable .

A ‘source-install’ is typically installed *editable*, as is done above (with the ``--editable`` option). Now, the
(local) pathways sources can be edited, with direct effect. This is an advantage for developers (of pathways).


.. todo:: make pathways downloadable

   For now: Download the source from `Bitbucket <https://bitbucket.org/ALbert_Mietus/pathways-r-d>`_!

Tips
====

* Add python3 to your path (http://stackoverflow.com/questions/3701646/how-to-add-to-the-pythonpath-in-windows-7)