[svn-r14045] Maintenance before 1.6.6 release: cleaned up the file. More editing follows.

1 files changed, 88 insertions, 221 deletions

diff --git a/release_docs/INSTALL b/release_docs/INSTALL
index 3c50956..d2b9946 100644
--- a/release_docs/INSTALL
+++ b/release_docs/INSTALL
@@ -6,48 +6,41 @@
 	--------
 	1. Obtaining HDF5
 
-	2. Warnings about compilers
-	2.1. GNU (Intel platforms)
-	2.2. DEC
-	2.3. SGI (Irix64 6.2)
-
-	3. Quick installation
-	3.1. TFLOPS
-	3.2. Windows
-	3.3. Certain Virtual File Layer(VFL)
-
-	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. 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
-	5.7  Building and testing with Intel compilers
-	5.8  Building and testing with PGI compilers
-
-	6. Using the Library
-
-	7. Support
+	2. Quick installation
+	2.1. Windows
+
+	3. HDF5 dependencies
+	3.1. Zlib
+	3.2  Szip
+	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 vs. Build Directories
+	4.3. Configuring
+	4.3.1. Specifying the installation directories
+	4.3.2. Using an alternate C compiler
+	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 vs. serial library
+	4.3.10. Disabling High-Level C APIs 
+	4.3.11. Threadsafe capability
+	4.3.12. Backward compatibility with HDF5 1.4* releases
+	4.4. Building
+	4.5. Testing
+	4.6. Installing
+
+	5. Using the Library
+
+	6. Support
 
 *****************************************************************************
 
@@ -67,36 +60,7 @@
 	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.
-
-
-3. Quick installation
+2. 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. "#" in "hdf5-1.6.#" below stands
@@ -109,29 +73,20 @@
 	    $ make check
 	    $ make install
 
-3.1. TFLOPS
-	Users of the Intel TFLOPS machine, after reading this file,
-	should see the INSTALL_TFLOPS for more instructions.
-
-3.2. Windows
+2.1. Windows
 	Users of Microsoft Windows should see the INSTALL_Windows for
 	detailed instructions.
 
-3.3. Certain Virtual File Layer(VFL)
-	If users want to install with special Virtual File Layer(VFL),
-	please go to read INSTALL_VFL file.  SRB and Globus-GASS have
-	been documented. 
-
 
-4. HDF5 dependencies
-4.1. Zlib 
+3. HDF5 dependencies
+3.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 (optional)
+3.2. Szip (optional)
 	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
@@ -140,7 +95,7 @@
         file can be found at ftp://ftp.ncsa.uiuc.edu/HDF/szip/
         
         To configure HDF5 library with Szip compression filter, use 
-        --enable-szlib=/PATH_TO_SZIP flag. For more information see 5.3.6.
+        --enable-szlib=/PATH_TO_SZIP flag. For more information see 4.3.6.
 
         Starting with the release 1.6.3 Szip library binaries are distributed 
         with encoder enabled (license may be required to use this binary) 
@@ -150,36 +105,36 @@
         an HDF5 application can always read Szip compressed data if Szip filter
         is present.
 
-4.3. MPI and MPI-IO
+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 then only a serial version of HDF5 can be
 	built.
 
 
-5. Full installation instructions for source distributions
-5.1. Unpacking the distribution
+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-1.6.#' directory.
 
-5.1.1. Non-compressed tar archive (*.tar)
+4.1.1. Non-compressed tar archive (*.tar)
 
 	    $ tar xf hdf5-1.6.#.tar
 
-5.1.2. Compressed tar archive (*.tar.Z)
+4.1.2. Compressed tar archive (*.tar.Z)
 
 	    $ uncompress -c < hdf5-1.6.#.tar.Z | tar xf -
 
-5.1.3. Gzip'd tar archive (*.tar.gz)
+4.1.3. Gzip'd tar archive (*.tar.gz)
 
 	    $ gunzip < hdf5-1.6.#.tar.gz | tar xf -
 
-5.1.4. Bzip'd tar archive (*.tar.bz2)
+4.1.4. Bzip'd tar archive (*.tar.bz2)
 
 	    $ bunzip2 < hdf5-1.6.#.tar.bz2 | tar xf -
 
-5.2. Source vs. Build Directories
+4.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
@@ -203,7 +158,7 @@
 		version of make. The VPATH facility should not be used
 		with the new parallel make option.
 
-5.3. Configuring
+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:
@@ -223,11 +178,11 @@
 	`configure' output. The host config file influences the behavior
 	of configure by setting or augmenting shell variables.
 
-5.3.1. Specifying the installation directories
+4.3.1. Specifying the installation directories
 	Typing `make install' will install the HDF5 library, header
 	files, examples, and support programs in hdf5/lib,
 	hdf5/include, hdf5/examples and hdf5/bin under the directory where it
