mirror/hdf5
2
0
Fork 0
mirror of https://github.com/HDFGroup/hdf5.git synced 2024-11-21 01:04:10 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update and Add general INSTALL (#4016)

Browse Source
This commit is contained in:
Allen Byrne 2024-02-23 08:02:18 -06:00 committed by GitHub
parent 9a99fee914
commit 3fd1e90df6
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 184 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
HDF5Examples/config/cmake/HDFMacros.cmake
View File

@ -90,7 +90,7 @@ macro (HDFTEST_COPY_FILE src dest target)
endmacro ()
macro (HDF_DIR_PATHS package_prefix)
option (H5EX_USE_GNU_DIRS "ON to use GNU Coding Standard install directory variables, OFF to use historical settings" OFF)
option (H5EX_USE_GNU_DIRS "ON to use GNU Coding Standard install directory variables, OFF to use historical settings" OFF)
if (H5EX_USE_GNU_DIRS)
include(GNUInstallDirs)
if (NOT ${package_prefix}_INSTALL_BIN_DIR)
@ -121,7 +121,7 @@ macro (HDF_DIR_PATHS package_prefix)
endif ()
if (APPLE)
option (${package_prefix}_BUILD_FRAMEWORKS "ON to build as frameworks libraries, OFF to build according to BUILD_SHARED_LIBS" OFF)
option (${package_prefix}_BUILD_FRAMEWORKS "ON to build as frameworks libraries, OFF to build according to BUILD_SHARED_LIBS" OFF)
endif ()
if (NOT ${package_prefix}_INSTALL_BIN_DIR)

79
release_docs/INSTALL Normal file
View File

@ -0,0 +1,79 @@
*************************************************************************
* Installation Instructions for HDF5 *
*************************************************************************
Instructions for the Installation of 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 Helpdesk: https://hdfgroup.atlassian.net/servicedesk/customer/portals
CONTENTS
--------
1. Obtaining HDF5
2. Third-party Software Requirements
2.1. Zlib
2.2 Szip (optional)
2.3. MPI and MPI-IO
*****************************************************************************
1. Obtaining HDF5
The latest supported public releases of HDF5 are available on
https://github.com/HDFGroup/hdf5.
2. Third-party Software Requirements
2.1. Zlib
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
filter will succeed but the data will not be compressed.
2.2. Szip (optional)
The HDF5 library includes a predefined compression filter that
uses the extended-Rice lossless compression algorithm for chunked
datasets.
Building instructions are available with the Szip source code.
The HDF Group does not distribute separate Szip precompiled libraries,
but the HDF5 pre-built binaries provided on The HDF Group download page
include the Szip library with the encoder enabled. These can be found
here:
https://www.hdfgroup.org/downloads/hdf5/
Please notice that if HDF5 configure cannot find a valid Szip library,
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,
check the "I/O filters (external):" line in the configure output,
summary section, printed to the standard output.
2.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, only a serial version of HDF5 can be built.
3. HDF5 Source Code and Precompiled Binaries
The HDF Group provides source code and pre-compiled binaries from the
HDF5 github releases page:
https://github.com/HDFGroup/hdf5/releases
4. Build and Install HDF5 on Unix and Mac OSX Platforms with autotools
see the release_docs/INSTALL_Autotools.txt file.
5. Build and Install HDF5 Libraries and tools with CMake
see the release_docs/INSTALL_CMake.txt file.

199
release_docs/INSTALL_Auto.txt
View File

