summaryrefslogtreecommitdiffstats
path: root/release_docs
diff options
context:
space:
mode:
authorAllen Byrne <byrn@hdfgroup.org>2018-09-10 14:29:46 (GMT)
committerAllen Byrne <byrn@hdfgroup.org>2018-09-10 14:29:46 (GMT)
commitfbf837eac31d510ecc8eaa65ea489ae180cde15f (patch)
treebb58fe6e0417093a167ba8fb7c4412f81dcd37fd /release_docs
parentc834d9f99d45e5b9752e8525fe8761ea5592bf2c (diff)
parentc9771263ae300a65f6f9ae518da766a314002bed (diff)
downloadhdf5-fbf837eac31d510ecc8eaa65ea489ae180cde15f.zip
hdf5-fbf837eac31d510ecc8eaa65ea489ae180cde15f.tar.gz
hdf5-fbf837eac31d510ecc8eaa65ea489ae180cde15f.tar.bz2
Merge pull request #1233 in HDFFV/hdf5 from ~BYRN/hdf5_adb:develop to develop
* commit 'c9771263ae300a65f6f9ae518da766a314002bed': Minor text corrections HDFFV-10569 Add unsupported option notes to docs
Diffstat (limited to 'release_docs')
-rw-r--r--release_docs/INSTALL112
-rw-r--r--release_docs/INSTALL_CMake.txt18
-rw-r--r--release_docs/USING_CMake_Examples.txt2
3 files changed, 80 insertions, 52 deletions
diff --git a/release_docs/INSTALL b/release_docs/INSTALL
index baad559..5c54698 100644
--- a/release_docs/INSTALL
+++ b/release_docs/INSTALL
@@ -2,11 +2,11 @@
Instructions for the Installation of HDF5 Software
==================================================
-This file provides instructions for installing the HDF5 software.
+This file provides instructions for installing the HDF5 software.
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 Forum: https://forum.hdfgroup.org/
HDF Helpdesk: https://portal.hdfgroup.org/display/support/The+HDF+Help+Desk
CONTENTS
@@ -52,8 +52,8 @@ CONTENTS
1. Obtaining HDF5
The latest supported public release of HDF5 is available from
- https://www.hdfgroup.org/downloads/hdf5/. For Unix and UNIX-like
- platforms, it is available in tar format compressed with gzip.
+ 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.
@@ -77,14 +77,14 @@ CONTENTS
$ 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
+ 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
+ In this case, PATH_TO_SZIP would be replaced with the path to the
installed location of the SZIP library.
2.1. Windows
@@ -101,7 +101,7 @@ 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
@@ -122,17 +122,17 @@ CONTENTS
include the Szip library with the encoder enabled. These can be found
here:
- https://www.hdfgroup.org/downloads/hdf5/
+ 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."
Please notice that if HDF5 configure cannot find a valid Szip library,
- configure will not fail; in this case, the compression filter will
+ configure will not fail; in this case, the compression filter will
not be available to the applications.
- To check if Szip compression was successfully configured in,
+ To check if Szip compression was successfully configured in,
check the "I/O filters (external):" line in the configure output,
summary section, printed to the standard output.
@@ -188,7 +188,7 @@ CONTENTS
detects various features of the host system and creates the
Makefiles. On most systems it should be sufficient to say:
- $ ./configure
+ $ ./configure
Or
$ sh configure
@@ -218,15 +218,15 @@ CONTENTS
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,"
+ 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
+ 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
@@ -257,7 +257,7 @@ CONTENTS
$ ./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
for these compilers in order: f90, pgf90, f95. To use an
@@ -267,7 +267,7 @@ CONTENTS
4.3.5. Specifying other programs
- The build system has been tuned for use with GNU make but also
+ 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
@@ -286,8 +286,8 @@ CONTENTS
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
+ 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
@@ -310,11 +310,11 @@ CONTENTS
LDFLAGS=-L/home/robb/lib \
./configure
- HDF5 uses the zlib library to support the HDF5 deflate
- data compression filter. 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
+ HDF5 uses the zlib library to support the HDF5 deflate
+ data compression filter. 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:
@@ -324,8 +324,8 @@ CONTENTS
LDFLAGS=-L/usr/unsup/lib \
./configure
- HDF5 includes Szip as a predefined compression method (see 3.2).
- To enable Szip compression, the HDF5 library must be configured
+ 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
@@ -350,10 +350,10 @@ CONTENTS
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
- `--enable-build-mode=production'; to compile with optimizations
- (the default for supported public releases),
- say `--enable-build-mode=production'. On some systems the
+ 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'.
@@ -362,13 +362,13 @@ CONTENTS
$ ./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 the `--enable-internal-debug'
- switch.
+ 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 the `--enable-internal-debug'
+ switch.
- Debugging can be disabled by saying `--disable-internal-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).
@@ -378,10 +378,10 @@ CONTENTS
$ ./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
+ 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).
+ snapthots) or `--disable-trace' (the default for public releases).
The tracing must also be enabled at runtime to see any output.
4.3.9. Parallel versus serial library
@@ -389,25 +389,39 @@ CONTENTS
parallelism on a distributed multi-processor system. Read the
file INSTALL_parallel for detailed information.
+ The threadsafe, C++ and Java interfaces are not compatible
+ with the parallel option.
+ Unless --enable-unsupported has been specified on the configure line,
+ the following options must be disabled:
+ --enable-threadsafe, --enable-cxx, --enable-java
+
+
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 information, see:
+ For further information, see:
https://portal.hdfgroup.org/display/knowledge/Questions+about+thread-safety+and+concurrent+access
+ The high-level, C++, Fortran and Java interfaces are not compatible
+ with the thread-safety option because the lock is not hoisted
+ into the higher-level API calls.
+ Unless --enable-unsupported has been specified on the configure line,
+ the following options must be disabled:
+ --enable-hl, --enable-cxx, --enable-fortran, --enable-java
+
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
+ identically to the v1.8 library with the
--with-default-api-version=v18
- configure flag, or identically to the v1.6 library with the
+ 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.10 library without requiring immediate changes to the application
- source code. For additional configuration options and other details,
+ v1.10 library without requiring immediate changes to the application
+ source code. For additional configuration options and other details,
see "API Compatibility Macros":
https://portal.hdfgroup.org/display/HDF5/API+Compatibility+Macros
@@ -487,7 +501,7 @@ CONTENTS
$ make install prefix=NEW_DIR
- where NEW_DIR is the new directory where you wish to install HDF5.
+ 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.
@@ -510,7 +524,7 @@ CONTENTS
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)
@@ -518,12 +532,12 @@ CONTENTS
./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/h52gif (HDF5 to GIF converter)
./tools/gifconv/gif2h5 (GIF to HDF5 converter)
5. Using the Library
-
+
For information on using HDF5 see the documentation, tutorials and examples
found here:
diff --git a/release_docs/INSTALL_CMake.txt b/release_docs/INSTALL_CMake.txt
index ba77ac4..1d6797c 100644
--- a/release_docs/INSTALL_CMake.txt
+++ b/release_docs/INSTALL_CMake.txt
@@ -492,7 +492,7 @@ These five steps are described in detail below.
Release and build the solution.
3.2.1 The external libraries (zlib and szip) can be configured
- to allow building the libraries by downloading from an GIT repository.
+ to allow building the libraries by downloading from a GIT repository.
The option is 'HDF5_ALLOW_EXTERNAL_SUPPORT'; by adding the following
configuration option:
-DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING="GIT"
@@ -509,7 +509,7 @@ These five steps are described in detail below.
adding the following configuration option:
-DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING="TGZ"
- The options to control the SVN URL (config/cmake/cacheinit.cmake
+ The options to control the TGZ URL (config/cmake/cacheinit.cmake
file) are:
ZLIB_TGZ_NAME:STRING="zlib_src.ext"
SZIP_TGZ_NAME:STRING="szip_src.ext"
@@ -652,6 +652,20 @@ NOTE:
flag is not available on windows and some modern linux systems will
ignore the flag.
+ ---------------- Unsupported Library Options ---------------------
+ The threadsafe, C++ and Java interfaces are not compatible
+ with the HDF5_ENABLE_PARALLEL option.
+ Unless ALLOW_UNSUPPORTED has been specified,
+ the following options must be disabled:
+ HDF5_ENABLE_THREADSAFE, HDF5_BUILD_CPP_LIB, HDF5_BUILD_JAVA
+
+ The high-level, C++, Fortran and Java interfaces are not compatible
+ with the HDF5_ENABLE_THREADSAFE option because the lock is not hoisted
+ into the higher-level API calls.
+ Unless ALLOW_UNSUPPORTED has been specified,
+ the following options must be disabled:
+ HDF5_BUILD_HL_LIB, HDF5_BUILD_CPP_LIB, HDF5_BUILD_FORTRAN, HDF5_BUILD_JAVA
+
========================================================================
VII. User Defined Options for HDF5 Libraries with CMake
diff --git a/release_docs/USING_CMake_Examples.txt b/release_docs/USING_CMake_Examples.txt
index 6f744d9..d5fae39 100644
--- a/release_docs/USING_CMake_Examples.txt
+++ b/release_docs/USING_CMake_Examples.txt
@@ -46,7 +46,7 @@ Default installation process:
Copy HDF5_Examples.cmake to this directory.
The default source folder is defined as "HDF5Examples". It can be changed
with the CTEST_SOURCE_NAME script option.
- The default installation folder is defined as "@CMAKE_INSTALL_PREFIX@".
+ The default installation folder is defined for the platform.
It can be changed with the INSTALLDIR script option.
(Note: Windows has issues with spaces and paths -The path will need to
be set correctly.)