summaryrefslogtreecommitdiffstats
path: root/release_docs
diff options
context:
space:
mode:
authorAlbert Cheng <acheng@hdfgroup.org>2008-02-14 14:32:34 (GMT)
committerAlbert Cheng <acheng@hdfgroup.org>2008-02-14 14:32:34 (GMT)
commit56060e7ec26abf1deb94ae9ce4adef4122f2702d (patch)
treeee187ba0b171caaeeabd6bc86d91348891b2da5c /release_docs
parentc3f33288a2bfdfe29111a340cd777e9cc3023c40 (diff)
downloadhdf5-56060e7ec26abf1deb94ae9ce4adef4122f2702d.zip
hdf5-56060e7ec26abf1deb94ae9ce4adef4122f2702d.tar.gz
hdf5-56060e7ec26abf1deb94ae9ce4adef4122f2702d.tar.bz2
[svn-r14582] Purpose:
Fold all the updates made for v1.8.0 release to the main trunk. Versions are from r14548 to r14556. Changes are, Updated section 4 for v1.8 release. (May still check the v1.6 INSTALL to see if something can be adopted from there. But this is good for v1.8 release.) Moved the section 2. "Warnings about compilers" to Appendix A; renumbered section 3-7 to section 2-6 and fixed all section references. Updated Website names from ncsa.uiuc.edu to hdfgroup.org or hdfgroup.uiuc.edu. Updated section 1-3 and some of section 4. Quick editorial review. Convert tabs to spaces for consistent display and printing. Verify and fix links and references. Moved the following three paragraphs to the Appendix part since they have old information that are not relevant most recent machines or compilers. "Large (>2GB) versus small (<2GB) file capability", "Building and testing with Intel compilers" "Building and testing with PGI compilers"
Diffstat (limited to 'release_docs')
-rw-r--r--release_docs/INSTALL1315
1 files changed, 687 insertions, 628 deletions
diff --git a/release_docs/INSTALL b/release_docs/INSTALL
index 1444bf2..4a9a567 100644
--- a/release_docs/INSTALL
+++ b/release_docs/INSTALL
@@ -1,674 +1,733 @@
- Instructions for the Installation of HDF5 Software
- ==================================================
-
-WARNING: This file was not updated for the 1.8.0-beta* releases. If you have any problems with the HDF5
- installation please contact help@hdfgroup.org
-
- 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. Windows
- 3.2. RedStorm (Cray XT3)
-
- 4. HDF5 dependencies
- 4.1. Zlib
- 4.2 Szip
- 4.3. 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. Configuring for 64-bit support
- 5.3.4. Additional compilation flags
- 5.3.5. Compiling HDF5 wrapper libraries
- 5.3.6. Specifying other programs
- 5.3.7. Specifying other libraries and headers
- 5.3.8. Static versus shared linking
- 5.3.9. Optimization versus symbolic debugging
- 5.3.10. Large (>2GB) vs. small (<2GB) file capability
- 5.3.11. Parallel vs. serial library
- 5.3.12. Threadsafe capability
- 5.3.13. Backward compatibility
- 5.3.14. Network stream capability
- 5.4. Building
- 5.5. Testing
- 5.6. Installing
- 5.7 Building and testing with Intel compilers
- 5.8 Building and testing with PGI compilers
-
- 6. Using the Library
-
- 7. Support
+Instructions for the Installation of HDF5 Software
+==================================================
+
+This file provides instructions for installing the HDF5 software.
+If you have any problems with the installation, please see The HDF Group's
+support page at the following location:
+
+ http://www.hdfgroup.org/services/support.html
+
+CONTENTS
+--------
+ 1. Obtaining HDF5
+
+ 2. Quick installation
+ 2.1. Windows
+ 2.2. RedStorm (Cray XT3)
+
+ 3. HDF5 dependencies
+ 3.1. Zlib
+ 3.2 Szip (optional)
+ 3.3. MPI and MPI-IO
+
+ 4. Full installation instructions for source distributions
+ 4.1. Unpacking the distribution
+ 4.1.1. Non-compressed tar archive (*.tar)
+ 4.1.2. Compressed tar archive (*.tar.Z)
+ 4.1.3. Gzip'd tar archive (*.tar.gz)
+ 4.1.4. Bzip'd tar archive (*.tar.bz2)
+ 4.2. Source versus build directories
+ 4.3. Configuring
+ 4.3.1. Specifying the installation directories
+ 4.3.2. Using an alternate C compiler
+ 4.3.3. Configuring for 64-bit support
+ 4.3.4. Additional compilation flags
+ 4.3.5. Compiling HDF5 wrapper libraries
+ 4.3.6. Specifying other programs
+ 4.3.7. Specifying other libraries and headers
+ 4.3.8. Static versus shared linking
+ 4.3.9. Optimization versus symbolic debugging
+ 4.3.10. Parallel versus serial library
+ 4.3.11. Threadsafe capability
+ 4.3.12. Backward compatibility
+ 4.4. Building
+ 4.5. Testing
+ 4.6. Installing HDF5
+
+ 5. Using the Library
+
+ 6. Support
+
+ A. Warnings about compilers
+ A.1. GNU (Intel platforms)
+ A.2. DEC
+ A.3. SGI (Irix64 6.2)
+ A.4. Windows/NT
+
+ B. Large (>2GB) versus small (<2GB) file capability
+
+ C. Building and testing with other compilers
+ C.1. Building and testing with Intel compilers
+ C.2. Building and testing with PGI compilers
*****************************************************************************
1. Obtaining HDF5
- The latest supported public release of HDF5 is available from
- ftp://hdf.ncsa.uiuc.edu/HDF5/current/src. For Unix platforms, it is
- available in tar format compressed with gzip. 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. COMPAQ/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 *'.
- The fortran module (5.4.1a) fails in compiling some fortran
- programs. Need to use 5.5.0 or more.
-
-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.
-
- A link warning: defaultlib "LIBC" conflicts with use of other libs
- appears for debug version of VC++ 6.0. This warning will not affect
- building and testing hdf5 libraries.
-
-
-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 < hdf5-1.6.0.tar.gz | tar xf -
- $ cd hdf5-1.6.0
- $ make check
- $ make install
-
-3.1. Windows
- Users of Microsoft Windows should see the INSTALL_Windows for
- detailed instructions.
-
-3.2. RedStorm (Cray Xt3)
- Users of the Red Storm machine, after reading this file, should read
- the Red Storm section in the INSTALL_parallel file for specific
- instructions for the Red Storm machine. The same instructions would
- probably work for other Cray XT3 systems but they have not been
- verified.
-
-
-4. HDF5 dependencies
-4.1. Zlib
- The HDF5 library has a predefined compression filter that uses
- the "deflate" method for chunked datatsets. If zlib-1.1.2 or
- later is found then HDF5 will use it, otherwise HDF5's predefined
- compression method will degenerate to a no-op (the compression
- filter will succeed but the data will not be compressed).
-
-4.2. Szip
- The HDF5 library has a predefined compression filter that uses
- the extended-Rice lossless compression algorithm for chunked
- datatsets. For more information about Szip compression and license terms
- see http://hdf.ncsa.uiuc.edu/HDF5/doc_resource/SZIP/index.html.
- Precompiled szip binaries for each supported platform and source tar ball
- file can be found at ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current/
-
-4.3. MPI and MPI-IO
- The parallel version of the library is built upon the foundation
- provided by MPI and MPI-IO. If these libraries are not available
- when HDF5 is configured then only a serial version of HDF5 can be
- built.
-
-
-5. Full installation instructions for source distributions
-5.1. Unpacking the distribution
- The HDF5 source code is distributed in a variety of formats which
- can be unpacked with the following commands, each of which
- creates an `hdf5-1.6.0' directory.
-
-5.1.1. Non-compressed tar archive (*.tar)
-
- $ tar xf hdf5-1.6.0.tar
-
-5.1.2. Compressed tar archive (*.tar.Z)
-
- $ uncompress -c < hdf5-1.6.0.tar.Z | tar xf -
-
-5.1.3. Gzip'd tar archive (*.tar.gz)
-
- $ gunzip < hdf5-1.6.0.tar.gz | tar xf -
-
-5.1.4. Bzip'd tar archive (*.tar.bz2)
-
- $ bunzip2 < hdf5-1.6.0.tar.bz2 | tar xf -
-
-5.2. Source vs. Build Directories
- On most systems the build can occur in a directory other than the
- source directory, allowing multiple concurrent builds and/or
- read-only source code. In order to accomplish this, one should
- create a build directory, cd into that directory, and run the
- `configure' script found in the source directory (configure
- details are below).
-
- Unfortunately, this does not work on recent Irix platforms (6.5?
- and later) because that `make' doesn't understand the VPATH
- variable. However, hdf5 also supports Irix `pmake' which has a
- .PATH target which serves a similar purpose. Here's what the man
- pages say about VPATH, which is the facility used by HDF5
- makefiles for this feature:
-
- The VPATH facility is a derivation of the undocumented
- VPATH feature in the System V Release 3 version of make.
- System V Release 4 has a new VPATH implementation, much
- like the pmake(1) .PATH feature. This new feature is also
- undocumented in the standard System V Release 4 manual
- pages. For this reason it is not available in the IRIX
- version of make. The VPATH facility should not be used
- with the new parallel make option.
-
-5.3. Configuring
- HDF5 uses the GNU autoconf system for configuration, which
- detects various features of the host system and creates the
- Makefiles. On most systems it should be sufficient to say:
-
- $ ./configure OR
- $ sh configure
-
- The configuration process can be controlled through environment
- variables, command-line switches, and host configuration files.
- For a complete list of switches type:
-
- $ ./configure --help
-
- The host configuration files are located in the `config'
- directory and are based on architecture name, vendor name, and/or
- operating system which are displayed near the beginning of the
- `configure' output. The host config file influences the behavior
- of configure by setting or augmenting shell variables.
-
-5.3.1. Specifying the installation directories
- Typing `make install' will install the HDF5 library, header
- files, examples, and support programs in /usr/local/lib,
- /usr/local/include, /usr/local/doc/hdf5/examples, and
- /usr/local/bin. To use a path other than
- /usr/local specify the path with the `--prefix=PATH' switch:
-
- $ ./configure --prefix=$HOME
-
- If shared libraries are being built (the default) then the final
- home of the shared library must be specified with this switch
- before the library and executables are built.
-
- HDF5 can be installed into a different location than the prefix
- specified at configure time; see the section on Installing HDF5
- for more details.
-
-5.3.2. Using an alternate C compiler
- By default, configure will look for the C compiler by trying
- `gcc' and `cc'. However, if the environment variable "CC" is set
- then its value is used as the C compiler (users of csh and
- derivatives will need to prefix the commands below with `env').
- For instance, to use the native C compiler on a system which also
- has the GNU gcc compiler:
-
- $ CC=cc ./configure
-
- A parallel version of hdf5 can be built by specifying `mpicc'
- as the C compiler (the `--enable-parallel' flag documented
- below is optional in this case). Using the `mpicc' compiler
- will insure that the correct MPI and MPI-IO header files and
- libraries are used.
-
- $ CC=/usr/local/mpi/bin/mpicc ./configure
-
-5.3.3. Configuring for 64-bit support
- Several machine architectures support 32-bit or 64-bit binaries.
- The options below describe how to enable support for different options.
-
- On Irix64 the default compiler is `cc'. To use an alternate
- compiler specify it with the CC variable:
-
- $ CC='cc -n32' ./configure
-
- Similarly, users compiling on a Solaris machine and desiring to
- build the distribution with 64-bit support should specify the
- correct flags with the CC variable:
-
- $ CC='cc -xarch=v9' ./configure
-
- To configure AIX 64-bit support including fortran API and C++,
- (Note: need to set $AR to 'ar -X 64'.)
- Serial:
- $ CFLAGS=-q64 FFLAGS=-q64 CXXFLAGS=-q64 AR='ar -X 64'\
- $ ./configure --enable-fortran
- Parallel: (C++ not supported with parallel)
- $ CFLAGS=-q64 FFLAGS=-q64 AR='ar -X 64'\
- $ ./configure --enable-fortran
-
-5.3.4. Additional compilation flags
- If addtional flags must be passed to the compilation commands
- then specify those flags with the CFLAGS variable. For instance,
- to enable symbolic debugging of a production version of HDF5 one
- might say:
-
- $ CFLAGS=-g ./configure --enable-production
-
-5.3.5. Compiling HDF5 wrapper libraries
- One can optionally build the Fortran and/or C++ interface to the
- HDF5 C library. By default, both options are disabled. To build
- them, specify `--enable-fortran' and `--enable-cxx' respectively.
-
- $ ./configure --enable-fortran
- $ ./configure --enable-cxx
-
- Configuration will halt if a working Fortran 90 or 95 compiler or
- C++ compiler is not found. Currently, the Fortran configure tests
- for these compilers in order: f90, pgf90, f95. To use an
- alternative compiler specify it with the F9X variable:
-
- $ F9X=/usr/local/bin/g95 ./configure --enable-fortran
-
- Note: The Fortran and C++ interfaces are not supported on all the
- platforms the main HDF5 library supports. Also, the Fortran
- interface supports parallel HDF5 while the C++ interface does
- not.
-
- Note: On Cray T3Es the following files should be modified before
- building the Fortran Library:
- fortran/src/H5Dff.f90
- fortran/src/H5Aff.f90
- fortran/src/H5Pff.f90
- Check for "Comment if on T3E ..." comment and comment out
- specified lines or use a patch from HDF FTP server
- ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current/
-
- Note: See sections 5.7 and 5.8 for how to build Fortran Library with
- PGI or Intel compilers.
-
-5.3.6. Specifying other programs
- The build system has been tuned for use with GNU make but works
- also with other versions of make. If the `make' command runs a
- non-GNU version but a GNU version is available under a different
- name (perhaps `gmake') then HDF5 can be configured to use it by
- setting the MAKE variable. Note that whatever value is used for
- MAKE must also be used as the make command when building the
- library:
-
- $ MAKE=gmake ./configure
- $ gmake
-
- The `AR' and `RANLIB' variables can also be set to the names of
- the `ar' and `ranlib' (or `:') commands to override values
- detected by configure.
-
- The HDF5 library, include files, and utilities are installed
- during `make install' (described below) with a BSD-compatible
- install program detected automatically by configure. If none is
- found then the shell script bin/install-sh is used. Configure
- doesn't check that the install script actually works, but if a
- bad install is detected on your system (e.g., on the ASCI blue
- machine as of March 2, 1999) you have two choices:
-
- 1. Copy the bin/install-sh program to your $HOME/bin
- directory, name it `install', and make sure that $HOME/bin
- is searched before the system bin directories.
-
- 2. Specify the full path name of the `install-sh' program
- as the value of the INSTALL environment variable. Note: do
- not use `cp' or some other program in place of install
- because the HDF5 makefiles also use the install program to
- also change file ownership and/or access permissions.
-
-5.3.7. Specifying other libraries and headers
- Configure searches the standard places (those places known by the
- systems compiler) for include files and header files. However,
- additional directories can be specified by using the CPPFLAGS
- and/or LDFLAGS variables:
-
- $ CPPFLAGS=-I/home/robb/include \
+ The latest supported public release of HDF5 is available from
+ ftp://ftp.hdfgroup.org/HDF5/current/src. For Unix and UNIX-like
+ platforms, it is available in tar format compressed with gzip.
+ 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, in a limited number of formats, can be found on THG's
+ development FTP server:
+
+ ftp://ftp.hdfgroup.uiuc.edu/pub/outgoing/hdf5/snapshots
+
+
+2. Quick installation
+ For those who 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. For example, to install HDF5 version X.Y.Z at
+ location /usr/local/hdf5, use the following steps.
+
+ $ gunzip < hdf5-X.Y.Z.tar.gz | tar xf -
+ $ cd hdf5-X.Y.Z
+ $ ./configure --prefix=/usr/local/hdf5 <more configure_flags>
+ $ make
+ $ make check # run test suite.
+ $ make install
+ $ make check-install # verify installation.
+
+ Some versions of the tar command support the -z option. In such cases,
+ the first step above can be simplified to the following:
+
+ $ tar zxf hdf5-X.Y.Z.tar.gz
+
+ <configure_flags> above refers to the configure flags appropriate
+ to your installation. For example, to install HDF5 with the
+ Fortran and C++ interfaces and with SZIP compression, the
+ configure line might read as follows:
+
+ $ ./configure --prefix=/usr/local/hdf5 --enable-fortran \
+ --enable-cxx --with-szlib=PATH_TO_SZIP
+
+ In this case, PATH_TO_SZIP would be replaced with the path to the
+ installed location of the SZIP library.
+
+2.1. Windows
+ Users of Microsoft Windows should see the INSTALL_Windows files for
+ detailed instructions.
+
+2.2. RedStorm (Cray XT3)
+ Users of the Red Storm machine, after reading this file, should read
+ the Red Storm section in the INSTALL_parallel file for specific
+ instructions for the Red Storm machine. The same instructions would
+ probably work for other Cray XT3 systems, but they have not been
+ verified.
+
+
+3. HDF5 dependencies
+3.1. Zlib
+ The HDF5 Library includes a predefined compression filter that
+ uses the "deflate" method for chunked datasets. If zlib-1.1.2 or
+ later is found, HDF5 will use it. Otherwise, HDF5's predefined
+ compression method will degenerate to a no-op; the compression
+ filter will succeed but the data will not be compressed.
+
+3.2. Szip (optional)
+ The HDF5 Library includes a predefined compression filter that
+ uses the extended-Rice lossless compression algorithm for chunked
+ datasets. For more information about Szip compression and license
+ terms, see http://hdfgroup.org/doc_resource/SZIP/.
+
+ Precompiled Szip binaries for each supported platform and a source
+ tar file can be found at ftp://ftp.hdfgroup.org/lib-external/szip/.
+
+ To configure the HDF5 Library with the Szip compression filter, use
+ the '--enable-szlib=/PATH_TO_SZIP' flag. For more information, see
+ section 4.3.7, "Specifying other libraries and headers."
+
+ Starting with release 1.6.3, Szip library binaries are distributed
+ with the encoder enabled (a license may be required to use this binary)
+ and with the encoder disabled (freely usable without a license).
+ If the encoder enabled binary is used, Szip compression encoding is
+ available for an HDF5 application; if the encoder disabled binary is
+ used, Szip compression is not available. Szip decoding is always
+ available for applications (i.e., an HDF5 application can always read
+ Szip-compressed data) if the Szip filter is present, regardless of the
+ binary used.
+
+3.3. MPI and MPI-IO
+ The parallel version of the library is built upon the foundation
+ provided by MPI and MPI-IO. If these libraries are not available
+ when HDF5 is configured, only a serial version of HDF5 can be built.
+
+
+4. Full installation instructions for source distributions
+
+4.1. Unpacking the distribution
+ The HDF5 source code is distributed in a variety of formats which
+ can be unpacked with the following commands, each of which creates an
+ 'hdf5-X.Y.Z' directory, where X.Y.Z is the HDF5 version numbers.
+
+4.1.1. Non-compressed tar archive (*.tar)
+
+ $ tar xf hdf5-X.Y.Z.tar
+
+4.1.2. Compressed tar archive (*.tar.Z)
+
+ $ uncompress -c < hdf5-X.Y.Z.tar.Z | tar xf -
+ Or
+ $ tar Zxf hdf5-X.Y.Z.tar.Z
+
+4.1.3. Gzip'd tar archive (*.tar.gz)
+
+ $ gunzip < hdf5-X.Y.Z.tar.gz | tar xf -
+ Or
+ $ tar zxf hdf5-X.Y.Z.tar.gz
+
+4.1.4. Bzip'd tar archive (*.tar.bz2)
+
+ $ bunzip2 < hdf5-X.Y.Z.tar.bz2 | tar xf -
+ Or
+ $ tar jxf hdf5-X.Y.Z.tar.bz2
+
+4.2. Source versus build directories
+ On most systems the build can occur in a directory other than the
+ source directory, allowing multiple concurrent builds and/or
+ read-only source code. In order to accomplish this, one should
+ create a build directory, cd into that directory, and run the
+ `configure' script found in the source directory (configure
+ details are below). For example,
+ $ mkdir built-fortran
+ $ cd build-fortran
+ $ ../hdf5-X.Y.Z/configure --enable-fortran ...
+
+ Unfortunately, this does not work on recent Irix platforms (6.5?
+ and later) because that `make' does not understand the VPATH variable.
+ However, HDF5 also supports Irix `pmake' which has a .PATH target
+ which serves a similar purpose. Here's what the Irix man pages say
+ about VPATH, the facility used by HDF5 makefiles for this feature:
+
+ The VPATH facility is a derivation of the undocumented
+ VPATH feature in the System V Release 3 version of make.
+ System V Release 4 has a new VPATH implementation, much
+ like the pmake(1) .PATH feature. This new feature is also
+ undocumented in the standard System V Release 4 manual
+ pages. For this reason it is not available in the IRIX
+ version of make. The VPATH facility should not be used
+ with the new parallel make option.
+
+4.3. Configuring
+ HDF5 uses the GNU autoconf system for configuration, which
+ detects various features of the host system and creates the
+ Makefiles. On most systems it should be sufficient to say:
+
+ $ ./configure
+ Or
+ $ sh configure
+
+ The configuration process can be controlled through environment
+ variables, command-line switches, and host configuration files.
+ For a complete list of switches type:
+
+ $ ./configure --help
+
+ The host configuration files are located in the `config'
+ directory and are based on architecture name, vendor name, and/or
+ operating system which are displayed near the beginning of the
+ `configure' output. The host config file influences the behavior
+ of configure by setting or augmenting shell variables.
+
+4.3.1. Specifying the installation directories
+ The default installation location is the HDF5 directory created in
+ the build directory. Typing `make install' will install the HDF5
+ Library, header files, examples, and support programs in hdf5/lib,
+ hdf5/include, hdf5/doc/hdf5/examples, and hdf5/bin. To use a path
+ other than hdf5, specify the path with the `--prefix=PATH' switch:
+
+ $ ./configure --prefix=/usr/local
+
+ If shared libraries are being built (the default), the final
+ home of the shared library must be specified with this switch
+ before the library and executables are built.
+
+ HDF5 can be installed into a different location than the prefix
+ specified at configure time; see section 4.6, "Installing HDF5,"
+ for more details.
+
+4.3.2. Using an alternate C compiler
+ By default, configure will look for the C compiler by trying
+ `gcc' and `cc'. However, if the environment variable "CC" is set
+ then its value is used as the C compiler. For instance, one would
+ use the following line to specify the native C compiler on a system
+ that also has the GNU gcc compiler (users of csh and derivatives
+ will need to prefix the commands below with `env'):
+
+ $ CC=cc ./configure
+
+ A parallel version of HDF5 can be built by specifying `mpicc'
+ as the C compiler. (The `--enable-parallel' flag documented
+ below is optional in this case.) Using the `mpicc' compiler
+ will insure that the correct MPI and MPI-IO header files and
+ libraries are used.
+
+ $ CC=/usr/local/mpi/bin/mpicc ./configure
+
+4.3.3. Configuring for 64-bit support
+ Several machine architectures support 32-bit or 64-bit binaries.
+ The options below describe how to enable support for different options.
+
+ On Irix64, the default compiler is `cc'. To use an alternate compiler,
+ specify it with the CC variable:
+
+ $ CC='cc -n32' ./configure
+
+ Similarly, users compiling on a Solaris machine and desiring to
+ build the distribution with 64-bit support should specify the
+ correct flags with the CC variable:
+
+ $ CC='cc -xarch=v9' ./configure
+
+ To configure AIX 64-bit support including the Fortran and C++ APIs,
+ (Note: need to set $AR to 'ar -X 64'.)
+ Serial:
+ $ CFLAGS=-q64 FFLAGS=-q64 CXXFLAGS=-q64 AR='ar -X 64'\
+ ./configure --enable-fortran
+ Parallel: (C++ not supported with parallel)
+ $ CFLAGS=-q64 FFLAGS=-q64 AR='ar -X 64'\
+ ./configure --enable-fortran
+
+4.3.4. Additional compilation flags
+ If addtional flags must be passed to the compilation commands,
+ specify those flags with the CFLAGS variable. For instance,
+ to enable symbolic debugging of a production version of HDF5, one
+ might say:
+
+ $ CFLAGS=-g ./configure --enable-production
+
+4.3.5. Compiling HDF5 wrapper libraries
+ One can optionally build the Fortran and/or C++ interfaces to the
+ HDF5 C library. By default, both options are disabled. To build
+ them, specify `--enable-fortran' and `--enable-cxx', respectively.
+
+ $ ./configure --enable-fortran
+ $ ./configure --enable-cxx
+
+ Configuration will halt if a working Fortran 90 or 95 compiler or
+ C++ compiler is not found. Currently, the Fortran configure tests
+ for these compilers in order: f90, pgf90, f95. To use an
+ alternate compiler specify it with the FC variable:
+
+ $ FC=/usr/local/bin/g95 ./configure --enable-fortran
+
+ Note: The Fortran and C++ interfaces are not supported on all the
+ platforms the main HDF5 Library supports. Also, the Fortran
+ interface supports parallel HDF5 while the C++ interface does
+ not.
+
+ Note: See sections 4.7 and 4.8 for building the Fortran library with
+ Intel or PGI compilers.
+
+4.3.6. Specifying other programs
+ The build system has been tuned for use with GNU make but also
+ works with other versions of make. If the `make' command runs a
+ non-GNU version but a GNU version is available under a different
+ name (perhaps `gmake'), then HDF5 can be configured to use it by
+ setting the MAKE variable. Note that whatever value is used for
+ MAKE must also be used as the make command when building the
+ library:
+
+ $ MAKE=gmake ./configure
+ $ gmake
+
+ The `AR' and `RANLIB' variables can also be set to the names of
+ the `ar' and `ranlib' (or `:') commands to override values
+ detected by configure.
+
+ The HDF5 Library, include files, and utilities are installed
+ during `make install' (described below) with a BSD-compatible
+ install program detected automatically by configure. If none is
+ found, the shell script bin/install-sh is used. Configure does not
+ check that the install script actually works; if a bad install is
+ detected on your system (e.g., on the ASCI blue machine as of
+ March 2, 1999) you have two choices:
+
+ 1. Copy the bin/install-sh program to your $HOME/bin
+ directory, name it `install', and make sure that $HOME/bin
+ is searched before the system bin directories.
+
+ 2. Specify the full path name of the `install-sh' program
+ as the value of the INSTALL environment variable. Note: do
+ not use `cp' or some other program in place of install
+ because the HDF5 makefiles also use the install program to
+ change file ownership and/or access permissions.
+
+4.3.7. Specifying other libraries and headers
+ Configure searches the standard places (those places known by the
+ systems compiler) for include files and header files. However,
+ additional directories can be specified by using the CPPFLAGS
+ and/or LDFLAGS variables:
+
+ $ CPPFLAGS=-I/home/robb/include \
LDFLAGS=-L/home/robb/lib \
- ./configure
-
- HDF5 uses the zlib library for two purposes: it provides support
- for the HDF5 deflate data compression filter, and it is used by
- the h5toh4 converter and the h4toh5 converter in support of
- HDF4. Configure searches the standard places (plus those
- specified above with CPPFLAGS and LDFLAGS variables) for the zlib
- headers and library. The search can be disabled by specifying
- `--without-zlib' or alternate directories can be specified with
- `--with-zlib=INCDIR,LIBDIR' or through the CPPFLAGS and LDFLAGS
- variables:
-
- $ ./configure --with-zlib=/usr/unsup/include,/usr/unsup/lib
-
- $ CPPFLAGS=-I/usr/unsup/include \
- LDFLAGS=-L/usr/unsup/lib \
- ./configure
-
- The HDF5-to-HDF4 and HDF4-to-HDF5 conversion tool requires the
- HDF4 library and header files which are detected the same way as
- zlib. The switch to give to configure is `--with-hdf4'. Note
- that HDF5 requires a newer version of zlib than the one shipped
- with some versions of HDF4. Also, unless you have the "correct"
- version of hdf4 the confidence testing will fail in the tools
- directory.
-
- HDF5 has Szip predefined compression method (see 4.2). To enable
- Szip compression, HDF5 library has to be configured and build using
- Szip Library
-
- $ ./configure --with-szlib=/Szip_Install_Directory
-
-5.3.8. Static versus shared linking
- The build process will create static libraries on all systems and
- shared libraries on systems that support dynamic linking to a
- sufficient degree. Either form of library may be suppressed by
- saying `--disable-static' or `--disable-shared'.
-
- $ ./configure --disable-shared
-
- Shared C++ and Fortran libraries will be built if shared libraries
- are enabled.
-
- To build only statically linked executables on platforms which
- support shared libraries, use the `--enable-static-exec' flag.
-
- $ ./configure --enable-static-exec
-
-5.3.9. Optimization versus symbolic debugging
- The library can be compiled to provide symbolic debugging support
- so it can be debugged with gdb, dbx, ddd, etc or it can be
- compiled with various optimizations. To compile for symbolic
- debugging (the default for snapshots) say `--disable-production';
- to compile with optimizations (the default for supported public
- releases) say `--enable-production'. On some systems the library
- can also be compiled for profiling with gprof by saying
- `--enable-production=profile'.
-
- $ ./configure --disable-production #symbolic debugging
- $ ./configure --enable-production #optimized code
- $ ./configure --enable-production=profile #for use with gprof
-
- Regardless of whether support for symbolic debugging is enabled,
- the library also is able to perform runtime debugging of certain
- packages (such as type conversion execution times, and extensive
- invariant condition checking). To enable this debugging supply a
- comma-separated list of package names to to the `--enable-debug'
- switch (see Debugging.html for a list of package names).
- Debugging can be disabled by saying `--disable-debug'. The
- default debugging level for snapshots is a subset of the
- available packages; the default for supported releases is no
- debugging (debugging can incur a significant runtime penalty).
-
- $ ./configure --enable-debug=s,t #debug only H5S and H5T
- $ ./configure --enable-debug #debug normal packages
- $ ./configure --enable-debug=all #debug all packages
- $ ./configure --disable-debug #no debugging
-
- HDF5 is also able to print a trace of all API function calls,
- their arguments, and the return values. To enable or disable the
- ability to trace the API say `--enable-trace' (the default for
- snapthots) or `--disable-trace' (the default for public
- releases). The tracing must also be enabled at runtime to see any
- output (see Debugging.html).
-
-5.3.10. Large (>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.11. 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.12. 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
- the configure script. Some platforms may also require the
- '-with-pthread=INC,LIB' (or '--with-pthread=DIR') flag to the configure
- script as well. Read the file doc/TechNotes/ThreadSafeLibrary.html
- for further details.
-
-5.3.13. Backward compatibility
- The 1.8 version of the HDF5 library can be configured to operate
- identically to the v1.6 library with the `--enable-hdf5v1_6'
- configure flag. This allows existing code to be compiled with the
- v1.8 library without requiring immediate changes to the
- application source code. This flag will only be supported in the
- v1.8 branch of the library, it will not be available in v1.9+.
-
-5.3.14. 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. The network stream capability is
- enabled by default, except for use in parallel or with a parallel
- compiler, where it is disabled. Explicitly enabling Stream-VFD
- will allow for its use in parallel.
-
-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.
-
- The HDF5 tests can take a long time to run on some systems. To
- perform a faster (but less thorough) test, set the HDF5TestExpress
- environment variable to 2 or 3 (with 3 being the shortest run).
- To perform a longer test, set HDF5TestExpress to 0. 1 is the default.
-
-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.
+ ./configure
+
+ HDF5 uses the zlib library for two purposes: it provides support
+ for the HDF5 deflate data compression filter, and it is used by
+ the h5toh4 converter and the h4toh5 converter in support of
+ HDF4. Configure searches the standard places (plus those specified
+ above with the CPPFLAGS and LDFLAGS variables) for the zlib
+ headers and library. The search can be disabled by specifying
+ `--without-zlib' or alternate directories can be specified with
+ `--with-zlib=INCDIR,LIBDIR' or through the CPPFLAGS and LDFLAGS
+ variables:
+
+ $ ./configure --with-zlib=/usr/unsup/include,/usr/unsup/lib
+
+ $ CPPFLAGS=-I/usr/unsup/include \
+ LDFLAGS=-L/usr/unsup/lib \
+ ./configure
+
+ The HDF5-to-HDF4 and HDF4-to-HDF5 conversion tool requires the
+ HDF4 library and header files, which are detected the same way as
+ zlib. The switch to give to configure is `--with-hdf4'. Note
+ that HDF5 requires a newer version of zlib than the one shipped
+ with some versions of HDF4. Also, unless you have the "correct"
+ version of HDF4, the confidence testing will fail in the tools
+ directory.
+
+ HDF5 includes Szip as a predefined compression method (see 3.2).
+ To enable Szip compression, the HDF5 Library must be configured
+ and built using the Szip Library:
+
+ $ ./configure --with-szlib=/Szip_Install_Directory
+
+4.3.8. Static versus shared linking
+ The build process will create static libraries on all systems and
+ shared libraries on systems that support dynamic linking to a
+ sufficient degree. Either form of the library may be suppressed by
+ saying `--disable-static' or `--disable-shared'.
+
+ $ ./configure --disable-shared
+
+ Shared C++ and Fortran libraries will be built if shared libraries
+ are enabled.
+
+ To build only statically linked executables on platforms which
+ support shared libraries, use the `--enable-static-exec' flag.
+
+ $ ./configure --enable-static-exec
+
+4.3.9. Optimization versus symbolic debugging
+ The library can be compiled to provide symbolic debugging support
+ so it can be debugged with gdb, dbx, ddd, etc., or it can be
+ compiled with various optimizations. To compile for symbolic
+ debugging (the default for snapshots), say `--disable-production';
+ to compile with optimizations (the default for supported public
+ releases), say `--enable-production'. On some systems the library
+ can also be compiled for profiling with gprof by saying
+ `--enable-production=profile'.
+
+ $ ./configure --disable-production #symbolic debugging
+ $ ./configure --enable-production #optimized code
+ $ ./configure --enable-production=profile #for use with gprof
+
+ Regardless of whether support for symbolic debugging is enabled,
+ the library can also perform runtime debugging of certain packages
+ (such as type conversion execution times and extensive invariant
+ condition checking). To enable this debugging, supply a
+ comma-separated list of package names to to the `--enable-debug'
+ switch. See "Debugging HDF5 Applications" for a list of package
+ names:
+
+ http://www.hdfgroup.org/HDF5/doc/H5.user/Debugging.html
+
+ Debugging can be disabled by saying `--disable-debug'.
+ The default debugging level for snapshots is a subset of the
+ available packages; the default for supported releases is no
+ debugging (debugging can incur a significant runtime penalty).
+
+ $ ./configure --enable-debug=s,t #debug only H5S and H5T
+ $ ./configure --enable-debug #debug normal packages
+ $ ./configure --enable-debug=all #debug all packages
+ $ ./configure --disable-debug #no debugging
+
+ HDF5 can also print a trace of all API function calls, their
+ arguments, and the return values. To enable or disable the
+ ability to trace the API say `--enable-trace' (the default for
+ snapthots) or `--disable-trace' (the default for public releases).
+ The tracing must also be enabled at runtime to see any output
+ (see "Debugging HDF5 Applications," reference above).
+
+4.3.10. Parallel versus serial library
+ The HDF5 Library can be configured to use MPI and MPI-IO for
+ parallelism on a distributed multi-processor system. Read the
+ file INSTALL_parallel for detailed explanations.
+
+4.3.11. Threadsafe capability
+ The HDF5 Library can be configured to be thread-safe (on a very
+ large scale) with the `--enable-threadsafe' flag to the configure
+ script. Some platforms may also require the '-with-pthread=INC,LIB'
+ (or '--with-pthread=DIR') flag to the configure script.
+ For further details, see "HDF5 Thread Safe Library":
+
+ http://www.hdfgroup.org/HDF5/doc/TechNotes/ThreadSafeLibrary.html
+
+4.3.12. Backward compatibility
+ The 1.8 version of the HDF5 Library can be configured to operate
+ identically to the v1.6 library with the
+ --with-default-api-version=v16
+ configure flag. This allows existing code to be compiled with the
+ v1.8 library without requiring immediate changes to the application
+ source code. For addtional configuration options and other details,
+ see "API Compatibility Macros in HDF5":
+
+ http://www.hdfgroup.org/HDF5/doc/RM/APICompatMacros.html
+
+4.4. Building
+ The library, confidence tests, and programs can be built by
+ saying just:
+
+ $ make
+
+ Note that if you have supplied some other make command via the MAKE
+ variable during the configuration step, 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
+ the `-j' since GNU make will turn it off for recursive invocations
+ of make.
+
+ $ make -j -l6
+
+4.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'.
+
+ The `check' consists of two sub-tests, check-s and check-p, which
+ are for serial and parallel tests, respectively. Since serial tests
+ and parallel tests must be run with single and multiple processes
+ respectively, the two sub-tests work nicely for batch systems in
+ which the number of processes is fixed per batch job. One may submit
+ one batch job, requesting 1 process, to run all the serial tests by
+ "make check-s"; and submit another batch job, requesting multiple
+ processes, to run all the parallel tests by "make check-p".
+
+ 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.
+
+ The HDF5 tests can take a long time to run on some systems. To perform
+ a faster (but less thorough) test, set the HDF5TestExpress environment
+ variable to 2 or 3 (with 3 being the shortest run). To perform a
+ longer test, set HDF5TestExpress to 0. 1 is the default.
+
+4.6. Installing HDF5
+ 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' (default is 'hdf5') in directories named `lib',
+ `include', and `bin'. The directories, if not existing, will be
+ created automatically, provided the mkdir command supports the -p
+ option.
+
+ 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 will need to run ./configure again.
$ INSTALL="$PWD/bin/install-sh -c" ./configure ...
$ make install
- If you want to install HDF5 in a location other than the location
- specified by the `--prefix=DIR' flag during configuration (or
- instead of the default location, `/usr/local'), you can do that
- by running the deploy script:
+ If you want to install HDF5 in a location other than the location
+ specified by the `--prefix=DIR' flag during configuration (or
+ instead of the default location, `hdf5'), you can do that
+ by running the deploy script:
$ bin/deploy NEW_DIR
- This will install hdf5 in NEW_DIR. Alternately, you can do this
- manually by issuing the command:
+ This will install HDF5 in NEW_DIR. Alternately, you can do this
+ manually by issuing the command:
- $ make install prefix=NEW_DIR
+ $ make install prefix=NEW_DIR
- where NEW_DIR is the new directory you wish to install HDF5. If
- you do not use the deploy script, you should run h5redeploy in
- NEW_DIR/bin directory. This utility will fix h5cc, h5fc and
- h5c++ scripts to reflect the new NEW_DIR location.
+ where NEW_DIR is the new directory where you wish to install HDF5.
+ If you do not use the deploy script, you should run h5redeploy in
+ NEW_DIR/bin directory. This utility will fix the h5cc, h5fc and
+ h5c++ scripts to reflect the new NEW_DIR location.
- The library can be used without installing it by pointing the
- compiler at the `src' and 'src/.libs' directory for include files and
- libraries. However, the minimum which must be installed to make
- the library publically available is:
+ The library can be used without installing it by pointing the
+ compiler at the `src' and 'src/.libs' directory for include files and
+ libraries. However, the minimum which must be installed to make
+ the library publicly available is:
- The library:
- ./src/.libs/libhdf5.a
+ The library:
+ ./src/.libs/libhdf5.a
- The public header files:
- ./src/H5*public.h, ./src/H5public.h
+ The public header files:
+ ./src/H5*public.h, ./src/H5public.h
./src/H5FD*.h except ./src/H5FDprivate.h,
./src/H5api_adpt.h
- The main header file:
- ./src/hdf5.h
+ The main header file:
+ ./src/hdf5.h
+
+ The configuration information:
+ ./src/H5pubconf.h
+
+ The support programs that are useful are:
+ ./tools/h5ls/h5ls (list file contents)
+ ./tools/h5dump/h5dump (dump file contents)
+ ./tools/misc/h5repart (repartition file families)
+ ./tools/misc/h5debug (low-level file debugging)
+ ./tools/h5import/h5import (imports data to HDF5 file)
+ ./tools/h5diff/h5diff (compares two HDF5 files)
+ ./tools/gifconv/h52gif (HDF5 to GIF converter)
+ ./tools/gifconv/gif2h5 (GIF to HDF5 converter)
- The configuration information:
- ./src/H5pubconf.h
-
- The support programs that are useful are:
- ./tools/h5ls/h5ls (list file contents)
- ./tools/h5dump/h5dump (dump file contents)
- ./tools/misc/h5repart (repartition file families)
- ./tools/misc/h5debug (low-level file debugging)
- ./tools/h5import/h5import (imports data to HDF5 file)
- ./tools/h5diff/h5diff (compares two HDF5 files)
- ./tools/gifconv/h52gif (HDF5 to GIF converter)
- ./tools/gifconv/gif2h5 (GIF to HDF5 converter)
-5.7 Building and testing with Intel compilers
+5. Using the Library
+ Please see the "HDF5 User's Guide" and the "HDF5 Reference Manual":
+ http://www.hdfgroup.org/HDF5/doc/
- When Intel compilers are used (icc or ecc), you will need to
- modify the generated "libtool" program after configuration is finished.
- On or around line 104 of the libtool file, there are lines which
- look like:
+ Most programs will include <hdf5.h> and link with -lhdf5.
+ Additional libraries may also be necessary depending on whether
+ support for compression, etc., was compiled into the HDF5 Library.
- # How to pass a linker flag through the compiler.
- wl=""
+ 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.
- Change these lines to this:
- # How to pass a linker flag through the compiler.
- wl="-Wl,"
+6. Support
+ Support is described in the README file.
- UPDATE: This is now done automatically by the configure script. However,
- if you still experience a problem, you may want to check this line in
- the libtool file and make sure that it has the correct value.
- * To build the Fortran library using Intel compiler on Linux 2.4, one has to
- x Use -fpp -DDEC$=DEC_ -DMS$=MS_ compiler flags to disable
- DEC and MS compiler directives in source files in fortran/src, fortran/test
- and fortran/examples directories.
- e.g., setenv F9X 'ifc -fpp -DDEC$=DEC_ -DMS$=MS_'
- (do not use double quotes since $ is interpreted in them.)
+*****************************************************************************
+ APPENDIX
+*****************************************************************************
- x If Version 6.0 of Fortran compiler is used, build fails in
- the fortran/test directory and then in the
- fortran/examples directory; to proceed, edit the work.pcl files in
- those directories to contain two lines
+A. Warnings about compilers
+ Output from the following compilers should be extremely suspected
+ when used to compile the HDF5 Library, especially if optimizations are
+ enabled. In all cases, HDF5 attempts to work around the compiler bugs.
+
+A.1. GNU (Intel platforms)
+ Versions before 2.8.1 have serious problems allocating registers
+ when functions contain operations on `long long' datatypes.
+ Supplying the `--disable-hsizet' switch to configure (documented
+ in Appendix B, "Large (>2GB) versus small (<2GB) file capability,")
+ will prevent HDF5 from using `long long' datatypes in
+ situations that are known not to work, but it limits the HDF5
+ address space to 2GB.
+
+A.2. COMPAQ/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 *'.
+ The Fortran module (5.4.1a) fails in compiling some Fortran
+ programs. Use 5.5.0 or higher.
+
+A.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.
+
+A.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.
+
+ A link warning: defaultlib "LIBC" conflicts with use of other libs
+ appears for debug version of VC++ 6.0. This warning will not affect
+ building and testing HDF5 Libraries.
+
+
+B. Large (>2GB) versus 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 datatype. To disable use of the
+ `long long' type on these machines, say:
+
+ $ ./configure --disable-hsizet
+
+C. Building and testing with other compilers
+C.1. Building and testing with Intel compilers
+ When Intel compilers are used (icc or ecc), you will need to modify
+ the generated "libtool" program after configuration is finished.
+ On or around line 104 of the libtool file, there are lines which
+ look like:
+
+ # How to pass a linker flag through the compiler.
+ wl=""
+
+ Change these lines to this:
+
+ # How to pass a linker flag through the compiler.
+ wl="-Wl,"
+
+ UPDATE: This is now done automatically by the configure script.
+ However, if you still experience a problem, you may want to check this
+ line in the libtool file and make sure that it has the correct value.
+
+ * To build the Fortran library using Intel compiler on Linux 2.4,
+ one has to perform the following steps:
+ x Use the -fpp -DDEC$=DEC_ -DMS$=MS_ compiler flags to disable
+ DEC and MS compiler directives in source files in the fortran/src,
+ fortran/test, and fortran/examples directories.
+ E.g., setenv F9X 'ifc -fpp -DDEC$=DEC_ -DMS$=MS_'
+ Do not use double quotes since $ is interpreted in them.
+
+ x If Version 6.0 of Fortran compiler is used, the build fails in
+ the fortran/test directory and then in the fortran/examples
+ directory. To proceed, edit the work.pcl files in those
+ directories to contain two lines:
work.pc
../src/work.pc
- x Do the same in fortran/examples directory
- x Problem with work.pc files was resolved for newest version of the compiler (7.0)
-
- * To build the Fortran Library on IA32 follow step described above, except
- that DEC and MS compiler directives should be removed manually or
- use a patch from HDF FTP server ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current/
-
-
-5.8 Building and testing with PGI compilers
-
- When PGI C and C++ compilers are used (pgcc or pgCC), you will need to
- modify the generated "libtool" program after configuration is finished.
- On or around line 104 of the libtool file, there are lines which
- look like:
+ x Do the same in the fortran/examples directory.
- # How to pass a linker flag through the compiler.
- wl=""
+ x A problem with work.pc files was resolved for the newest version
+ of the compiler (7.0).
- Change these lines to this:
+ * To build the Fortran library on IA32, follow the steps described
+ above, except that the DEC and MS compiler directives should be
+ removed manually or use a patch from HDF FTP server:
- # How to pass a linker flag through the compiler.
- wl="-Wl,"
+ ftp://ftp.hdfgroup.org/HDF5/current/
- UPDATE: This is now done automatically by the configure script. However,
- if you still experience a problem, you may want to check this line in
- the libtool file and make sure that it has the correct value.
- To build HDF5 C++ Library with pgCC (version 4.0 and later), set
- environment variable CXX to "pgCC -tlocal"
- setenv CXX "pgCC -tlocal"
- before running the configure script.
+C.2. Building and testing with PGI compilers
+ When PGI C and C++ compilers are used (pgcc or pgCC), you will need to
+ modify the generated "libtool" program after configuration is finished.
+ On or around line 104 of the libtool file, there are lines which
+ look like this:
+ # How to pass a linker flag through the compiler.
+ wl=""
-6. Using the Library
- Please see the User Manual in the doc/html directory.
+ Change these lines to this:
- Most programs will include <hdf5.h> and link with -lhdf5.
- Additional libraries may also be necessary depending on whether
- support for compression, etc. was compiled into the hdf5 library.
+ # How to pass a linker flag through the compiler.
+ wl="-Wl,"
- 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.
+ UPDATE: This is now done automatically by the configure script. However,
+ if you still experience a problem, you may want to check this line in
+ the libtool file and make sure that it has the correct value.
+ To build the HDF5 C++ Library with pgCC (version 4.0 and later), set
+ the environment variable CXX to "pgCC -tlocal"
+ setenv CXX "pgCC -tlocal"
+ before running the configure script.
-7. Support
- Support is described in the README file.