@ -1,60 +1,56 @@
*************************************************************************
* Installation Instructions for HDF5 using Autotools *
*************************************************************************
Instructions for the Installation of HDF5 Software
==================================================
Table of Contents
This file provides instructions for installing the HDF5 software.
Section I. Preconditions
Section II: Unix and Mac OSX Configuration and Build
Section III: Full installation instructions for source distributions
Section IV: Using the Library
Section V: Windows Configuration and Build
************************************************************************
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 Helpdesk: https://hdfgroup.atlassian.net/servicedesk/customer/portals
CONTENTS
--------
1. Obtaining HDF5
2. Quick installation
2.1. Windows
========================================================================
I. Preconditions
========================================================================
Obtaining HDF5 source code
1. Create a directory for your development; for example, "myhdfstuff".
3. HDF5 dependencies
3.1. Zlib
3.2 Szip (optional)
3.3. MPI and MPI-IO
2. Obtain HDF5 source from Github
development branch: https://github.com/HDFGroup/hdf5
last release: https://github.com/HDFGroup/hdf5/releases/latest
hdf5-1_14_"X".tar.gz or hdf5-1_14_"X".zip
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 versus 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 versus serial library
4.3.10. Threadsafe capability
4.3.11. Backward compatibility
4.4. Building
4.5. Testing
4.6. Installing HDF5
5. Using the Library
and put it in "myhdfstuff".
Uncompress the file. There should be a hdf5-1.14."X" folder.
*****************************************************************************
========================================================================
II. Unix and Mac OSX Configuration and Build
========================================================================
1. Obtaining HDF5
The latest supported public releases of HDF5 are available on
https://github.com/HDFGroup/hdf5.
See RELEASE.txt in the release_notes/ directory for the list of platforms
tested for this release.
Before You Start:
2. Quick installation
1. Make sure that the ZLIB library is installed on your system.
2. Optional: Install the Szip version 2.1 library (you may use
Szip 2.0 binaries).
3. Extract the source from the hdf5-X.Y.Z.tar file and change
directory to hdf5-X.Y.Z.
4. Quick installation
For those who 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. For example, to install HDF5 version X.Y.Z at
@ -67,8 +63,7 @@ CONTENTS
$ make install
$ make check-install # verify installation.
<configure_flags> above refers to the configure flags appropriate
<more 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
configure line might read as follows:
@ -79,84 +74,38 @@ CONTENTS
In this case, PATH_TO_SZIP would be replaced with the path to the
installed location of the SZIP library.
2.1. Windows
Users of Microsoft Windows should see the INSTALL_Windows files for
detailed instructions.
========================================================================
III. Full installation instructions for source distributions
========================================================================
3. HDF5 dependencies
3.1. Zlib
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
filter will succeed but the data will not be compressed.
3.2. Szip (optional)
The HDF5 library includes a predefined compression filter that
uses the extended-Rice lossless compression algorithm for chunked
datasets. For information on Szip compression, license terms,
and obtaining the Szip source code, see:
https://portal.hdfgroup.org/display/HDF5/Szip+Compression+in+HDF+Products
Building instructions are available with the Szip source code.
The HDF Group does not distribute separate Szip precompiled libraries,
but the HDF5 pre-built binaries provided on The HDF Group download page
include the Szip library with the encoder enabled. These can be found
here:
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
not be available to the applications.
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.
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, only a serial version of HDF5 can be built.
4. Full installation instructions for source distributions
4.1. Unpacking the distribution
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-X.Y.Z' directory, where X.Y.Z is the HDF5 version numbers.
4.1.1. Non-compressed tar archive (*.tar)
1.1. Non-compressed tar archive (*.tar)
$ tar xf hdf5-X.Y.Z.tar
4.1.2. Compressed tar archive (*.tar.Z)
1.2. Compressed tar archive (*.tar.Z)
$ uncompress -c < hdf5-X.Y.Z.tar.Z | tar xf -
Or
$ tar Zxf hdf5-X.Y.Z.tar.Z
4.1.3. Gzip'd tar archive (*.tar.gz)
1.3. Gzip'd tar archive (*.tar.gz)
$ gunzip < hdf5-X.Y.Z.tar.gz | tar xf -
Or
$ tar zxf hdf5-X.Y.Z.tar.gz
4.1.4. Bzip'd tar archive (*.tar.bz2)
1.4. Bzip'd tar archive (*.tar.bz2)
$ bunzip2 < hdf5-X.Y.Z.tar.bz2 | tar xf -
Or
$ tar jxf hdf5-X.Y.Z.tar.bz2
4.2. Source versus build directories
2. Source versus 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
@ -168,7 +117,7 @@ CONTENTS
$ ../hdf5-X.Y.Z/configure --enable-fortran ...
4.3. Configuring
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:
@ -189,7 +138,7 @@ CONTENTS
`configure' output. The host config file influences the behavior
of configure by setting or augmenting shell variables.
4.3.1. Specifying the installation directories
3.1. Specifying the installation directories
The default installation location is the HDF5 directory created in
the build directory. Typing `make install' will install the HDF5
library, header files, examples, and support programs in hdf5/lib,
@ -206,7 +155,7 @@ CONTENTS
specified at configure time; see section 4.6, "Installing HDF5,"
for more details.
4.3.2. Using an alternate C compiler
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
@ -225,7 +174,7 @@ CONTENTS
$ CC=/usr/local/mpi/bin/mpicc ./configure
4.3.3. Additional compilation flags
3.3. Additional compilation flags
If additional flags must be passed to the compilation commands,
specify those flags with the CFLAGS variable. For instance,
to enable symbolic debugging of a production version of HDF5, one
@ -233,7 +182,7 @@ CONTENTS
$ CFLAGS=-g ./configure --enable-build-mode=production
4.3.4. Compiling HDF5 wrapper libraries
3.4. Compiling HDF5 wrapper libraries
One can optionally build the Fortran, C++, and Java interfaces to
the HDF5 C library. By default, these options are disabled. To build
them, specify '--enable-fortran', '--enable-cxx', or '--enable-java',
@ -251,7 +200,7 @@ CONTENTS
$ FC=/usr/local/bin/g95 ./configure --enable-fortran
4.3.5. Specifying other programs
3.5. Specifying other programs
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
@ -285,7 +234,7 @@ CONTENTS
because the HDF5 makefiles also use the install program to
change file ownership and/or access permissions.
4.3.6. Specifying other libraries and headers
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
@ -315,7 +264,7 @@ CONTENTS
$ ./configure --with-szlib=/Szip_Install_Directory
4.3.7. Static versus shared linking
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 the library may be suppressed by
@ -331,7 +280,7 @@ CONTENTS
$ ./configure --enable-static-exec
4.3.8. Optimization versus symbolic debugging
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
@ -372,7 +321,7 @@ CONTENTS
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
3.9. Parallel versus serial library
The HDF5 library can be configured to use MPI and MPI-IO for
parallelism on a distributed multi-processor system. Read the
file INSTALL_parallel for detailed information.
@ -384,7 +333,7 @@ CONTENTS
--enable-threadsafe, --enable-cxx, --enable-java
4.3.10. Threadsafe capability
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'
@ -401,7 +350,7 @@ CONTENTS
--enable-hl, --enable-cxx, --enable-fortran, --enable-java
4.3.11. Backward compatibility
3.11. Backward compatibility
The 1.15 version of the HDF5 library can be configured to operate
identically to the v1.14 library with the
--with-default-api-version=v114
@ -420,7 +369,7 @@ CONTENTS
https://portal.hdfgroup.org/display/HDF5/API+Compatibility+Macros
4.4. Building
4. Building
The library, confidence tests, and programs can be built by
specifying:
@ -437,7 +386,7 @@ CONTENTS
$ make -j -l6
4.4. Building doxygen
4. Building doxygen
One can optionally build the doxygen files for the HDF5 C library.
By default, this option is disabled. To build the html files, specify
'--enable-doxygen'.
@ -450,7 +399,7 @@ CONTENTS
$ make doxygen
4.5. Testing
5. Testing
HDF5 comes with various test suites, all of which can be run by
specifying:
@ -480,7 +429,7 @@ CONTENTS
variable to 2 or 3 (with 3 being the shortest run). To perform a
longer test, set HDF5TestExpress to 0. 3 is the default.
4.6. Installing HDF5
6. Installing HDF5
The HDF5 library, include files, and support programs can be
installed by specifying `make install'. The files are installed under the
directory specified with `--prefix=DIR' (or if not specified, in 'hdf5'
@ -543,8 +492,9 @@ CONTENTS
./tools/gifconv/gif2h5 (GIF to HDF5 converter)
5. Using the Library
========================================================================
IV. Using the Library
========================================================================
For information on using HDF5 see the documentation, tutorials and examples
found here:
@ -555,4 +505,21 @@ CONTENTS
shared HDF5 libraries.
========================================================================
V. Windows Configuration and Build
========================================================================
See RELEASE.txt in the release_notes/ directory for the list of platforms
tested for this release.
We now recommend that users build, test, and install HDF5 using CMake.
Instructions for building and testing HDF5 using CMake can be found in the
INSTALL_CMake.txt file found in this folder.
For instructions on building and testing an application with HDF5, see the
USING_HDF5_CMake.txt file found in this folder.
Users who want to build and run an application with HDF5 in Visual Studio
without using CMake should consult the USING_HDF5_VS.txt file.

