philipp/hdf5
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #1233 in HDFFV/hdf5 from ~BYRN/hdf5_adb:develop to develop

Browse Source 
* commit 'c9771263ae300a65f6f9ae518da766a314002bed':
  Minor text corrections
  HDFFV-10569 Add unsupported option notes to docs
This commit is contained in:
Allen Byrne
2018-09-10 09:29:46 -05:00
parent c834d9f99d c9771263ae
commit fbf837eac3
4 changed files with 97 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
config/cmake/scripts/HDF5options.cmake
View File

@@ -66,6 +66,23 @@ set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING
#### package examples ####
#set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_PACK_EXAMPLES:BOOL=ON -DHDF5_EXAMPLES_COMPRESSED:STRING=HDF5Examples-1.10.9-Source.tar.gz -DHDF5_EXAMPLES_COMPRESSED_DIR:PATH=${CTEST_SCRIPT_DIRECTORY}")
#############################################################################################
### enable parallel builds
#set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_ENABLE_PARALLEL:BOOL=ON")
#set(ADD_BUILD_OPTIONS “${ADD_BUILD_OPTIONS} -DHDF5_BUILD_CPP_LIB:BOOL=OFF”)
#set(ADD_BUILD_OPTIONS “${ADD_BUILD_OPTIONS} -DHDF5_BUILD_JAVA:BOOL=OFF”)
#set(ADD_BUILD_OPTIONS “${ADD_BUILD_OPTIONS} -DHDF5_ENABLE_THREADSAFE:BOOL=OFF”)
#############################################################################################
### enable thread-safety builds
#set(ADD_BUILD_OPTIONS “${ADD_BUILD_OPTIONS} -DHDF5_ENABLE_THREADSAFE:BOOL=ON”)
#set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_ENABLE_PARALLEL:BOOL=OFF")
#set(ADD_BUILD_OPTIONS “${ADD_BUILD_OPTIONS} -DHDF5_BUILD_CPP_LIB:BOOL=OFF”)
#set(ADD_BUILD_OPTIONS “${ADD_BUILD_OPTIONS} -DHDF5_BUILD_FORTRAN:BOOL=OFF”)
#set(ADD_BUILD_OPTIONS “${ADD_BUILD_OPTIONS} -DHDF5_BUILD_HL_LIB:BOOL=OFF”)
#############################################################################################
### disable test program builds

112
release_docs/INSTALL
View File

@@ -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:

18
release_docs/INSTALL_CMake.txt
View File

@@ -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

2
release_docs/USING_CMake_Examples.txt
View File

@@ -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.)