mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-12-03 02:32:04 +08:00
767 lines
37 KiB
Plaintext
767 lines
37 KiB
Plaintext
************************************************************************
|
|
* Build and Install HDF5 C, C++, Fortran and High-Level Libraries *
|
|
* and tools with CMake *
|
|
************************************************************************
|
|
|
|
Table of Contents
|
|
|
|
Section I: Preconditions
|
|
Section II: Quick Step Building HDF5 Libraries with CMake Script Mode
|
|
Section III: Quick Step Building HDF5 Libraries with CMake Command Mode
|
|
Section IV: Further considerations
|
|
Section V: Options for building HDF5 Libraries with CMake command line
|
|
Section VI: CMake option defaults for HDF5
|
|
Section VII: User Defined Options for HDF5 Libraries with CMake
|
|
Section VIII: User Defined Compile Flags for HDF5 Libraries with CMake
|
|
|
|
************************************************************************
|
|
|
|
|
|
========================================================================
|
|
I. Preconditions
|
|
========================================================================
|
|
Obtaining HDF5 source code
|
|
1. Create a directory for your development; for example, "myhdfstuff".
|
|
|
|
2. Obtain compressed (*.tar or *.zip) HDF5 source from
|
|
https://portal.hdfgroup.org/display/support/Building+HDF5+with+CMake
|
|
and put it in "myhdfstuff".
|
|
Uncompress the file. There should be a hdf5-1.13."X" folder.
|
|
|
|
CMake version
|
|
1. We suggest you obtain the latest CMake from the Kitware web site.
|
|
The HDF5 1.13."X" product requires a minimum CMake version 3.12,
|
|
where "X" is the current HDF5 release version. If you are using
|
|
VS2019, the minimum version is 3.15.
|
|
|
|
Note:
|
|
To change the install prefix from the platform defaults initialize
|
|
the CMake variable, CMAKE_INSTALL_PREFIX. Users of build scripts
|
|
will use the INSTALLDIR option.
|
|
|
|
|
|
========================================================================
|
|
II. Quick Step Building HDF5 Libraries with CMake Script Mode
|
|
========================================================================
|
|
This short set of instructions is written for users who want to quickly
|
|
build the HDF5 C and C++ static libraries and tools with SZIP and ZLIB
|
|
compression included. This procedure will use the default settings in
|
|
the config/cmake/cacheinit.cmake file.
|
|
HDF Group recommends using the ctest script mode to build HDF5.
|
|
|
|
The following files referenced below are available at the HDF web site:
|
|
https://portal.hdfgroup.org/display/support/Building+HDF5+with+CMake
|
|
|
|
Single compressed file with all the files needed, including source:
|
|
CMake-hdf5-1.13.X.zip or CMake-hdf5-1.13.X.tar.gz
|
|
|
|
Individual files included in the above mentioned compressed files
|
|
-----------------------------------------------
|
|
CMake build script:
|
|
CTestScript.cmake
|
|
|
|
External compression szip and zlib libraries:
|
|
LIBAEC.tar.gz
|
|
SZip.tar.gz
|
|
ZLib.tar.gz
|
|
|
|
Examples Source package:
|
|
HDF5Examples-1.14.x-Source.tar.gz
|
|
|
|
Configuration files:
|
|
HDF5config.cmake
|
|
HDF5options.cmake
|
|
|
|
Build scripts for windows or linux
|
|
-----------------------------------------------
|
|
|
|
To build HDF5 with the SZIP and ZLIB external libraries you will need to:
|
|
|
|
1. Change to the development directory "myhdfstuff".
|
|
|
|
2. Download the CMake-hdf5-1.13.X.zip(.tar.gz) file to "myhdfstuff".
|
|
Uncompress the file.
|
|
|
|
3. Change to the source directory "hdf5-1.13.x".
|
|
CTestScript.cmake file should not be modified.
|
|
|
|
4. Edit the platform configuration file, HDF5options.cmake, if you want to change
|
|
the default build environment.
|
|
(See https://portal.hdfgroup.org/display/support/How+to+Change+HDF5+CMake+Build+Options)
|
|
|
|
5. From the "myhdfstuff" directory execute the CTest Script with the
|
|
following options:
|
|
|
|
On 32-bit Windows with Visual Studio 2019, execute:
|
|
ctest -S HDF5config.cmake,BUILD_GENERATOR=VS2019 -C Release -VV -O hdf5.log
|
|
On 64-bit Windows with Visual Studio 2019, execute:
|
|
ctest -S HDF5config.cmake,BUILD_GENERATOR=VS201964 -C Release -VV -O hdf5.log
|
|
On 32-bit Windows with Visual Studio 2017, execute:
|
|
ctest -S HDF5config.cmake,BUILD_GENERATOR=VS2017 -C Release -VV -O hdf5.log
|
|
On 64-bit Windows with Visual Studio 2017, execute:
|
|
ctest -S HDF5config.cmake,BUILD_GENERATOR=VS201764 -C Release -VV -O hdf5.log
|
|
On 32-bit Windows with Visual Studio 2015, execute:
|
|
ctest -S HDF5config.cmake,BUILD_GENERATOR=VS2015 -C Release -VV -O hdf5.log
|
|
On 64-bit Windows with Visual Studio 2015, execute:
|
|
ctest -S HDF5config.cmake,BUILD_GENERATOR=VS201564 -C Release -VV -O hdf5.log
|
|
On Linux and Mac, execute:
|
|
ctest -S HDF5config.cmake,BUILD_GENERATOR=Unix -C Release -VV -O hdf5.log
|
|
The supplied build scripts are versions of the above.
|
|
|
|
The command above will configure, build, test, and create an install
|
|
package in the myhdfstuff folder. It will have the format:
|
|
HDF5-1.13.NN-<platform>.<zip or tar.gz>
|
|
|
|
On Unix, <platform> will be "Linux". A similar .sh file will also be created.
|
|
On Windows, <platform> will be "win64" or "win32". If you have an
|
|
installer on your system, you will also see a similar file that ends
|
|
in either .exe (NSIS) or .msi (WiX).
|
|
|
|
Notes on the command line options.
|
|
The -S option uses the script version of ctest.
|
|
|
|
The value for the -C option (as shown above, "-C Release") must
|
|
match the setting for CTEST_CONFIGURATION_TYPE in the platform
|
|
configuration file.
|
|
|
|
The -VV option is for most verbose; use -V for less verbose.
|
|
|
|
The "-O hdf5.log" option saves the output to a log file hdf5.log.
|
|
|
|
6. To install, "X" is the current release version
|
|
|
|
On Windows (with WiX installed), execute:
|
|
HDF5-1.13."X"-win32.msi or HDF5-1.13."X"-win64.msi
|
|
By default this program will install the hdf5 library into the
|
|
"C:\Program Files" directory and will create the following
|
|
directory structure:
|
|
HDF_Group
|
|
--HDF5
|
|
----1.13."X"
|
|
------bin
|
|
------include
|
|
------lib
|
|
------cmake
|
|
|
|
On Linux, change to the install destination directory
|
|
(create it if doesn't exist) and execute:
|
|
<path-to>/myhdfstuff/HDF5-1.13."X"-Linux.sh
|
|
After accepting the license, the script will prompt:
|
|
By default the HDF5 will be installed in:
|
|
"<current directory>/HDF5-1.13."X"-Linux"
|
|
Do you want to include the subdirectory HDF5-1.13."X"-Linux?
|
|
Saying no will install in: "<current directory>" [Yn]:
|
|
Note that the script will create the following directory structure
|
|
relative to the install point:
|
|
HDF_Group
|
|
--HDF5
|
|
----1.13."X"
|
|
------bin
|
|
------include
|
|
------lib
|
|
------share
|
|
|
|
On Mac you will find HDF5-1.13."X"-Darwin.dmg in the myhdfstuff folder. Click
|
|
on the dmg file to proceed with installation. After accepting the license,
|
|
there will be a folder with the following structure:
|
|
HDF_Group
|
|
--HDF5
|
|
----1.13."X"
|
|
------bin
|
|
------include
|
|
------lib
|
|
------share
|
|
|
|
By default the installation will create the bin, include, lib and cmake
|
|
folders in the <install destination directory>/HDF_Group/HDF5/1.13."X"
|
|
The <install destination directory> depends on the build platform;
|
|
Windows will set the default to:
|
|
C:/Program Files/HDF_Group/HDF5/1.13."X"
|
|
Linux will set the default to:
|
|
"myhdfstuff/HDF_Group/HDF5/1.13."X"
|
|
The default can be changed by adding ",INSTALLDIR=<my new dir>" to the
|
|
"ctest -S HDF5config.cmake..." command. For example on linux:
|
|
ctest -S HDF5config.cmake,INSTALLDIR=/usr/local/myhdf5,BUILD_GENERATOR=Unix -C Release -VV -O hdf5.log
|
|
|
|
|
|
========================================================================
|
|
III. Quick Step Building HDF5 C Static Libraries and Tools with CMake
|
|
========================================================================
|
|
Notes: This short set of instructions is written for users who want to
|
|
quickly build just the HDF5 C static library and tools from
|
|
the HDF5 source code package using the CMake command line tools.
|
|
Avoid the use of drive letters in paths on Windows.
|
|
|
|
Go through these steps:
|
|
|
|
1. Change to the development directory "myhdfstuff".
|
|
|
|
2. Uncompress the HDF5 source file
|
|
|
|
3. Create a folder "build" in the "myhdfstuff" directory.
|
|
|
|
4. Change into the "build" folder.
|
|
|
|
5. Configure the C library, tools and tests with one of the following commands:
|
|
|
|
On Windows 32 bit
|
|
cmake -G "Visual Studio 12 2013" -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ..\hdf5-1.13."X"
|
|
|
|
On Windows 64 bit
|
|
cmake -G "Visual Studio 12 2013 Win64" -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ..\hdf5-1.13."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.13."X"
|
|
|
|
where "X" is the current release version.
|
|
|
|
6. Build the C library, tools and tests with this command:
|
|
cmake --build . --config Release
|
|
|
|
7. Test the C library and tools with this command:
|
|
ctest . -C Release
|
|
|
|
8. Create an install image with this command:
|
|
cpack -C Release CPackConfig.cmake
|
|
|
|
9. To install
|
|
On Windows (with WiX installed), execute:
|
|
HDF5-1.13."X"-win32.msi or HDF5-1.13."X"-win64.msi
|
|
By default this program will install the hdf5 library into the
|
|
"C:\Program Files" directory and will create the following
|
|
directory structure:
|
|
HDF_Group
|
|
--HDF5
|
|
----1.13."X"
|
|
------bin
|
|
------include
|
|
------lib
|
|
------cmake
|
|
|
|
On Linux, change to the install destination directory
|
|
(create if doesn't exist) and execute:
|
|
<path-to>/myhdfstuff/build/HDF5-1.13."X"-Linux.sh
|
|
After accepting the license, the script will prompt:
|
|
By default the HDF5 will be installed in:
|
|
"<current directory>/HDF5-1.13."X"-Linux"
|
|
Do you want to include the subdirectory HDF5-1.13."X"-Linux?
|
|
Saying no will install in: "<current directory>" [Yn]:
|
|
Note that the script will create the following directory structure
|
|
relative to the install point:
|
|
HDF_Group
|
|
--HDF5
|
|
----1.13."X"
|
|
------bin
|
|
------include
|
|
------lib
|
|
------share
|
|
|
|
On Mac you will find HDF5-1.13."X"-Darwin.dmg in the build folder. Click
|
|
on the dmg file to proceed with installation. After accepting the license,
|
|
there will be a folder with the following structure:
|
|
HDF_Group
|
|
--HDF5
|
|
----1.13."X"
|
|
------bin
|
|
------include
|
|
------lib
|
|
------share
|
|
|
|
|
|
========================================================================
|
|
IV. Further considerations
|
|
========================================================================
|
|
|
|
1. We suggest you obtain the latest CMake for windows from the Kitware
|
|
web site. The HDF5 1.13."X" product requires a minimum CMake version 3.12.
|
|
|
|
2. If you plan to use Zlib or Szip:
|
|
A. Download the binary packages and install them in a central location.
|
|
For example on Windows, create a folder extlibs and install the
|
|
packages there. Add the following CMake options:
|
|
-DZLIB_LIBRARY:FILEPATH=some_location/lib/zlib.lib
|
|
-DZLIB_INCLUDE_DIR:PATH=some_location/include
|
|
-DZLIB_USE_EXTERNAL:BOOL=OFF
|
|
-DSZIP_LIBRARY:FILEPATH=some_location/lib/szlib.lib
|
|
-DSZIP_INCLUDE_DIR:PATH=some_location/include
|
|
-DSZIP_USE_EXTERNAL:BOOL=OFF
|
|
where "some_location" is the full path to the extlibs folder.
|
|
Also the appropriate environment variable must be set;
|
|
set(ENV{ZLIB_ROOT} "some_location")
|
|
set(ENV{SZIP_ROOT} "some_location")
|
|
|
|
B. Use source packages from an GIT server by adding the following CMake
|
|
options:
|
|
HDF5_ALLOW_EXTERNAL_SUPPORT:STRING="GIT"
|
|
ZLIB_GIT_URL:STRING="http://some_location/zlib"
|
|
SZIP_GIT_URL:STRING="http://some_location/szip"
|
|
where "some_location" is the URL to the GIT repository. Also set
|
|
CMAKE_BUILD_TYPE to the configuration type.
|
|
|
|
C. Use source packages from a compressed file by adding the following
|
|
CMake options:
|
|
HDF5_ALLOW_EXTERNAL_SUPPORT:STRING="TGZ"
|
|
ZLIB_TGZ_NAME:STRING="zlib_src.ext"
|
|
SZIP_TGZ_NAME:STRING="szip_src.ext"
|
|
TGZPATH:STRING="some_location"
|
|
where "some_location" is the URL or full path to the compressed
|
|
file and ext is the type of compression file. Also set CMAKE_BUILD_TYPE
|
|
to the configuration type during configuration
|
|
|
|
3. If you are building on Apple Darwin platforms, you should add the
|
|
following options:
|
|
Compiler choice - use xcode by setting the ENV variables of CC and CXX
|
|
Shared fortran is not supported, build static:
|
|
BUILD_SHARED_LIBS:BOOL=OFF
|
|
Additional options:
|
|
CMAKE_ANSI_CFLAGS:STRING=-fPIC
|
|
CTEST_USE_LAUNCHERS:BOOL=ON
|
|
CMAKE_BUILD_WITH_INSTALL_RPATH:BOOL=OFF
|
|
|
|
4. Windows developers should install NSIS or WiX to create an install image with CPack.
|
|
Visual Studio Express users will not be able to package HDF5 into
|
|
an install image executable.
|
|
|
|
5. Developers can copy the config/cmake/cacheinit.cmake file and alter the
|
|
the settings for the developers' environment. Then the only options needed
|
|
on the command line are those options that are different. Example using HDF
|
|
default cache file:
|
|
cmake -C ../config/cmake/cacheinit.cmake -G "Visual Studio 12 2013" \
|
|
-DHDF5_ENABLE_SZIP_SUPPORT:BOOL=OFF -DHDF5_ENABLE_Z_LIB_SUPPORT:BOOL=OFF \
|
|
-DCMAKE_BUILD_TYPE:STRING=Release ..
|
|
|
|
6. CMake uses a toolchain of utilities to compile, link libraries and
|
|
create archives, and other tasks to drive the build. The toolchain
|
|
utilities available are determined by the languages enabled. In normal
|
|
builds, CMake automatically determines the toolchain for host builds
|
|
based on system introspection and defaults. In cross-compiling
|
|
scenarios, a toolchain file may be specified with information about
|
|
compiler and utility paths.
|
|
Variables and Properties
|
|
Several variables relate to the language components of a toolchain which
|
|
are enabled. CMAKE_<LANG>_COMPILER is the full path to the compiler used
|
|
for <LANG>. CMAKE_<LANG>_COMPILER_ID is the identifier used by CMake for
|
|
the compiler and CMAKE_<LANG>_COMPILER_VERSION is the version of the compiler.
|
|
|
|
The CMAKE_<LANG>_FLAGS variables and the configuration-specific equivalents
|
|
contain flags that will be added to the compile command when compiling a
|
|
file of a particular language.
|
|
|
|
As the linker is invoked by the compiler driver, CMake needs a way to
|
|
determine which compiler to use to invoke the linker. This is calculated
|
|
by the LANGUAGE of source files in the target, and in the case of static
|
|
libraries, the language of the dependent libraries. The choice CMake makes
|
|
may be overridden with the LINKER_LANGUAGE target property.
|
|
|
|
See the CMake help for more information on using toolchain files.
|
|
|
|
To use a toolchain file with the supplied cmake scripts, see the
|
|
HDF5options.cmake file under the toolchain section.
|
|
|
|
Notes: CMake and HDF5
|
|
|
|
1. Using CMake for building and using HDF5 is under active development.
|
|
While we have attempted to provide error-free files, please
|
|
understand that development with CMake has not been extensively
|
|
tested outside of HDF. The CMake specific files may change
|
|
before the next release.
|
|
|
|
2. CMake support for HDF5 development should be usable on any
|
|
system where CMake is supported. Please send us any comments on
|
|
how CMake support can be improved on any system. Visit the
|
|
KitWare site for more information about CMake.
|
|
|
|
3. Build and test results can be submitted to our CDash server:
|
|
The CDash server for community submissions of hdf5 is at
|
|
https://cdash.hdfgroup.org.
|
|
|
|
Submitters are requested to register their name and contact info and
|
|
maintain their test sites. After your first submission, login and go
|
|
to your "My CDash" link and claim your site.
|
|
|
|
We ask that all submissions include the configuration information and
|
|
contact information in the CTest Notes Files upload step. See the
|
|
current reports on CDash for examples.
|
|
|
|
Please follow the convention that "NIGHTLY" submissions maintain the same
|
|
configuration every time. "EXPERIMENTAL" submissions can be expected to
|
|
be different for each submission.
|
|
|
|
4. See the appendix at the bottom of this file for examples of using
|
|
a ctest script for building and testing. Using a ctest script is
|
|
preferred because of its flexibility.
|
|
|
|
Notes: CMake in General
|
|
|
|
1. More information about using CMake can be found at the KitWare site at
|
|
www.cmake.org.
|
|
|
|
2. CMake uses the command line; however, the visual CMake tool is
|
|
available for the configuration step. The steps are similar for
|
|
all the operating systems supported by CMake.
|
|
|
|
|
|
========================================================================
|
|
V. Options for Building HDF5 Libraries with the CMake Command Line
|
|
========================================================================
|
|
|
|
To build the HDF5 Libraries with CMake, go through these five steps:
|
|
|
|
1. Run CMake
|
|
2. Configure the cache settings
|
|
3. Build HDF5
|
|
4. Test HDF5
|
|
5. Package HDF5 (create install image)
|
|
|
|
These five steps are described in detail below.
|
|
|
|
========================================================================
|
|
|
|
1. Run CMake
|
|
|
|
The visual CMake executable is named "cmake-gui.exe" on Windows and should be
|
|
available in your Start menu. For Linux, UNIX, and Mac users the
|
|
executable is named "cmake-gui" and can be found where CMake was
|
|
installed.
|
|
|
|
Specify the source and build directories.
|
|
|
|
***** Make the build and source directories different. ******
|
|
|
|
For example on Windows, if the source is at c:\MyHDFstuff\hdf5,
|
|
then use c:\MyHDFstuff\hdf5\build or c:\MyHDFstuff\build\hdf5 as the
|
|
build directory.
|
|
|
|
RECOMMENDED:
|
|
Users can perform the configuration step without using the visual
|
|
cmake-gui program. We use the file cacheinit.cmake in the
|
|
config/cmake source folder for our testing. This file enables all of the
|
|
basic options and we turn specific options on or off for testing
|
|
using the following command line within the build directory:
|
|
|
|
cmake -C <sourcepath>/config/cmake/cacheinit.cmake -G "<generator>" [-D<options>] <sourcepath>
|
|
|
|
Where <generator> is
|
|
* MinGW Makefiles
|
|
* NMake Makefiles
|
|
* Unix Makefiles
|
|
* Visual Studio 14 2015
|
|
* Visual Studio 14 2015 Win64
|
|
* Visual Studio 15 2017
|
|
* Visual Studio 15 2017 Win64
|
|
* Visual Studio 16 2019
|
|
|
|
<options> is:
|
|
* SZIP_INCLUDE_DIR:PATH=<path to szip includes directory>
|
|
* SZIP_LIBRARY:FILEPATH=<path to szip/library file>
|
|
* ZLIB_INCLUDE_DIR:PATH=<path to zlib includes directory>
|
|
* ZLIB_LIBRARY:FILEPATH=<path to zlib/library file>
|
|
* <HDF5OPTION>:BOOL=[ON | OFF]
|
|
|
|
<cacheinit.cmake> is:
|
|
# This is the CMakeCache file used by HDF Group for daily tests.
|
|
########################
|
|
# EXTERNAL cache entries
|
|
########################
|
|
set (CMAKE_INSTALL_FRAMEWORK_PREFIX "Library/Frameworks" CACHE STRING "Frameworks installation directory" FORCE)
|
|
set (HDF_PACKAGE_EXT "" CACHE STRING "Name of HDF package extension" FORCE)
|
|
set (HDF5_BUILD_FORTRAN ON CACHE BOOL "Build FORTRAN support" FORCE)
|
|
set (HDF5_ENABLE_Z_LIB_SUPPORT ON CACHE BOOL "Enable Zlib Filters" FORCE)
|
|
set (HDF5_ENABLE_SZIP_SUPPORT ON CACHE BOOL "Use SZip Filter" FORCE)
|
|
set (HDF5_ENABLE_SZIP_ENCODING ON CACHE BOOL "Use SZip Encoding" FORCE)
|
|
set (MPIEXEC_MAX_NUMPROCS "3" CACHE STRING "Minimum number of processes for HDF parallel tests" FORCE)
|
|
set (HDF5_ENABLE_ALL_WARNINGS ON CACHE BOOL "Enable all warnings" FORCE)
|
|
set (HDF_TEST_EXPRESS "2" CACHE STRING "Control testing framework (0-3)" FORCE)
|
|
set (HDF5_ALLOW_EXTERNAL_SUPPORT "NO" CACHE STRING "Allow External Library Building (NO GIT TGZ)" FORCE)
|
|
set_property (CACHE HDF5_ALLOW_EXTERNAL_SUPPORT PROPERTY STRINGS NO GIT TGZ)
|
|
set (ZLIB_TGZ_NAME "ZLib.tar.gz" CACHE STRING "Use ZLib from compressed file" FORCE)
|
|
set (SZIP_TGZ_NAME "SZip.tar.gz" CACHE STRING "Use SZip from compressed file" FORCE)
|
|
set (SZAEC_TGZ_NAME "LIBAEC.tar.gz" CACHE STRING "Use SZip AEC from compressed file" FORCE)
|
|
set (USE_LIBAEC ON CACHE BOOL "Use libaec szip replacement" FORCE)
|
|
set (ZLIB_PACKAGE_NAME "zlib" CACHE STRING "Name of ZLIB package" FORCE)
|
|
set (LIBAEC_PACKAGE_NAME "libaec" CACHE STRING "Name of AEC SZIP package" FORCE)
|
|
set (SZIP_PACKAGE_NAME "szip" CACHE STRING "Name of SZIP package" FORCE)
|
|
|
|
2. Configure the cache settings
|
|
|
|
2.1 Visual CMake users, click the Configure button. If this is the first time you are
|
|
running cmake-gui in this directory, you will be prompted for the
|
|
generator you wish to use (for example on Windows, Visual Studio 12).
|
|
CMake will read in the CMakeLists.txt files from the source directory and
|
|
display options for the HDF5 project. After the first configure you
|
|
can adjust the cache settings and/or specify the locations of other programs.
|
|
|
|
Any conflicts or new values will be highlighted by the configure
|
|
process in red. Once you are happy with all the settings and there are no
|
|
more values in red, click the Generate button to produce the appropriate
|
|
build files.
|
|
|
|
On Windows, if you are using a Visual Studio generator, the solution and
|
|
project files will be created in the build folder.
|
|
|
|
On linux, if you are using the Unix Makefiles generator, the Makefiles will
|
|
be created in the build folder.
|
|
|
|
2.2 Preferred command line example on Windows in c:\MyHDFstuff\hdf5\build directory:
|
|
|
|
cmake -C ../config/cmake/cacheinit.cmake -G "Visual Studio 12 2013" \
|
|
-DHDF5_ENABLE_SZIP_SUPPORT:BOOL=OFF -DHDF5_ENABLE_Z_LIB_SUPPORT:BOOL=OFF \
|
|
-DCMAKE_BUILD_TYPE:STRING=Release ..
|
|
|
|
2.3 On Windows, if you are using a Visual Studio Express version you must
|
|
be sure that the following two options are correctly set/unset:
|
|
|
|
HDF5_NO_PACKAGES:BOOL=ON
|
|
HDF5_USE_FOLDERS:BOOL=OFF
|
|
|
|
3. Build HDF5
|
|
|
|
On Windows, you can build HDF5 using either the Visual Studio Environment
|
|
or the command line. The command line can be used on all platforms;
|
|
Windows, linux, Unix, and Mac.
|
|
|
|
To build from the command line, navigate to your build directory and
|
|
execute the following:
|
|
|
|
cmake --build . --config {Debug | Release}
|
|
|
|
NOTE: "--config {Debug | Release}" may be optional on your platform. We
|
|
recommend choosing either Debug or Release on Windows.
|
|
|
|
3.1 If you wish to use the Visual Studio environment, open the solution
|
|
file in your build directory. Be sure to select either Debug or
|
|
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 a GIT repository.
|
|
The option is 'HDF5_ALLOW_EXTERNAL_SUPPORT'; by adding the following
|
|
configuration option:
|
|
-DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING="GIT"
|
|
|
|
The options to control the GIT URL (config/cmake/cacheinit.cmake file) are:
|
|
ZLIB_GIT_URL:STRING="http://${git_url}/zlib"
|
|
SZIP_GIT_URL:STRING="http://${git_url}/szip"
|
|
${git_url} should be changed to your location. Also define CMAKE_BUILD_TYPE
|
|
to be the configuration type.
|
|
|
|
3.2.2 Or the external libraries (zlib and szip) can be configured
|
|
to allow building the libraries by using a compressed file.
|
|
The option is 'HDF5_ALLOW_EXTERNAL_SUPPORT' and is enabled by
|
|
adding the following configuration option:
|
|
-DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING="TGZ"
|
|
|
|
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"
|
|
LIBAEC_TGZ_NAME:STRING="liaec_src.ext"
|
|
TGZPATH:STRING="some_location"
|
|
where "some_location/xxxx_src.ext" is the URL or full path to
|
|
the compressed file and where ext is the type of the compression
|
|
file such as .bz2, .tar, .tar.gz, .tgz, or .zip. Also define
|
|
CMAKE_BUILD_TYPE to be the configuration type.
|
|
|
|
NOTE: the USE_LIBAEC option will use the file named by LIBAEC_TGZ_NAME
|
|
to build SZIP instead of the file named by SZIP_TGZ_NAME. This option
|
|
is also used to account for the different headers and library names.
|
|
|
|
4. Test HDF5
|
|
|
|
To test the build, navigate to your build directory and execute:
|
|
|
|
ctest . -C {Debug | Release}
|
|
|
|
NOTE: "-C {Debug | Release}" may be optional on your platform. We
|
|
recommend choosing either Debug or Release to match the build
|
|
step on Windows.
|
|
|
|
5. Packaging HDF5 (create an install image)
|
|
|
|
To package the build into a simple installer using WiX toolset or the NullSoft installer NSIS
|
|
on Windows, or into compressed files (.tar.gz, .sh, .zip), use the CPack tool.
|
|
|
|
To package the build, navigate to your build directory and execute;
|
|
|
|
cpack -C {Debug | Release} CPackConfig.cmake
|
|
|
|
NOTE: See note 8 of this document for NSIS information.
|
|
See note 9 of this document for WiX information.
|
|
Also, if you are using a Visual Studio Express version or
|
|
want to disable the packaging components, set HDF5_NO_PACKAGES
|
|
to ON (on the command line add -DHDF5_NO_PACKAGES:BOOL=ON)
|
|
|
|
6. The files that support building HDF5 with CMake are all the files in the
|
|
config/cmake folder, the CMakeLists.txt files in each source folder, and
|
|
CTestConfig.cmake. CTestConfig.cmake is specific to the internal testing
|
|
performed by The HDF Group. It should be altered for the user's
|
|
installation and needs. The cacheinit.cmake file settings are used by
|
|
The HDF Group for daily testing. It should be altered/ignored for the user's
|
|
installation and needs.
|
|
|
|
7. More information about using CMake can be found at the KitWare site,
|
|
www.cmake.org.
|
|
|
|
8. Nullsoft Scriptable Install System
|
|
The Nullsoft Scriptable Install System (NSIS) is an open source installation
|
|
system. It was created by the WinAmp authors to distribute that application,
|
|
but it is now a general-purpose system which anyone might use. NSIS installers
|
|
recognize /S for silent installation and /D=dir to specify the
|
|
"output directory", which is where the program will be installed. These
|
|
options are case-sensitive, so be sure to type them in upper case.
|
|
|
|
9. WiX Toolset
|
|
WiX--the Windows Installer XML toolset--lets developers create installers for
|
|
Windows Installer, the Windows installation engine. See http://wixtoolset.org.
|
|
|
|
|
|
========================================================================
|
|
VI. CMake Option Defaults for HDF5
|
|
========================================================================
|
|
|
|
In the options listed below, there are three columns of information:
|
|
Option Name, Option Description, and Option Default.
|
|
The config/cmake/cacheinit.cmake file can override the following values.
|
|
|
|
---------------- General Build Options ---------------------
|
|
BUILD_SHARED_LIBS "Build Shared Libraries" ON
|
|
BUILD_STATIC_LIBS "Build Static Libraries" ON
|
|
BUILD_STATIC_EXECS "Build Static Executables" OFF
|
|
BUILD_TESTING "Build HDF5 Unit Testing" ON
|
|
|
|
---------------- HDF5 Build Options ---------------------
|
|
HDF5_BUILD_CPP_LIB "Build HDF5 C++ Library" ON
|
|
HDF5_BUILD_EXAMPLES "Build HDF5 Library Examples" ON
|
|
HDF5_BUILD_FORTRAN "Build FORTRAN support" OFF
|
|
HDF5_BUILD_JAVA "Build JAVA support" OFF
|
|
HDF5_BUILD_HL_LIB "Build HIGH Level HDF5 Library" ON
|
|
HDF5_BUILD_TOOLS "Build HDF5 Tools" ON
|
|
|
|
---------------- HDF5 Advanced Options ---------------------
|
|
ONLY_SHARED_LIBS "Only Build Shared Libraries" OFF
|
|
ALLOW_UNSUPPORTED "Allow unsupported combinations of configure options" OFF
|
|
HDF5_EXTERNAL_LIB_PREFIX "Use prefix for custom library naming." ""
|
|
HDF5_DISABLE_COMPILER_WARNINGS "Disable compiler warnings" OFF
|
|
HDF5_ENABLE_ALL_WARNINGS "Enable all warnings" OFF
|
|
HDF5_ENABLE_CODESTACK "Enable the function stack tracing (for developer debugging)." OFF
|
|
HDF5_ENABLE_COVERAGE "Enable code coverage for Libraries and Programs" OFF
|
|
HDF5_ENABLE_DEBUG_APIS "Turn on extra debug output in all packages" OFF
|
|
HDF5_ENABLE_DEPRECATED_SYMBOLS "Enable deprecated public API symbols" ON
|
|
HDF5_ENABLE_DIRECT_VFD "Build the Direct I/O Virtual File Driver" OFF
|
|
HDF5_ENABLE_EMBEDDED_LIBINFO "embed library info into executables" ON
|
|
HDF5_ENABLE_HSIZET "Enable datasets larger than memory" ON
|
|
HDF5_ENABLE_PARALLEL "Enable parallel build (requires MPI)" OFF
|
|
HDF5_ENABLE_PREADWRITE "Use pread/pwrite in sec2/log/core VFDs in place of read/write (when available)" ON
|
|
HDF5_ENABLE_TRACE "Enable API tracing capability" OFF
|
|
HDF5_ENABLE_USING_MEMCHECKER "Indicate that a memory checker is used" OFF
|
|
HDF5_GENERATE_HEADERS "Rebuild Generated Files" ON
|
|
HDF5_BUILD_GENERATORS "Build Test Generators" OFF
|
|
HDF5_JAVA_PACK_JRE "Package a JRE installer directory" OFF
|
|
HDF5_MEMORY_ALLOC_SANITY_CHECK "Indicate that internal memory allocation sanity checks are enabled" OFF
|
|
HDF5_NO_PACKAGES "Do not include CPack Packaging" OFF
|
|
HDF5_PACK_EXAMPLES "Package the HDF5 Library Examples Compressed File" OFF
|
|
HDF5_PACK_MACOSX_FRAMEWORK "Package the HDF5 Library in a Frameworks" OFF
|
|
HDF5_BUILD_FRAMEWORKS "TRUE to build as frameworks libraries,
|
|
FALSE to build according to BUILD_SHARED_LIBS" FALSE
|
|
HDF5_PACKAGE_EXTLIBS "CPACK - include external libraries" OFF
|
|
HDF5_STRICT_FORMAT_CHECKS "Whether to perform strict file format checks" OFF
|
|
HDF_TEST_EXPRESS "Control testing framework (0-3)" "0"
|
|
HDF5_TEST_VFD "Execute tests with different VFDs" OFF
|
|
HDF5_TEST_PASSTHROUGH_VOL "Execute tests with different passthrough VOL connectors" OFF
|
|
DEFAULT_API_VERSION "Enable default API (v16, v18, v110, v112, v114)" "v114"
|
|
HDF5_USE_FOLDERS "Enable folder grouping of projects in IDEs." ON
|
|
HDF5_WANT_DATA_ACCURACY "IF data accuracy is guaranteed during data conversions" ON
|
|
HDF5_WANT_DCONV_EXCEPTION "exception handling functions is checked during data conversions" ON
|
|
HDF5_ENABLE_THREADSAFE "Enable Threadsafety" OFF
|
|
if (APPLE)
|
|
HDF5_BUILD_WITH_INSTALL_NAME "Build with library install_name set to the installation path" OFF
|
|
if (CMAKE_BUILD_TYPE MATCHES Debug)
|
|
HDF5_ENABLE_INSTRUMENT "Instrument The library" OFF
|
|
if (HDF5_TEST_VFD)
|
|
HDF5_TEST_FHEAP_VFD "Execute fheap test with different VFDs" ON
|
|
if (HDF5_BUILD_FORTRAN)
|
|
HDF5_INSTALL_MOD_FORTRAN "Copy FORTRAN mod files to include directory (NO SHARED STATIC)" "XX"
|
|
if (BUILD_SHARED_LIBS AND BUILD_STATIC_LIBS) default HDF5_INSTALL_MOD_FORTRAN is SHARED
|
|
if (BUILD_SHARED_LIBS AND NOT BUILD_STATIC_LIBS) default HDF5_INSTALL_MOD_FORTRAN is SHARED
|
|
if (NOT BUILD_SHARED_LIBS AND BUILD_STATIC_LIBS) default HDF5_INSTALL_MOD_FORTRAN is STATIC
|
|
if (NOT BUILD_SHARED_LIBS AND NOT BUILD_STATIC_LIBS) default HDF5_INSTALL_MOD_FORTRAN is SHARED
|
|
|
|
---------------- External Library Options ---------------------
|
|
HDF5_ALLOW_EXTERNAL_SUPPORT "Allow External Library Building (NO GIT TGZ)" "NO"
|
|
HDF5_ENABLE_SZIP_SUPPORT "Use SZip Filter" OFF
|
|
HDF5_ENABLE_Z_LIB_SUPPORT "Enable Zlib Filters" OFF
|
|
ZLIB_USE_EXTERNAL "Use External Library Building for ZLIB" 0
|
|
SZIP_USE_EXTERNAL "Use External Library Building for SZIP" 0
|
|
if (HDF5_ENABLE_SZIP_SUPPORT)
|
|
HDF5_ENABLE_SZIP_ENCODING "Use SZip Encoding" OFF
|
|
USE_LIBAEC "Use libaec szip replacement" OFF
|
|
if (WINDOWS)
|
|
H5_DEFAULT_PLUGINDIR "%ALLUSERSPROFILE%/hdf5/lib/plugin"
|
|
else ()
|
|
H5_DEFAULT_PLUGINDIR "/usr/local/hdf5/lib/plugin"
|
|
endif ()
|
|
|
|
NOTE:
|
|
The BUILD_STATIC_EXECS ("Build Static Executables") option is only valid
|
|
on some unix operating systems. It adds the "-static" flag to cflags. This
|
|
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
|
|
========================================================================
|
|
|
|
Support for User Defined macros and options has been added. The file
|
|
UserMacros.cmake has an example of the technique. In the folder,
|
|
config/cmake/UserMacros, is an implementation for Windows Visual Studio
|
|
users for linking libraries to the static CRT - Windows_MT.cmake.
|
|
|
|
Copy the contents of the file, both macro and option, into the
|
|
UserMacros.cmake file. Then enable the option to the CMake configuration,
|
|
build and test process.
|
|
|
|
|
|
========================================================================
|
|
VIII. User Defined Compile Flags for HDF5 Libraries with CMake
|
|
========================================================================
|
|
|
|
Custom compiler flags can be added by defining the CMAKE_C_FLAGS and
|
|
CMAKE_CXX_FLAGS variables.
|
|
Using a cmake script:
|
|
set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O2")
|
|
Defined on the configure line:
|
|
cmake -G "Visual Studio 12 2013" -DCMAKE_C_FLAGS:STRING=-O2 ..
|
|
|
|
Debug symbols are enabled with configuration selections Debug or RelWithDebInfo.
|
|
The difference between Debug and RelWithDebInfo configurations is that
|
|
RelWithDebInfo optimizes the code similar to Release. It produces fully optimized
|
|
code, but also creates the symbol table and the debug metadata to give the
|
|
debugger input to map the execution back to the original code.
|
|
RelwithDebInfo configuration should not affect the performance when the code
|
|
is run without a debugger attached.
|
|
|
|
The HDF5_ENABLE_COVERAGE option will add "-g -O0 -fprofile-arcs -ftest-coverage"
|
|
to CMAKE_C_FLAGS.
|
|
|
|
|
|
========================================================================
|
|
For further assistance, send email to help@hdfgroup.org
|
|
========================================================================
|
|
|
|
|
|
|