INSTALL

You can either install Iris using the conda package manager or from source.

Installing using conda
----------------------

Iris is available using conda for the following platforms:
 * Linux 64-bit,
 * Mac OSX 64-bit, and
 * Windows 32-bit and 64-bit.

To install Iris using conda, you must first download and install conda,
for example from http://conda.pydata.org/miniconda.html.

Once conda is installed, you can install Iris using conda on any platform with
the following command::

  conda install -c conda-forge iris

If you wish to run any of the code examples
(see http://scitools.org.uk/iris/docs/latest/examples/index.html) you will also
need the Iris sample data. This can also be installed using conda::

  conda install -c conda-forge iris-sample-data

Further documentation on using conda and the features it provides can be found
at http://conda.pydata.org/docs/intro.html.


Installing from source
----------------------

The latest Iris source release is available from
https://github.com/SciTools/iris.

Iris makes use of a range of other libraries and python modules. These 
dependencies must be in place before you can successfully install 
Iris. Once you have satisfied the requirements detailed in the
``requirements`` directory, go to the root of Iris' and run::

  pip install .


In-place build - an alternative for developers
==============================================
We are very keen to encourage contributions to Iris. For this type of 
development activity an in-place build can be useful. Once you've cloned 
the Iris git repository you can perform an in-place build with::

  pip install -e .


Generating conda requirements
'''''''''''''''''''''''''''''

Requirements for Iris are stored in the ``requirements`` directory in the root of the source repository.
It is possible to generate a requirements file suitable for use with conda::

    python requirements/gen_conda_requirements.py > conda_requirements.txt

This may then be installed with::

    conda create -n my_iris_env --file conda_requirements.txt

Alternatively, a full requirements file that includes all optional dependencies can be produced with::

    python requirements/gen_conda_requirements.py --groups all > conda_requirements.txt


Custom site configuration
=========================
The default site configuration values can be overridden by creating the file
``iris/etc/site.cfg``. For example, the following snippet can be used to
specify a non-standard location for your dot executable::

  [System]
  dot_path = /usr/bin/dot

An example configuration file is available in ``iris/etc/site.cfg.template``.
See :py:func:`iris.config` for further configuration options.