Install Lab in a virtual environment
------------------------------------

We recommend installing Lab in a `Python virtual environment
<https://docs.python.org/3/tutorial/venv.html>`_. This has the advantage
that there are no modifications to the system-wide configuration, and
that you can create multiple environments with different Lab versions
(e.g., for different papers) without conflicts. Using Python 3, you
would proceed like this::

    # Install required packages, including virtualenv.
    sudo apt install mercurial python3 python3-venv

    # Create and activate a Python 3 virtual environment for Lab.
    python3 -m venv lab-venv  # or any other path instead of lab-venv
    source lab-venv/bin/activate

    # Install Lab in the virtual environment.
    pip install lab  # or a specific version with lab==x.y

If you want to install the latest development version and/or need to
change Lab itself, you can clone the Lab repo and install it in the
virtual environment::

    hg clone https://bitbucket.org/jendrikseipp/lab /path/to/lab
    pip install --editable /path/to/lab

The ``--editable`` flag in the last command is optional. It installs the
project in "editable mode", which is needed if you want to change the
Lab source code, since any changes under ``/path/to/lab`` are
immediately reflected in the installed package.

Please note that before running an experiment script you need to
activate the virtual environment with::

    source lab-venv/bin/activate


Install Lab globally
--------------------

Alternatively, you can install Lab and its dependencies globally::

    # Install dependencies.
    sudo apt install mercurial python python-matplotlib python-simplejson
    # Clone Lab repository.
    hg clone https://bitbucket.org/jendrikseipp/lab /path/to/lab

Add to your ``.bashrc`` to make Lab available on the ``PYTHONPATH``::

    export PYTHONPATH=/path/to/lab

Update shell configuration::

    source ~/.bashrc


Notes about requirements
------------------------

* Lab needs Python 2.7 or Python >= 3.5.
* matplotlib is only needed for reports that generate graphs.
* simplejson is optional, but speeds up generating reports.
