Added detailled installation documentation

README.rst

@@ -36,6 +36,8 @@ To install from source and recompile the HDF5 plugins, run::
 
 Installing from source can achieve better performances by enabling AVX2 and OpenMP if available.
 
+For more details, see the `installation documentation <doc/install.rst>`_.
+
 Documentation
 -------------
 

doc/install.rst

@@ -0,0 +1,72 @@
+==============
+ Installation
+==============
+
+Pre-built packages
+------------------
+
+Pre-built binaries of `hdf5plugin` are available from:
+
+- `pypi <https://pypi.org/project/hdf5plugin>`_, to install run:
+  ``pip install hdf5plugin [--user]``
+- `conda-forge <https://anaconda.org/conda-forge/hdf5plugin>`_, to install run:
+  ``conda install -c conda-forge hdf5plugin``
+
+To maximize compatibility, those binaries are built without optimization options (such as `AVX2`_ and `OpenMP`_).
+`Installation from source`_ can achieve better performances than pre-built binaries.
+
+Installation from source
+------------------------
+
+The build process enables compilation optimizations that are supported by the host machine.
+
+To install from source and recompile the HDF5 plugins, run::
+
+    pip install hdf5plugin --no-binary hdf5plugin [--user]
+
+To override the defaults that are probed from the machine, it is possible to specify build options.
+This is achieved by either setting environment variables or passing options to ``python setup.py build``, for example:
+
+- ``HDF5PLUGIN_OPENMP=False pip install hdf5plugin --no-binary hdf5plugin``
+- From the source directory: ``python setup.py build --openmp=False``
+
+Available options
+.................
+
+.. list-table::
+   :widths: 1 1 4
+   :header-rows: 1
+
+   * - Environment variable
+     - ``python setup.py build`` option
+     - Description
+   * - ``HDF5PLUGIN_HDF5_DIR``
+     - ``--hdf5``
+     - Custom path to HDF5 (as in h5py).
+   * - ``HDF5PLUGIN_HDF5_DIR``
+     - ``--openmp``
+     - Whether or not to compile with `OpenMP`_.
+       Default: True if probed (always False on macOS).
+   * - ``HDF5PLUGIN_NATIVE``
+     - ``--native``
+     - True to compile specifically for the host, False for generic support (For unix compilers only).
+       Default: True on supported architectures, False otherwise
+   * - ``HDF5PLUGIN_SSE2``
+     - ``--sse2``
+     - Whether or not to compile with `SSE2`_ support.
+       Default: True on ppc64le and when probed on x86, False otherwise
+   * - ``HDF5PLUGIN_AVX2``
+     - ``--avx2``
+     - Whether or not to compile with `AVX2`_ support. avx2=True requires sse2=True.
+       Default: True on x86 when probed, False otherwise
+   * - ``HDF5PLUGIN_CPP11``
+     - ``--cpp11``
+     - Whether or not to compile C++11 code if available.
+       Default: True if probed.
+
+Note: Boolean options are passed as ``True`` or ``False``.
+
+
+.. _AVX2: https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#Advanced_Vector_Extensions_2
+.. _SSE2: https://en.wikipedia.org/wiki/SSE2
+.. _OpenMP: https://www.openmp.org/