Debian Codegraph @

doc/install.rst

raw
1 ==============
2 Installation
3 ==============
4
5 Pre-built packages
6 ------------------
7
8 Pre-built binaries of `hdf5plugin` are available from:
9
10 - `pypi <https://pypi.org/project/hdf5plugin>`_, to install run:
11 ``pip install hdf5plugin [--user]``
12 - `conda-forge <https://anaconda.org/conda-forge/hdf5plugin>`_, to install run:
13 ``conda install -c conda-forge hdf5plugin``
14
15 To maximize compatibility, those binaries are built without optimization options (such as `AVX2`_ and `OpenMP`_).
16 `Installation from source`_ can achieve better performances than pre-built binaries.
17
18 Installation from source
19 ------------------------
20
21 The build process enables compilation optimizations that are supported by the host machine.
22
23 To install from source and recompile the HDF5 plugins, run::
24
25 pip install hdf5plugin --no-binary hdf5plugin [--user]
26
27 To override the defaults that are probed from the machine,
28 it is possible to specify build options by setting environment variables, for example:
29
30 - ``HDF5PLUGIN_OPENMP=False pip install hdf5plugin --no-binary hdf5plugin``
31 - From the source directory: ``HDF5PLUGIN_OPENMP=False pip install .``
32
33 Available options
34 .................
35
36 .. list-table::
37 :widths: 1 4
38 :header-rows: 1
39
40 * - Environment variable
41 - Description
42 * - ``HDF5PLUGIN_HDF5_DIR``
43 - Custom path to HDF5 (as in h5py).
44 It must contain a "include" subfolder and on Windows a "lib" subfolder with hdf5.lib.
45 * - ``HDF5PLUGIN_OPENMP``
46 - Whether or not to compile with `OpenMP`_.
47 Default: True if probed (always False on macOS).
48 * - ``HDF5PLUGIN_NATIVE``
49 - True to compile specifically for the host, False for generic support (For unix compilers only).
50 Default: True on supported architectures, False otherwise
51 * - ``HDF5PLUGIN_SSE2``
52 - Whether or not to compile with `SSE2`_ support.
53 Default: True on ppc64le and when probed on x86, False otherwise
54 * - ``HDF5PLUGIN_SSSE3``
55 - Whether or not to compile with `SSSE3`_ support.
56 Default: True when probed on x86, False otherwise
57 * - ``HDF5PLUGIN_AVX2``
58 - Whether or not to compile with `AVX2`_ support.
59 It requires enabling `SSE2`_ support.
60 Default: True on x86 when probed, False otherwise
61 * - ``HDF5PLUGIN_AVX512``
62 - Whether or not to compile with `AVX512`_ Foundation (F) and Byte and Word (BW) instruction sets support.
63 It requires enabling `SSE2`_ and `AVX2`_ support.
64 Default: True on x86 when probed, False otherwise
65 * - ``HDF5PLUGIN_BMI2``
66 - Whether or not to compile Zstandard with `BMI2`_ support if available.
67 Default: True on Linux and MacOS, False otherwise
68 * - ``HDF5PLUGIN_CPP11``
69 - Whether or not to compile C++11 code if available.
70 Default: True if probed.
71 * - ``HDF5PLUGIN_CPP14``
72 - Whether or not to compile C++14 code if available.
73 Default: True if probed.
74 * - ``HDF5PLUGIN_CPP20``
75 - Whether or not to compile C++20 code if available.
76 Default: True if probed.
77 * - ``HDF5PLUGIN_INTEL_IPP_DIR``
78 - Experimental feature: Path to Intel `IPP`_ root directory.
79 If provided, the LZ4 compression library and Blosc2 are set to use Intel `IPP`_.
80 Default: Do not use INTEL `IPP`_ libraries.
81
82 Note: Boolean options are passed as ``True`` or ``False``.
83
84
85 .. _AVX2: https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#Advanced_Vector_Extensions_2
86 .. _AVX512: https://en.wikipedia.org/wiki/AVX-512
87 .. _BMI2: https://en.wikipedia.org/wiki/X86_Bit_manipulation_instruction_set
88 .. _IPP: https://en.wikipedia.org/wiki/Integrated_Performance_Primitives
89 .. _SSE2: https://en.wikipedia.org/wiki/SSE2
90 .. _SSSE3: https://en.wikipedia.org/wiki/SSSE3
91 .. _OpenMP: https://www.openmp.org/