From 62ff7f238de1830a61881b7fb469282c978631c7 Mon Sep 17 00:00:00 2001 From: Albert Cheng Date: Tue, 12 Feb 2008 10:05:31 -0500 Subject: [svn-r14552] Purpose: 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.) Tested: Just eyeballed. --- release_docs/INSTALL | 94 ++++++++++++++++++++++++---------------------------- 1 file changed, 44 insertions(+), 50 deletions(-) diff --git a/release_docs/INSTALL b/release_docs/INSTALL index cfdbeb0..cda4239 100644 --- a/release_docs/INSTALL +++ b/release_docs/INSTALL @@ -36,7 +36,6 @@ 4.3.11. Parallel vs. serial library 4.3.12. Threadsafe capability 4.3.13. Backward compatibility - 4.3.14. Network stream capability 4.4. Building 4.5. Testing 4.6. Installing @@ -182,7 +181,10 @@ 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). + 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' doesn't understand the VPATH @@ -221,13 +223,13 @@ of configure by setting or augmenting shell variables. 4.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: + The default installation location is the hdf5 directory created in + the built 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=$HOME + $ ./configure --prefix=/usr/local If shared libraries are being built (the default) then the final home of the shared library must be specified with this switch @@ -274,10 +276,10 @@ (Note: need to set $AR to 'ar -X 64'.) Serial: $ CFLAGS=-q64 FFLAGS=-q64 CXXFLAGS=-q64 AR='ar -X 64'\ - $ ./configure --enable-fortran + ./configure --enable-fortran Parallel: (C++ not supported with parallel) $ CFLAGS=-q64 FFLAGS=-q64 AR='ar -X 64'\ - $ ./configure --enable-fortran + ./configure --enable-fortran 4.3.4. Additional compilation flags If addtional flags must be passed to the compilation commands @@ -298,24 +300,15 @@ 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: + alternative compiler specify it with the FC variable: - $ F9X=/usr/local/bin/g95 ./configure --enable-fortran + $ 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: 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 4.7 and 4.8 for how to build Fortran Library with Intel or PGI compilers. @@ -387,7 +380,7 @@ version of hdf4 the confidence testing will fail in the tools directory. - 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 @@ -463,11 +456,10 @@ 4.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. + 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 as well. + Read the file doc/TechNotes/ThreadSafeLibrary.html for further details. 4.3.13. Backward compatibility The 1.8 version of the HDF5 library can be configured to operate @@ -477,29 +469,19 @@ 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+. -4.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. - 4.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. + 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 - th `-j' since GNU make will turn it off for recursive invocations + the `-j' since GNU make will turn it off for recursive invocations of make. $ make -j -l6 @@ -515,23 +497,33 @@ 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 complets, but may continue to exist in an incomplete state if the test - fails. To prevent deletion of the files define the HDF5_NOCLEANUP + 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. + 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 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. + `--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 @@ -542,7 +534,7 @@ 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 + instead of the default location, `hdf5'), you can do that by running the deploy script: $ bin/deploy NEW_DIR @@ -670,6 +662,8 @@ 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 -- cgit v0.12