Instructions for the Installation of HDF5 Software ================================================== CONTENTS -------- 1. Obtaining HDF5 2. Warnings about compilers 2.1. GNU (Intel platforms) 2.2. DEC 2.3. SGI (Irix64 6.2) 2.4. Windows/NT 3. Quick installation 3.1. TFLOPS 3.2. Windows 3.3. Certain Virtual File Layer(VFL) 4. HDF5 dependencies 4.1. Zlib 4.2. MPI and MPI-IO 5. Full installation instructions for source distributions 5.1. Unpacking the distribution 5.1.1. Non-compressed tar archive (*.tar) 5.1.2. Compressed tar archive (*.tar.Z) 5.1.3. Gzip'd tar archive (*.tar.gz) 5.1.4. Bzip'd tar archive (*.tar.bz2) 5.2. Source vs. Build Directories 5.3. Configuring 5.3.1. Specifying the installation directories 5.3.2. Using an alternate C compiler 5.3.3. Additional compilation flags 5.3.4. Compiling HDF5 wrapper libraries 5.3.5. Specifying other programs 5.3.6. Specifying other libraries and headers 5.3.7. Static versus shared linking 5.3.8. Optimization versus symbolic debugging 5.3.9. Large (>2GB) vs. small (<2GB) file capability 5.3.10. Parallel vs. serial library 5.4. Building 5.5. Testing 5.6. Installing 6. Using the Library 7. Support ***************************************************************************** 1. Obtaining HDF5 The latest supported public release of HDF5 is available from ftp://hdf.ncsa.uiuc.edu/pub/dist/HDF5. For Unix platforms, it is available in tar format uncompressed or compressed with compress, gzip, or bzip2. For Microsoft Windows, it is in ZIP format. The HDF team also makes snapshots of the source code available on a regular basis. These snapshots are unsupported (that is, the HDF team will not release a bug-fix on a particular snapshot; rather any bug fixes will be rolled into the next snapshot). Furthermore, the snapshots have only been tested on a few machines and may not test correctly for parallel applications. Snapshots can be found at ftp://hdf.ncsa.uiuc.edu/pub/outgoing/hdf5/snapshots in a limited number of formats. 2. Warnings about compilers OUTPUT FROM THE FOLLOWING COMPILERS SHOULD BE EXTREMELY SUSPECT WHEN USED TO COMPILE THE HDF5 LIBRARY, ESPECIALLY IF OPTIMIZATIONS ARE ENABLED. IN ALL CASES, HDF5 ATTEMPTS TO WORK AROUND THE COMPILER BUGS BUT THE HDF5 DEVELOPMENT TEAM MAKES NO GUARANTEES THAT THERE ARE OTHER CODE GENERATION PROBLEMS. 2.1. GNU (Intel platforms) Versions before 2.8.1 have serious problems allocating registers when functions contain operations on `long long' data types. Supplying the `--disable-hsizet' switch to configure (documented below) will prevent hdf5 from using `long long' data types in situations that are known not to work, but it limits the hdf5 address space to 2GB. 2.2. DEC The V5.2-038 compiler (and possibly others) occasionally generates incorrect code for memcpy() calls when optimizations are enabled, resulting in unaligned access faults. HDF5 works around the problem by casting the second argument to `char *'. 2.3. SGI (Irix64 6.2) The Mongoose 7.00 compiler has serious optimization bugs and should be upgraded to MIPSpro 7.2.1.2m. Patches are available from SGI. 2.4. Windows/NT The MicroSoft Win32 5.0 compiler is unable to cast unsigned long long values to doubles. HDF5 works around this bug by first casting to signed long long and then to double. 3. Quick installation For those that don't like to read ;-) the following steps can be used to configure, build, test, and install the HDF5 library, header files, and support programs. $ gunzip 2GB) vs. small (<2GB) file capability In order to read or write files that could potentially be larger than 2GB it is necessary to use the non-ANSI `long long' data type on some platforms. However, some compilers (e.g., GNU gcc versions before 2.8.1 on Intel platforms) are unable to produce correct machine code for this data type. To disable use of the `long long' type on these machines say: $ ./configure --disable-hsizet 5.3.10. Parallel vs. serial library The HDF5 library can be configured to use MPI and MPI-IO for parallelizm on a distributed multi-processor system. Read the file INSTALL_parallel for detailed explanations. 5.3.11. Threadsafe capability The HDF5 library can be configured to be thread-safe (on a very large scale) with the with the `--enable-threadsafe' flag to configure. Read the file doc/TechNotes/ThreadSafeLibrary.html for further details. 5.3.12. Backward compatibility The 1.4 version of the HDF5 library can be configured to operate identically to the v1.2 library with the `--enable-hdf5v1_2' configure flag. This allows existing code to be compiled with the v1.4 library without requiring immediate changes to the application source code. This flag will only be supported in the v1.4 branch of the library, it will not be available in v1.5+. 5.3.13. Network stream capability The HDF5 library can be configured with a network stream file driver with the `--enable-stream-vfd' configure flag. This option compiles the "stream" Virtual File Driver into the main library. See the documentation on the Virtual File Layer for more details about the use of this driver. 5.4. Building The library, confidence tests, and programs can be build by saying just: $ make Note that if you supplied some other make command via the MAKE variable during the configuration step then that same command must be used here. When using GNU make you can add `-j -l6' to the make command to compile in parallel on SMP machines. Do not give a number after th `-j' since GNU make will turn it off for recursive invocations of make. $ make -j -l6 5.5. Testing HDF5 comes with various test suites, all of which can be run by saying $ make check To run only the tests for the library change to the `test' directory before issuing the command. Similarly, tests for the parallel aspects of the library are in `testpar' and tests for the support programs are in `tools'. Temporary files will be deleted by each test when it complets, but may continue to exist in an incomplete state if the test fails. To prevent deletion of the files define the HDF5_NOCLEANUP environment variable. 5.6. Installing The HDF5 library, include files, and support programs can be installed in a (semi-)public place by saying `make install'. The files are installed under the directory specified with `--prefix=DIR' (or '/usr/local') in directories named `lib', `include', and `bin'. The prefix directory must exist prior to `make install', but its subdirectories are created automatically. If `make install' fails because the install command at your site somehow fails, you may use the install-sh that comes with the source. You need to run ./configure again. $ INSTALL="$PWD/bin/install-sh -c" ./configure ... $ make install The library can be used without installing it by pointing the compiler at the `src' directory for both include files and libraries. However, the minimum which must be installed to make the library publically available is: The library: ./src/libhdf5.a The public header files: ./src/H5*public.h The main header file: ./src/hdf5.h The configuration information: ./src/H5config.h The support programs that are useful are: ./tools/h5ls (list file contents) ./tools/h5dump (dump file contents) ./tools/h5repart (repartition file families) ./tools/h5toh4 (hdf5 to hdf4 file converter) ./tools/h5debug (low-level file debugging) ./tools/h5import (a demo) ./tools/h4toh5 (hdf4 to hdf5 file converter) 6. Using the Library Please see the User Manual in the doc/html directory. Most programs will include and link with -lhdf5. Additional libraries may also be necessary depending on whether support for compression, etc. was compiled into the hdf5 library. A summary of the hdf5 installation can be found in the libhdf5.settings file in the same directory as the static and/or shared hdf5 libraries. 7. Support Support is described in the README file.