32
release_docs/INSTALL_CMake.txt
View File

@ -213,7 +213,7 @@ Notes: This short set of instructions is written for users who want to
cmake -G "Visual Studio 16 2019" -A Win32 -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ..\hdf5-1.15."X"
On Windows 64 bit
cmake -G "Visual Studio 16 2019 Win64" -A x64 -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ..\hdf5-1.15."X"
cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ..\hdf5-1.15."X"
On Linux and Mac
cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ../hdf5-1.15."X"
@ -657,7 +657,7 @@ These five steps are described in detail below.
2.2 Preferred command line example on Windows in c:\MyHDFstuff\hdf5\build directory:
cmake -C ../config/cmake/cacheinit.cmake -G "Visual Studio 16 2019" "-Ax64"\
cmake -C ../config/cmake/cacheinit.cmake -G "Visual Studio 16 2019" "-Ax64" \
-DHDF5_ENABLE_SZIP_SUPPORT:BOOL=OFF -DHDF5_ENABLE_Z_LIB_SUPPORT:BOOL=OFF \
-DCMAKE_BUILD_TYPE:STRING=Release ..
@ -692,11 +692,11 @@ These five steps are described in detail below.
-DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING="GIT"
The options to control the GIT parameters (config/cmake/cacheinit.cmake file) are:
ZLIB_GIT_URL:STRING="http://${git_url}/zlib"
ZLIB_GIT_URL:STRING="https://${git_url}/zlib"
ZLIB_GIT_BRANCH="${git_branch}"
SZIP_GIT_URL:STRING="http://${git_url}/szip"
SZIP_GIT_URL:STRING="https://${git_url}/szip"
SZIP_GIT_BRANCH="${git_branch}"
PLUGIN_GIT_URL:STRING="http://${git_url}/plugin"
PLUGIN_GIT_URL:STRING="https://${git_url}/plugin"
PLUGIN_GIT_BRANCH="${git_branch}"
${git_url} should be changed to your location and ${git_branch} is
your branch in the repository. Also define CMAKE_BUILD_TYPE
@ -909,23 +909,23 @@ HDF5_ENABLE_PLUGIN_SUPPORT "Enable PLUGIN Filters"
HDF5_ENABLE_SZIP_SUPPORT "Use SZip Filter" OFF
HDF5_ENABLE_Z_LIB_SUPPORT "Enable Zlib Filters" ON
ZLIB_USE_EXTERNAL "Use External Library Building for ZLIB" OFF
ZLIB_TGZ_ORIGPATH "Use ZLIB from original location" "https://github.com/madler/zlib/releases/download/v1.2.13"
ZLIB_TGZ_NAME "Use ZLIB from original compressed file" "zlib-1.2.13.tar.gz"
ZLIB_USE_LOCALCONTENT "Use local file for ZLIB FetchContent" ON
ZLIB_USE_EXTERNAL "Use External Library Building for ZLIB" OFF
ZLIB_TGZ_ORIGPATH "Use ZLIB from original location" "https://github.com/madler/zlib/releases/download/v1.2.13"
ZLIB_TGZ_NAME "Use ZLIB from original compressed file" "zlib-1.2.13.tar.gz"
ZLIB_USE_LOCALCONTENT "Use local file for ZLIB FetchContent" ON
SZIP_USE_EXTERNAL "Use External Library Building for SZIP" OFF
SZIP_USE_EXTERNAL "Use External Library Building for SZIP" OFF
if (HDF5_ENABLE_SZIP_SUPPORT)
HDF5_ENABLE_SZIP_ENCODING "Use SZip Encoding" ON
LIBAEC_TGZ_ORIGPATH "Use LIBAEC from original location" "https://github.com/MathisRosenhauer/libaec/releases/download/v1.0.6/libaec-1.0.6.tar.gz"
LIBAEC_TGZ_NAME "Use LIBAEC from original compressed file" "libaec-v1.0.6.tar.gz"
LIBAEC_USE_LOCALCONTENT "Use local file for LIBAEC FetchContent" ON
LIBAEC_TGZ_ORIGPATH "Use LIBAEC from original location" "https://github.com/MathisRosenhauer/libaec/releases/download/v1.0.6/libaec-1.0.6.tar.gz"
LIBAEC_TGZ_NAME "Use LIBAEC from original compressed file" "libaec-v1.0.6.tar.gz"
LIBAEC_USE_LOCALCONTENT "Use local file for LIBAEC FetchContent" ON
PLUGIN_USE_EXTERNAL "Use External Library Building for PLUGINS" OFF
PLUGIN_USE_EXTERNAL "Use External Library Building for PLUGINS" OFF
if (WINDOWS)
H5_DEFAULT_PLUGINDIR "%ALLUSERSPROFILE%/hdf5/lib/plugin"
H5_DEFAULT_PLUGINDIR "%ALLUSERSPROFILE%/hdf5/lib/plugin"
else ()
H5_DEFAULT_PLUGINDIR "/usr/local/hdf5/lib/plugin"
H5_DEFAULT_PLUGINDIR "/usr/local/hdf5/lib/plugin"
endif ()
NOTE:

2
release_docs/USING_CMake_Examples.txt
View File

@ -67,7 +67,7 @@ Default installation process:
ctest -S HDF5_Examples.cmake,CTEST_SOURCE_NAME=MyExamples,INSTALLDIR=MyLocation -C Release -V -O test.log
When executed, the ctest script will save the results to the log file, test.log, as
indicated by the ctest command. If you wish the to see more build and test information,
indicated by the ctest command. If you wish to see more build and test information,
add "-VV" to the ctest command. The output should show;
100% tests passed, 0 tests failed out of 156.

4
release_docs/USING_HDF5_VS.txt
View File

@ -44,7 +44,9 @@ Using Visual Studio 2010 and above with HDF5 Libraries built with Visual Studio
hdf5.lib hdf5_cpp.lib
For static linking:
libszaec.lib libaec.lib libzlib.lib libhdf5.lib libhdf5_cpp.lib
HDF5 libraries: libhdf5.lib libhdf5_cpp.lib
Compression libraries: libszaec.lib libaec.lib libzlib.lib
System libraries: shlwapi.lib
==========================================================================