============================
Installing and running khmer
============================

You'll need Python 2.7+ and internet access.

The khmer project currently works with Python 2.6 but we target Python 2.7+. 

Build requirements
------------------

OS X 
^^^^

#) If you just what to use the khmer project tools and not develop them then
skip to step 4).

#) Install Xcode from the `Mac App Store (requires root)
   <https://developer.apple.com/xcode/>`_

#) `Register as an Apple Developer <https://developer.apple.com/register>`__.

#) Install the Xcode command-line tools: Xcode -> preferences ->
   Downloads -> Command Line Tools (requires root)

#) From a terminal install virtualenv. You'll need the URL of the `latest
virtualenv release <https://pypi.python.org/packages/source/v/virtualenv/>`__.

::

      curl -O https://pypi.python.org/packages/source/v/virtualenv/virtualenv-1.x.y.tar.gz
      tar xzf virtualenv*
      cd virtualenv-*; python virtualenv.py ../khmerEnv; cd ..
      source khmerEnv/bin/activate

Linux
^^^^^

#) Install the python development environment, virtualenv, pip, and
gcc.

On recent Debian and Ubuntu this can be done with::

   sudo apt-get install python2.7-dev python-virtualenv python-pip gcc

For RHEL6::

   sudo yum install -y python-devel python-pip git gcc gcc-c++ make
   sudo pip install virtualenv   

#) Create a virtualenv and activate it::

      cd a/writeable/directory/
      virtualenv khmerEnv
      source khmerEnv/bin/activate

Linux users without root access can try step 4) from the OS X instructions above

Latest stable release
---------------------

#) Check your pip version::

	pip --version

#) Use pip to download, build, and install khmer and its dependencies.

If you're running version 1.5 or greater of pip::
        pip install --allow-external argparse khmer
For pip version 1.4.1 and earlier::
	pip install khmer

#) The scripts are now in the ``env/bin`` directory and ready for your
   use. You can directly use them by name, see :doc:`scripts`.

4) When returning to khmer after installing it you will need to
   reactivate the virtualenv first::

      source khmerEnv/bin/activate

Latest development branch
-------------------------

Repeat the above but modify the pip install line.

If you're running version 1.5 or greater of ``pip`` then::

	pip install --allow-external argparse git+https://github.com/ged-lab/khmer.git@master#egg=khmer

For ``pip`` version 1.4.1 and earlier::

   pip install git+https://github.com/ged-lab/khmer.git@master#egg=khmer

You can change ``master`` in the above command to the name of another branch.

Run the tests
^^^^^^^^^^^^^

If you're running a version of ``pip`` less than 1.4 and you want to run the
tests then you should upgrade ``pip``::

	pip install --user --upgrade pip

Repeat the appropriate installation procedure from above but add "--no-clean"
to the ``pip`` invocation.

The source will be in the ``khmerEnv/build/khmer`` directory. Run
``make test`` there.