diff options
Diffstat (limited to 'release_docs/INSTALL')
| -rw-r--r-- | release_docs/INSTALL | 373 |
1 files changed, 95 insertions, 278 deletions
diff --git a/release_docs/INSTALL b/release_docs/INSTALL index 2dcb9be..baad559 100644 --- a/release_docs/INSTALL +++ b/release_docs/INSTALL @@ -3,10 +3,11 @@ 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 +For help with installing, questions can be posted to the HDF Forum or sent to the HDF Helpdesk: + + HDF Forum: https://forum.hdfgroup.org/ + HDF Helpdesk: https://portal.hdfgroup.org/display/support/The+HDF+Help+Desk CONTENTS -------- @@ -31,59 +32,34 @@ CONTENTS 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.3.3. Additional compilation flags + 4.3.4. Compiling HDF5 wrapper libraries + 4.3.5. Specifying other programs + 4.3.6. Specifying other libraries and headers + 4.3.7. Static versus shared linking + 4.3.8. Optimization versus symbolic debugging + 4.3.9. Parallel versus serial library + 4.3.10. Threadsafe capability + 4.3.11. 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://ftp.hdfgroup.org/HDF5/current/src. For Unix and UNIX-like + https://www.hdfgroup.org/downloads/hdf5/. 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, + 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. @@ -125,28 +101,30 @@ CONTENTS 3. HDF5 dependencies 3.1. Zlib - The HDF5 Library includes a predefined compression filter that + 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 + 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/. + datasets. For information on Szip compression, license terms, + and obtaining the Szip source code, see: + + https://portal.hdfgroup.org/display/HDF5/Szip+Compression+in+HDF+Products - The Szip source code can be obtained from the HDF5 Download page - http://www.hdfgroup.org/HDF5/release/obtain5.html#extlibs. Building - instructions are available with the Szip source code. + Building instructions are available with the Szip source code. The HDF Group does not distribute separate Szip precompiled libraries, - but the HDF5 binaries available from - http://www.hdfgroup.org/HDF5/release/obtain5.html include - the Szip encoder enabled binary for the corresponding platform. + but the HDF5 pre-built binaries provided on The HDF Group download page + include the Szip library with the encoder enabled. These can be found + here: - To configure the HDF5 Library with the Szip compression filter, use + https://www.hdfgroup.org/downloads/hdf5/ + + To configure the HDF5 library with the Szip compression filter, use the '--with-szlib=/PATH_TO_SZIP' flag. For more information, see section 4.3.7, "Specifying other libraries and headers." @@ -204,20 +182,6 @@ CONTENTS $ 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 @@ -243,7 +207,7 @@ CONTENTS 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, + 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: @@ -275,45 +239,24 @@ CONTENTS $ 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 -m64' ./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 FCFLAGS=-q64 CXXFLAGS=-q64 AR='ar -X 64'\ - ./configure --enable-fortran - Parallel: (C++ not supported with parallel) - $ CFLAGS=-q64 FCFLAGS=-q64 AR='ar -X 64'\ - ./configure --enable-fortran -4.3.4. Additional compilation flags - If addtional flags must be passed to the compilation commands, +4.3.3. Additional compilation flags + If additional 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 + $ CFLAGS=-g ./configure --enable-build-mode=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. +4.3.4. Compiling HDF5 wrapper libraries + One can optionally build the Fortran, C++, and Java interfaces to + the HDF5 C library. By default, these options are disabled. To build + them, specify '--enable-fortran', '--enable-cxx', or '--enable-java', + respectively. $ ./configure --enable-fortran $ ./configure --enable-cxx + $ ./configure --enable-java Configuration will halt if a working Fortran 90 or 95 compiler or C++ compiler is not found. Currently, the Fortran configure tests @@ -322,15 +265,8 @@ CONTENTS $ 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 +4.3.5. 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 @@ -346,7 +282,7 @@ CONTENTS the `ar' and `ranlib' (or `:') commands to override values detected by configure. - The HDF5 Library, include files, and utilities are installed + 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 @@ -364,7 +300,7 @@ CONTENTS 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 +4.3.6. 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 @@ -389,12 +325,12 @@ CONTENTS ./configure 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: + 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 +4.3.7. 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 @@ -410,75 +346,75 @@ CONTENTS $ ./configure --enable-static-exec -4.3.9. Optimization versus symbolic debugging +4.3.8. 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 + debugging (the default for snapshots), say + `--enable-build-mode=production'; to compile with optimizations + (the default for supported public releases), + say `--enable-build-mode=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 + $ ./configure --enable-build-mode=debug #symbolic debugging + $ ./configure --enable-build-mode=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 + condition checking). To enable this debugging, supply a + comma-separated list of package names to the `--enable-internal-debug' + switch. - Debugging can be disabled by saying `--disable-debug'. + Debugging can be disabled by saying `--disable-internal-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 + $ ./configure --enable-internal-debug=s,t #debug only H5S and H5T + $ ./configure --enable-internal-debug #debug normal packages + $ ./configure --enable-internal-debug=all #debug all packages + $ ./configure --disable-internal-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). + The tracing must also be enabled at runtime to see any output. -4.3.10. Parallel versus serial library - The HDF5 Library can be configured to use MPI and MPI-IO for +4.3.9. 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. + file INSTALL_parallel for detailed information. -4.3.11. Threadsafe capability - The HDF5 Library can be configured to be thread-safe (on a very +4.3.10. 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": + For further information, see: + + https://portal.hdfgroup.org/display/knowledge/Questions+about+thread-safety+and+concurrent+access - 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 +4.3.11. Backward compatibility + The 1.10 version of the HDF5 library can be configured to operate + identically to the v1.8 library with the + --with-default-api-version=v18 + configure flag, or 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": + v1.10 library without requiring immediate changes to the application + source code. For additional configuration options and other details, + see "API Compatibility Macros": - http://www.hdfgroup.org/HDF5/doc/RM/APICompatMacros.html + https://portal.hdfgroup.org/display/HDF5/API+Compatibility+Macros 4.4. Building The library, confidence tests, and programs can be built by - saying just: + specifying: $ make @@ -495,7 +431,7 @@ CONTENTS 4.5. Testing HDF5 comes with various test suites, all of which can be run by - saying + specifying: $ make check @@ -524,13 +460,13 @@ CONTENTS 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. + The HDF5 library, include files, and support programs can be + installed by specifying `make install'. The files are installed under the + directory specified with `--prefix=DIR' (or if not specified, in 'hdf5' + in the top directory of the HDF5 source code). They will be + placed 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 @@ -587,134 +523,15 @@ CONTENTS 5. Using the Library - Please see the "HDF5 User's Guide" and the "HDF5 Reference Manual": - - http://www.hdfgroup.org/HDF5/doc/ - - 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. - - 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. - - -6. Support - Support is described in the README file. - - -***************************************************************************** - APPENDIX -***************************************************************************** - -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. - -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. - - -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 the fortran/examples directory. - - x A problem with work.pc files was resolved for the newest version - of the compiler (7.0). - - * 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: - - ftp://ftp.hdfgroup.org/HDF5/current/ - - -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="" + + For information on using HDF5 see the documentation, tutorials and examples + found here: - Change these lines to this: + https://portal.hdfgroup.org/display/HDF5/HDF5 - # How to pass a linker flag through the compiler. - wl="-Wl," + A summary of the features included in the built 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. |