====================
Installation of h5py
====================

This document is a very quick overview of the installation procedure for UNIX.
Full documentation is on the web at h5py.alfven.org.  Windows users should
download a binary installer; installation from source is only supported on
UNIX-like platforms (Linux and Mac OS-X).

On Mac OS-X, you can also install via MacPorts.

Before you start
----------------

You will first need to install HDF5, preferably via a package manager.  Both
versions 1.6 and 1.8 are supported.  NumPy 1.0.3 (numpy.scipy.org) or later
is also required. Keep in mind:

1. You will also need headers for development; sometimes this is offered
   separately as "libhdf5-dev" or similar.

2. HDF5 *must* be available as a dynamic library (libhdf5.so or similar), or
   h5py won't work.


Quick installation
------------------

H5py can now be automatically installed by setuptools' easy_install command:

    [sudo] easy_install h5py

Alternatively, you can install in the traditional manner by running setup.py:

    python setup.py build
    [sudo] python setup.py install


Custom installation
-------------------

Sometimes h5py may not be able to determine what version of HDF5 is installed.
Also, sometimes HDF5 may be installed in an unusual location.  You can
specify both your version of HDF5 and its location through the "configure"
command:

    $ python setup.py configure [--hdf5=/path/to/hdf5] [--api=<16 or 18>]
    $ python setup.py build
    $ [sudo] python setup.py install

Alternatively (for example, if installing with easy_install), you can use
environment variables:

    $ export HDF5_DIR=/path/to/hdf5
    $ export HDF5_API=<16 or 18>
    $ easy_install h5py

Keep in mind that on some platforms, "sudo" will filter out your environment
variables.  If you need to be a superuser to run easy_install, you might
want to issue all three of these commands in a root shell.

Settings issued with the "configure" command will always override those set
with environment variables.  Also, for technical reasons the configure command
must be run by itself, before any build commands.


Running tests
-------------

H5py has a battery of built-in tests.  To run them, simply do:

    python setup.py test

Please report test failures to the author, either to [h5py at alfven dot org]
or the bug tracker at http://h5py.googlecode.com.

Thanks for using h5py!