From 1d2beee51f38ec4a3eda17ca564755f1711c2f44 Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Tue, 4 Sep 2018 11:43:07 -0500 Subject: HDFFV-10569 Add unsupported option notes to docs --- config/cmake/scripts/HDF5options.cmake | 17 +++++ release_docs/INSTALL | 112 ++++++++++++++++++--------------- release_docs/INSTALL_CMake.txt | 14 +++++ 3 files changed, 94 insertions(+), 49 deletions(-) diff --git a/config/cmake/scripts/HDF5options.cmake b/config/cmake/scripts/HDF5options.cmake index c5f08ed..3e6aad0 100755 --- a/config/cmake/scripts/HDF5options.cmake +++ b/config/cmake/scripts/HDF5options.cmake @@ -67,6 +67,23 @@ set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING #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 #set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DBUILD_TESTING:BOOL=OFF") 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 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..28afc16 100644 --- a/release_docs/INSTALL_CMake.txt +++ b/release_docs/INSTALL_CMake.txt @@ -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 -- cgit v0.12