.. vim: set filetype=rst

============================
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 want 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 download the virtualenv package and create a
   virtual environment with it. 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-*; python2.7 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/
      python2.7 -m virtualenv khmerEnv
      source khmerEnv/bin/activate

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

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

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

      pip2 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`.

#) 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::

   pip2 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``::

	pip2 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.