=========================
Installation instructions
=========================

Dependencies
============

To install MetaWards, you first need to install Python >= 3.7. To check
if you have Python 3.7 installed type;

.. code-block:: bash

    python -V

This should print out the version number of the Python you have available.
If the version number is ``2.???`` then you have a very old Python 2. If
this is the case, try;

.. code-block:: bash

    python3 -V

and see if you have a Python 3 that has a version number >= 3.7. If so,
please use ``python3`` instead of ``python``.

If you don't have Python >=3.7 installed, then you can install Python
either via your package manager, or more simply, by using
`anaconda <https://anaconda.org>`__.

pip install
=============

Once you have a working Python >= 3.7, the easiest way to install
MetaWards is using
`pip <https://pip.pypa.io/en/stable/>`__.

.. code-block:: bash

    pip install metawards

(if this doesn't work, then you may need to use the command ``pip3``,
or you may have to `install pip <https://pip.pypa.io/en/stable/installing/>`__.
If you have trouble installing pip then we recommend that you download
and install `anaconda <https://anaconda.org>`__, which has pip included)

To install a specific version, e.g. 0.6.0, type

.. code-block:: bash

    pip install metawards==0.6.0

This will install a binary version of metawards if it is avaiable for your
operating system / processor / version of python. If not, then
metawards will be compiled into C using `cython <https://cython.org>`__,
and then compiled into an executable using your system C compiler
(e.g. `gcc <https://gcc.gnu.org>`__ or `clang <https://clang.llvm.org>`__).
You can control which C compiler to use by setting the ``CC`` environment
variable, e.g.

.. code-block:: bash

    CC=gcc pip install metawards

MetaWards is written in standard C, using
`OpenMP <https://www.openmp.org>`__ for parallelisation,
and it has no external dependencies, so
it should compile without issue. Note that the system C compiler on
OS X (Mac) does not support OpenMP. In this case you will need to install
and use a different compiler, e.g. installing clang via
`homebrew <https://brew.sh>`__. If you have any problems then please
`post an issue on GitHub <https://github.com/metawards/MetaWards/issues>`__.

Source install
==============

You can download a source release of MetaWards from the
`project release page <https://github.com/metawards/MetaWards/releases>`__.

Once you have downloaded the file you can unpack it and change into
that directory using;

.. code-block:: bash

   tar -zxvf MetaWards-X.Y.Z.tar.gz
   cd MetaWards-X.Y.Z

where ``X.Y.Z`` is the version you downloaded. For the 0.6.0 release
this would be;

.. code-block:: bash

    tar -zxvf MetaWards-0.5.0.tar.gz
    cd MetaWards-X.Y.Z

Next you need to install the dependencies of MetaWards. Do this by typing;

.. code-block:: bash

    pip install -r requirements.txt

Now you are ready to compile and install MetaWards itself;

.. code-block:: bash

    make
    make install

You can choose the C compiler to use by setting the ``CC`` environment
variable, e.g.

.. code-block:: bash

    CC=clang make
    CC=clang make install

MetaWards is written in standard C, using
`OpenMP <https://www.openmp.org>`__ for parallelisation,
and it has no external dependencies, so
it should compile without issue. Note that the system C compiler on
OS X (Mac) does not support OpenMP. In this case you will need to install
and use a different compiler, e.g. installing clang via
`homebrew <https://brew.sh>`__. If you have any problems then please
`post an issue on GitHub <https://github.com/metawards/MetaWards/issues>`__.

For developers
==============

You can clone the MetaWards repository to your computer and install from
there;

.. code-block:: bash

    git clone https://github.com/metawards/MetaWards
    cd MetaWards

From this point you can compile as if you have downloaded from source.
As a developer you may want to install the developer tools to enable
you to run the tests and create the website. To do this type;

.. code-block:: bash

    pip install -r requirements-dev.txt

    pytest tests
    cd doc; make html

Note that the tests assume that you have already downloaded the
model data from `MetaWardsData <https://github.com/metawards/MetaWardsData>`__
and configured this as `described here <model_data.html>`__.