This file contains instructions for the installation of HDF5 on Unix-like systems. First, one must obtain a tarball of the HDF5 release from the ftp://hdf.ncsa.uiuc.edu/pub/dist/HDF5 repository. The files are available in uncompressed tar, gzip, bzip2, and compress formats. For those that like to live dangerously and don't like to read ;-) you can do the following: $ tar xf hdf5-1.0.0a.tar $ cd hdf5-1.0.0a $ sh configure $ make # Builds library and tools $ make test # Builds and runs confidence tests. # NOTE: if fails, run the # command in the test directory $ make install # Optional Note: For the users of the Intel TFLOPS machine, a special sequence of steps for the install may be found in the file: INSTALL.ascired. 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. * 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. * 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*'. * 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. * 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. ======= Step 0: Install optional third-party packages. * Zlib compression library, version 1.1.2 or later is used for the `deflate' compression method if available; otherwise no compression filters will be predefined. The source code can be found at http://www.cdrom.com/pub/infozip/zlib Step 1. Unpack the source tree. * The tarball will unpack into an hdf5-1.1.0 directory with one of the following commands: $ tar xf hdf5-1.1.0.tar OR $ gunzip .o step. AR Name of the `ar' program. RANLIB Name of the `ranlib' program or `:' if none. MAKE Name of the `make' program (GNU make is preferred) * The default compiler is `cc -n32' on Irix6.x platforms and `cc -64' on Irix64 platforms. To use an alternate compiler (such as `cc -o32') specify the name and compiler selection switch with the CC environment variable: $ CC='cc -o32' ./configure ...... * This version of HDF5 is normally built with various debugging code enabled. To turn it off add the `--disable-debug' switch to the configure command. Even if debugging support is compiled into the library one must still enable the code at runtime with the HDF5_DEBUG environment variable (see Debugging.html). Including debugging support in the library (whether it's enabled or not) may incur a significant run-time penalty. * This version of HDF5 is normally built with support for symbolic debugging with dbx or gdb and without compiler optimization switches. To disable symbolic debugging and enable optimizations add `--enable-production' to the configure command. * This version of HDF5 is normally built with the ability to print the names, arguments, and return values of all API functions when they're called. For more information refer to the Debugging.html file. To disable tracing support add `--disable-trace' to the configure command. * Configure will look for the GNU zlib (a compression library) in the standard places for your environment. If it's installed in a non-standard place then absolute path names can be specified with `--with-zlib=INCDIR,LIBDIR' for the include file and/or library. To prevent detection of zlib use `--without-zlib'. * The HDF5-to-HDF4 conversion tool requires the HDF4 library and header files which are auto-detected by configure. If they are in a non-standard place then absolute path names can be specified with `--with-hdf4=INCDIR,LIBDIR' for the include file and/or library. To prevent detection of hdf4 use `--without-hdf4'. Beware of the GNU zlib that comes with hdf4 -- it's too old to use with hdf5 (hdf4 tools can be linked with the newer versions of zlib). * Old versions of gcc (<2.8.0) may experience register allocation problems on some architectures. If this happens then the `--disable-hsizet' can be given but the resulting library will be unable to handle datasets larger than 4GB. * Libraries, include files, programs, and documentation are installed (when one says `make install') under /usr/local/lib, /usr/local/include, /usr/local/bin, and /usr/local/man. However, if you want them in some other location you can specify a prefix to use instead of /usr/local. For instance, to install in /usr/lib, /usr/include, /usr/bin, and /usr/man one would say $ ./configure --prefix=/usr The library can be used directly from the source tree without installing it. Step 3. Compile library, tests, and programs. * Build library targets by saying $ make Note: If you supplied some other make command through the MAKE environment variable in the previous step then use that command instead. The same applies below. Note: 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 the `-j' since GNU make will turn it off for recursive invocations of make. Step 4. Run confidence tests. * All confidence tests should be run by saying $ make test The command will fail if any test fails, and one will see the word "*FAIL*" in the output. * Some old versions of make will report that `test is up to date'. If this happens then run `make _test' instead or run `make test' from within the test directory. * Temporary files will be deleted by each test when it completes, 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. Step 5. Install public files. * Install the library, header files, and programs by saying: $ make install * This step will fail unless you have permission to write to the installation directories. Of course, you can use the header files, library, and programs directly out of the source tree if you like, skipping this step. The directory specified for the --prefix switch (or "/usr/local") must exist, but the directories under it are created automatically by make. * The minimum which must be installed are: 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 * Additional useful things which are installed: The tools library: ./tools/libh5tools.a Some tools: ./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) Step 6. Subscribe to mailing lists. * Subscribe to the mailing lists described in the README file.