-        was built (hdf5-1.6.# or build directory mentioned in 5.2)
+        was built (hdf5-1.6.# or build directory mentioned in 4.2)
         To use a path other than hdf5 specify the path with 
         the `--prefix=PATH' switch:
 
@@ -237,7 +192,7 @@
 	home of the shared library must be specified with this switch
 	before the library and executables are built.
 
-5.3.2. Using an alternate C compiler
+4.3.2. Using an alternate C compiler
 	By default, configure will look for the C compiler specified
         in the host configuration file in the config directory or by trying
 	`gcc' and `cc'. However, if the environment variable "CC" is set
@@ -276,7 +231,7 @@
 	    $ CFLAGS=-q64 FFLAGS=-q64 AR='ar -X 64'\
 	    $ ./configure --enable-fortran --enable-parallel
 
-5.3.3. Additional compilation flags
+4.3.3. 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
@@ -284,7 +239,7 @@
 
 	    $ CFLAGS=-g ./configure --enable-production
 
-5.3.4. Compiling HDF5 wrapper libraries
+4.3.4. 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.
@@ -310,19 +265,8 @@
 	Note: Fortran interface supports parallel HDF5 while the 
               C++ interface does not.
           
-        Note:  On Cray T3E machines the following files need to 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.5. Specifying other programs
+
+4.3.5. 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
@@ -356,7 +300,7 @@
 	       because the HDF5 makefiles also use the install program to
 	       also change file ownership and/or access permissions.
 
-5.3.6. 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
@@ -366,10 +310,9 @@
               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
+	HDF5 uses the zlib library to  provide support
+	for the HDF5 deflate data compression filter.
+	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
@@ -382,13 +325,13 @@
 	      LDFLAGS=-L/PATH_TO_ZLIB/lib \
 	      ./configure
 
-	HDF5 has Szip predefined compression method (see 4.2).  To enable
+	HDF5 has Szip predefined compression method (see 3.2).  To enable
 	Szip compression, HDF5 library has to be configured and build using 
 	Szip Library
 
         $ ./configure --with-szlib=/PATH_TO_SZIP
 
-5.3.7. 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 library may be suppressed by
@@ -396,15 +339,12 @@
 
 	    $ ./configure --disable-shared
 
-	The C++ and Fortran libraries are currently only available in the
-	static format.
-
 	To build only statically linked executables on platforms which
 	support shared libraries, use the `--enable-static-exec' flag.
 
 	    $ ./configure --enable-static-exec
 
-5.3.8. 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
@@ -442,22 +382,18 @@
 	releases). The tracing must also be enabled at runtime to see any
 	output (see Debugging.html).
 
-5.3.9. 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.10. Parallel vs. serial library
+4.3.9. 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
+4.3.10. Disabling high-level C APIs
+	By default the HDF5 library is configured to build high-level C APIs.
+        If this feature is not desired, use --disable-hl configuration flag to
+        bypass building and testing high-level C APIs.
+
+4.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
         the configure script.  Some platforms may also require the 
@@ -465,23 +401,21 @@
         script as well.  Read the file doc/html/TechNotes/ThreadSafeLibrary.html
          in the source directory for further details.
 
-5.3.12. Backward compatibility
+4.3.12. Backward compatibility with HDF5 1.4* releases
 	The 1.6 version of the HDF5 library can be configured to operate
 	identically to the v1.4 library with the `--enable-hdf5v1_4'
 	configure flag. This allows existing code to be compiled with the
 	v1.6 library without requiring immediate changes to the
 	application source code. This flag will only be supported in the
-	v1.6 branch of the library, it will not be available in v1.7+.
+	v1.6 branch of the library, it will not be available in v1.8+.
 
-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. This option is ON by default. Use
-        --disable-stream-vfd configuration flag to turn it OFF.
+4.3.12. Network stream capability
+	By default the HDF5 library is configured with a network stream file
+	driver. See the documentation on the Virtual File Layer for more details
+	about the use of this driver. Use --disable-stream-vfd configuration  
+        flag to turn it OFF.
 
-5.4. Building
+4.4. Building
 	The library, confidence tests, and programs can be build by
 	saying just:
 
@@ -498,7 +432,7 @@
 
 	    $ make -j -l6
 
-5.5. Testing
+4.5. Testing
 	HDF5 comes with various test suites, all of which can be run by
 	saying
 
@@ -514,7 +448,7 @@
 	fails. To prevent deletion of the files define the HDF5_NOCLEANUP
 	environment variable.
 
-5.6. Installing
+4.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
@@ -552,84 +486,17 @@
     	The support programs that are useful are:
 	    ./tools/h5ls/h5ls		(list file contents)
 	    ./tools/h5dump/h5dump	(dump file contents)
+	    ./tools/h5repack/h5repack	(repacks HDF5 file)
+	    ./tools/h5jam/h5jam(unjam)	( adds/removes user block to/from HDF5 file)
 	    ./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
-
-
-     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 
-          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.)
-
-          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
-
-                    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/
-      Also check "How to build HDF5 Fortran with Intel Compiler" under HDF5 FAQ
-      http://hdf.ncsa.uiuc.edu/hdf5-quest.html#plat-intel
-
-
-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:
-
-          # 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 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.
+            ./hl//tools/h52gif/h52gif	(HDF5 to GIF converter) 
+            ./hl//tools/gif2h5/gif2h5   (GIF to HDF5 converter)
 
 
-6. Using the Library
+5. Using the Library
 	Please see the User Manual in the doc/html directory.
 
 	Most programs will include <hdf5.h> and link with -lhdf5.
@@ -645,7 +512,7 @@
         scripts are installed under bin subdirectory when make install is run.
 
 
-6.1 Using the C++ API
+5.1 Using the C++ API
 	To use the C++ API, one must include the header file H5Cpp.h
 	in the application.  Please refer to the examples in c++/examples
 	for sample code.
@@ -662,5 +529,5 @@
 	the stylesheet that can be used to change the document layout.
 
 
-7. Support
+6. Support
 	Support is described in the README file.