Installation guide

This guide is intended to provide step-by step instructions for installing echidna. The preferred installation method is to install echidna in a virtual environment. The reason for this is that it should be entirely platform independent and ensures all versions of echidna are built against the same version of each dependency. Another bonus is that it makes it incredibly easy to install echidna on a system where you do not have root privileges. The guide will assume installation via this method, but aims to point out alternative options where possible.

If you experience any major problems during installation, please email [email protected] and we'll try and get back to you as soon as possible.

Setting up the virtualenv

This section summarises the virtualenv installation guide.

If you have root privileges, installing virtualenv is as easy as:

$ [sudo] pip install virtualenv

but otherwise you will have to download the source:

$ curl -O https://pypi.python.org/packages/source/v/virtualenv/virtualenv-X.X.tar.gz
$ tar xvfz virtualenv-X.X.tar.gz

At the time of writing, the latest stable release is 13.1.0, but any recent release should work fine.

---

Note

If you have installed virtualenv from source, you will need to replace virtualenv with python virtualenv.py in the following, where virtualenv.py is located in the directory just created when un-tarring.

---

The basic command to set up a virtualenv is :

$ virtualenv ENV

where ENV is the directory in which you would like to put your software package(s). I find it easiest to create a virtualenv with the same name as the software e.g.:

$ virtualenv echidna

but then you will end up with three consecutive directories named echidna so perhaps echidna_env, whatever works for you.

There are a number of options that can be used with the virtualenv command. One particularly useful one is the -p, --python option. This lets you specify the default python version within the virtualenv, which can be different to the python version used to create the virtualenv. echidna uses python 2.7 as standard (and will move to python 3 in the future), so you may wish to use this if python 2.6 is the default on your system.

$ virtualenv -p /path/to/python/2.7 ENV

Another useful option is the --system-site-packages option. This gives the virtualenv access to python packages installed system-wide. This can be very useful if you have python packages e.g. IPython or pdb already installed, and would like to use them within the virtualenv. If this flag is not included you will have to install separately, all python packages you want to use within the virtualenv.

Once you have set up your virtualenv and any time you wish to use it:

$ cd /path/to/ENV
$ source bin/activate

your command prompt should now tell you that you are working in the virtualenv. After you have finished working, in order to deactivate your virtualenv type:

(ENV) $ deactivate

Downloading the software

To download the latest release only, you have two options:

• download the latest release from GitHub

• Clone the repository from the command line

    (ENV) $ git clone -b "v0.1-alpha" [email protected]:snoplusuk/echidna.git
  

You can also clone the current development version, using:

(ENV) $ git clone [email protected]:snoplusuk/echidna.git

However, if you plan on developing the code as well, you should consider forking the repository and then cloning your fork:

(ENV) $ git clone [email protected]:yourusername/echidna.git

Installing dependencies

There are some external python packages that echidna relies on, for example Numpy - used for creating the core data structure. This section explains how to easily install these dependencies using pip.

However there is one dependency that must be installed without pip in order to install the following. The h5py python module requires either libhdf5-dev or hdf5-devel first. These can be installed by e.g.:

$ [sudo] apt-get install libhdf5-dev

or equivalent on mac/other distributions. They will probably require root privileges so you may need to talk to your system administrator.

If you now navigate to the echidna directory created when cloning/downloading the software, in the base directory you will find a requirements.txt file. This includes all the dependencies, with the correct version number supplied. To install them simply type:

(ENV) $ pip install -r requirements.txt

If you are in a virtualenv (note the indication in the command prompt) you do not need any root privileges here (i.e. no sudo or equivalent). If you are not using a virtualenv this may be required.

---

Troubleshooting

If you experience any problems when installing the requirements using pip try the following:

• Are you using the correct python version?
  • Ideally it should be python-2.7.X. Type python --version to check
  • If not consider using a virtualenv and specifying the correct python version with the -p flag
• Are you using the correct version of pip?
  • If it is pip 6.0 or greater you should be fine. Type pip --version to check
  • You can update pip with pip install -U pip

---

An alternate method that avoids having to set up a virtualenv, but still does not require root privileges, is to do (thanks to Jeanne for pointing this out):

$ pip install --user -r requirements.txt

This will install the dependencies to ~/.local/. Then you can either sym-link ~/.local/bin/* to /bin, or add ~/.local/bin/ to your PATH (and probably PYTHONPATH).

Whenever requirements.txt is updated, you can easily update the dependencies using:

(ENV) $ pip install -r requirements.txt --upgrade

Testing

You should now have a fully working version of the code. Python compiles at run time, so there is no need to compile anything before using it. One thing that is recommended, to check echidna and the dependencies have been installed correctly, is to run the suite of unittests.

Remember before you run echidna you need to source the appropriate RAT environment.

To test the full code is working as expected run:

(ENV) $ python -m unittest discover echidna/test/

from the base directory.