2010-05-27 00:47:12 +08:00
|
|
|
************************************************************************
|
|
|
|
|
* Build and Install HDF5 C/C++ Library with CMake *
|
|
|
|
|
************************************************************************
|
|
|
|
|
|
|
|
|
|
Notes: This short instruction is written for users who want to quickly build
|
|
|
|
|
HDF5 library and tools from the HDF5 source code package using the
|
|
|
|
|
CMake tools.
|
|
|
|
|
|
|
|
|
|
More information about using CMake can be found at the KitWare site,
|
|
|
|
|
www.cmake.org.
|
|
|
|
|
|
|
|
|
|
CMake uses the command line, however the visual CMake tool is
|
|
|
|
|
recommended for the configuration step. The steps are similiar for
|
|
|
|
|
all the operating systems supported by CMake.
|
|
|
|
|
|
|
|
|
|
NOTES:
|
2011-01-26 04:40:41 +08:00
|
|
|
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
|
2010-09-21 01:27:29 +08:00
|
|
|
before the next release.
|
|
|
|
|
|
2011-01-26 04:40:41 +08:00
|
|
|
2. CMake was originally introduced to support development on Windows,
|
|
|
|
|
however it 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.
|
|
|
|
|
|
2011-08-25 23:08:29 +08:00
|
|
|
3. If you are building HDF5 on Windows, do NOT use or execute any
|
|
|
|
|
files from the windows folder.
|
|
|
|
|
|
|
|
|
|
4. Build and test results can be submitted to our CDash server at:
|
|
|
|
|
cdash.hdfgroup.uiuc.edu.
|
2011-01-26 04:40:41 +08:00
|
|
|
Please read the HDF and CDash document at:
|
|
|
|
|
www.hdfgroup.org/CDash/HowToSubmit.
|
2010-05-27 00:47:12 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
========================================================================
|
|
|
|
|
Preconditions
|
|
|
|
|
========================================================================
|
|
|
|
|
|
|
|
|
|
1. We suggest you obtain the latest CMake for windows from the Kitware
|
2011-03-15 03:13:15 +08:00
|
|
|
web site. The HDF5 1.8.x product requires CMake version 2.8.4.
|
2010-05-27 00:47:12 +08:00
|
|
|
|
2011-01-26 04:40:41 +08:00
|
|
|
2. If you plan to use Zlib or Szip;
|
|
|
|
|
A. Download the packages and install them
|
|
|
|
|
in a central location. For example on Windows, create a folder extlibs
|
|
|
|
|
and install the packages there. Windows users should also read Section V
|
|
|
|
|
in INSTALL_Windows.txt.
|
|
|
|
|
B. Use source packages from a SVN server by adding the following CMake
|
|
|
|
|
options:
|
|
|
|
|
HDF5_ALLOW_EXTERNAL_SUPPORT:STRING="SVN"
|
|
|
|
|
ZLIB_SVN_URL:STRING="http://some_location/zlib/trunk"
|
|
|
|
|
SZIP_SVN_URL:STRING="http://some_location/szip/trunk"
|
|
|
|
|
where "some_location" is the URL to the SVN repository.
|
|
|
|
|
C. Use source packages from a compressed file by adding the following CMake
|
|
|
|
|
options:
|
|
|
|
|
HDF5_ALLOW_EXTERNAL_SUPPORT:STRING="TGZ"
|
2011-01-26 05:17:54 +08:00
|
|
|
ZLIB_TGZ_NAME:STRING="zlib_src.ext"
|
|
|
|
|
SZIP_TGZ_NAME:STRING="szip_src.ext"
|
|
|
|
|
TGZ_PATH:STRING="some_location"
|
2011-01-26 04:40:41 +08:00
|
|
|
where "some_location" is the URL or full path to the compressed file and
|
|
|
|
|
ext is the type of compression file.
|
|
|
|
|
|
2010-05-27 00:47:12 +08:00
|
|
|
|
|
|
|
|
========================================================================
|
|
|
|
|
Building HDF5 C/C++ Libraries with CMake
|
|
|
|
|
========================================================================
|
|
|
|
|
|
|
|
|
|
1. Run CMake
|
|
|
|
|
|
|
|
|
|
The 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. It is recommemded that you
|
|
|
|
|
choose a build directory different then the source directory
|
|
|
|
|
(for example on Windows, if the source is at c:\MyHDFstuff\hdf5, then
|
|
|
|
|
use c:\MyHDFstuff\hdf5\build or c:\MyHDFstuff\build\hdf5).
|
2010-09-21 01:27:29 +08:00
|
|
|
|
|
|
|
|
OPTIONAL:
|
|
|
|
|
Users can perform the configuration step without using the visual cmake-gui
|
|
|
|
|
program. We use the file cacheinit.cmake in the config/cmake folder for
|
|
|
|
|
our testing. This file enables all 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
|
|
|
|
|
* Borland Makefiles
|
|
|
|
|
* MSYS Makefiles
|
|
|
|
|
* MinGW Makefiles
|
|
|
|
|
* NMake Makefiles
|
|
|
|
|
* Unix Makefiles
|
|
|
|
|
* Visual Studio 10
|
|
|
|
|
* Visual Studio 10 Win64
|
|
|
|
|
* Visual Studio 6
|
|
|
|
|
* Visual Studio 7
|
|
|
|
|
* Visual Studio 7 .NET 2003
|
|
|
|
|
* Visual Studio 8 2005
|
|
|
|
|
* Visual Studio 8 2005 Win64
|
|
|
|
|
* Visual Studio 9 2008
|
|
|
|
|
* Visual Studio 9 2008 Win64
|
|
|
|
|
|
|
|
|
|
<options> is:
|
|
|
|
|
* SZIP_INCLUDE_DIR:PATH=<path to szip includes directory>
|
|
|
|
|
* SZIP_LIBRARY:FILEPATH=<path to szip/library file>
|
2011-08-26 23:38:35 +08:00
|
|
|
* ZLIB_INCLUDE_DIR:PATH=<path to zlib includes directory>
|
|
|
|
|
* ZLIB_LIBRARY:FILEPATH=<path to zlib/library file>
|
2010-09-21 01:27:29 +08:00
|
|
|
* <HDF5OPTION>:BOOL=[ON | OFF]
|
|
|
|
|
|
|
|
|
|
<cacheinit.cmake> is:
|
|
|
|
|
# This is the CMakeCache file.
|
|
|
|
|
########################
|
|
|
|
|
# EXTERNAL cache entries
|
|
|
|
|
########################
|
|
|
|
|
SET (BUILD_SHARED_LIBS ON CACHE BOOL "Build Shared Libraries" FORCE)
|
|
|
|
|
SET (BUILD_TESTING ON CACHE BOOL "Build HDF5 Unit Testing" FORCE)
|
|
|
|
|
SET (HDF5_BUILD_CPP_LIB ON CACHE BOOL "Build HDF5 C++ Library" FORCE)
|
|
|
|
|
SET (HDF5_BUILD_EXAMPLES ON CACHE BOOL "Build HDF5 Library Examples" FORCE)
|
|
|
|
|
SET (HDF5_BUILD_FORTRAN ON CACHE BOOL "Build FORTRAN support" FORCE)
|
|
|
|
|
SET (HDF5_BUILD_HL_LIB ON CACHE BOOL "Build HIGH Level HDF5 Library" FORCE)
|
|
|
|
|
SET (HDF5_BUILD_TOOLS ON CACHE BOOL "Build HDF5 Tools" FORCE)
|
|
|
|
|
SET (HDF5_DISABLE_COMPILER_WARNINGS OFF CACHE BOOL "Disable compiler warnings" FORCE)
|
|
|
|
|
SET (HDF5_ENABLE_HSIZET ON CACHE BOOL "Enable datasets larger than memory" FORCE)
|
|
|
|
|
SET (HDF5_ENABLE_PARALLEL OFF CACHE BOOL "Enable parallel build (requires MPI)" FORCE)
|
|
|
|
|
SET (HDF5_ENABLE_SZIP_ENCODING ON CACHE BOOL "Use SZip Encoding" FORCE)
|
|
|
|
|
SET (HDF5_ENABLE_SZIP_SUPPORT ON CACHE BOOL "Use SZip Filter" FORCE)
|
|
|
|
|
SET (HDF5_ENABLE_Z_LIB_SUPPORT ON CACHE BOOL "Enable Zlib Filters" FORCE)
|
|
|
|
|
SET (HDF5_ENABLE_COVERAGE OFF CACHE BOOL "Enable code coverage for Libraries and Programs" FORCE)
|
2010-05-27 00:47:12 +08:00
|
|
|
|
|
|
|
|
2. Configure the cache settings
|
|
|
|
|
|
2010-09-21 01:27:29 +08:00
|
|
|
2.1 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 9 2008).
|
|
|
|
|
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 locations of other programs.
|
2010-05-27 00:47:12 +08:00
|
|
|
|
2010-09-21 01:27:29 +08:00
|
|
|
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.
|
2010-05-27 00:47:12 +08:00
|
|
|
|
2010-09-21 01:27:29 +08:00
|
|
|
On Windows, if you are using a Visual Studio generator, the solution and
|
|
|
|
|
project files will be created in the build folder.
|
2010-05-27 00:47:12 +08:00
|
|
|
|
2010-09-21 01:27:29 +08:00
|
|
|
On linux, if you are using the Unix Makefiles generator, the Makefiles will
|
|
|
|
|
be created in the build folder.
|
|
|
|
|
|
|
|
|
|
2.2 Alternative command line example on Windows in c:\MyHDFstuff\hdf5\build directory:
|
|
|
|
|
|
|
|
|
|
cmake -C ../config/cmake/cacheinit.cmake -G "Visual Studio 9 2008" \
|
|
|
|
|
-DHDF5_ENABLE_SZIP_SUPPORT:BOOL=OFF -DHDF5_ENABLE_Z_LIB_SUPPORT:BOOL=OFF ..
|
2010-05-27 00:47:12 +08:00
|
|
|
|
2011-10-26 00:52:58 +08:00
|
|
|
2.3 On Windows, if you are using a VS 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
|
|
|
|
|
|
2010-05-27 00:47:12 +08:00
|
|
|
3. Build HDF5
|
|
|
|
|
|
|
|
|
|
On Windows, you can build HDF5 using either the Visual Studio Environment
|
|
|
|
|
or the command line. The command line is used on 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.
|
2010-10-15 05:58:35 +08:00
|
|
|
|
2011-01-26 22:09:45 +08:00
|
|
|
3.2.1 The external libraries (zlib and szip) can be configured
|
2010-10-15 05:58:35 +08:00
|
|
|
to allow building the libraries by downloading from a SVN repository.
|
|
|
|
|
The option is 'HDF5_ALLOW_EXTERNAL_SUPPORT'; by adding the following
|
|
|
|
|
configuration option:
|
|
|
|
|
-DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING="SVN"
|
|
|
|
|
|
2011-01-26 04:40:41 +08:00
|
|
|
The options to control the SVN URL (config/cmake/cacheinit.cmake file):
|
2010-10-15 05:58:35 +08:00
|
|
|
ZLIB_SVN_URL:STRING="http://svn.hdfgroup.uiuc.edu/zlib/trunk"
|
|
|
|
|
SZIP_SVN_URL:STRING="http://svn.hdfgroup.uiuc.edu/szip/trunk"
|
2011-01-26 04:40:41 +08:00
|
|
|
These should be changed to your location.
|
|
|
|
|
|
2011-01-26 22:09:45 +08:00
|
|
|
3.2.2 Or the external libraries (zlib and szip) can be configured
|
2011-01-26 04:40:41 +08:00
|
|
|
to allow building the libraries by using a compressed file.
|
|
|
|
|
The option is 'HDF5_ALLOW_EXTERNAL_SUPPORT'; by adding the following
|
|
|
|
|
configuration option:
|
|
|
|
|
-DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING="TGZ"
|
|
|
|
|
|
|
|
|
|
The options to control the SVN URL (config/cmake/cacheinit.cmake file):
|
2011-01-26 05:17:54 +08:00
|
|
|
ZLIB_TGZ_NAME:STRING="zlib_src.ext"
|
|
|
|
|
SZIP_TGZ_NAME:STRING="szip_src.ext"
|
|
|
|
|
TGZ_PATH:STRING="some_location"
|
2011-01-26 04:40:41 +08:00
|
|
|
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 like:
|
|
|
|
|
.bz2, .tar, .tar.gz, .tgz, .zip
|
2010-05-27 00:47:12 +08:00
|
|
|
|
|
|
|
|
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.
|
2010-09-21 01:27:29 +08:00
|
|
|
|
|
|
|
|
5. Packaging HDF5
|
|
|
|
|
|
|
|
|
|
To package the build into a simple installer using the NullSoft installer NSIS
|
|
|
|
|
on Windows, or into compressed files (.tar.gz, .sh, .zip), use the CPack tool.
|
|
|
|
|
|
2011-01-26 04:40:41 +08:00
|
|
|
To package the build, navigate to your build directory and execute;
|
2010-09-21 01:27:29 +08:00
|
|
|
|
2010-09-21 05:00:36 +08:00
|
|
|
cpack -C {Debug | Release} CPackConfig.cmake
|
2010-09-21 01:27:29 +08:00
|
|
|
|
|
|
|
|
NOTE: We have just introduced the packaging capability and it has not been
|
|
|
|
|
extensively tested. Please send us comments on how it can be improved.
|
2011-08-25 23:08:29 +08:00
|
|
|
See NSIS note 8 of this document.
|
2011-10-18 03:49:06 +08:00
|
|
|
Also, if you are using a VS Express version or do not want to enable
|
|
|
|
|
the packaging components, set HDF5_NO_PACKAGES to ON (on the command
|
|
|
|
|
line add -DHDF5_NO_PACKAGES:BOOL=ON)
|
2010-09-21 01:27:29 +08:00
|
|
|
|
2010-10-15 05:58:35 +08:00
|
|
|
6. The files that support building HDF5 with CMake are all the files in the
|
2010-09-21 01:27:29 +08:00
|
|
|
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 users
|
|
|
|
|
installation and needs.
|
2010-05-27 00:47:12 +08:00
|
|
|
|
2010-10-15 05:58:35 +08:00
|
|
|
7. More information about using CMake can be found at the KitWare site,
|
2010-05-27 00:47:12 +08:00
|
|
|
www.cmake.org.
|
2011-08-25 23:08:29 +08:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2011-10-01 02:19:54 +08:00
|
|
|
|
|
|
|
|
========================================================================
|
|
|
|
|
All options for HDF5 C/C++ Libraries with CMake
|
|
|
|
|
========================================================================
|
|
|
|
|
OPTION (HDF5_Enable_Clear_File_Buffers "Securely clear file buffers before writing to file" ON)
|
|
|
|
|
OPTION (HDF5_Enable_Instrument "Instrument The library" HDF5_Enable_Instrument)
|
|
|
|
|
OPTION (HDF5_STRICT_FORMAT_CHECKS "Whether to perform strict file format checks" OFF)
|
|
|
|
|
OPTION (HDF5_METADATA_TRACE_FILE "Enable metadata trace file collection" OFF)
|
|
|
|
|
OPTION (HDF5_WANT_DATA_ACCURACY "IF data accuracy is guaranteed during data conversions" ON)
|
|
|
|
|
OPTION (HDF5_WANT_DCONV_EXCEPTION "exception handling functions is checked during data conversions" ON)
|
|
|
|
|
OPTION (HDF5_ENABLE_CODESTACK "Enable the function stack tracing (for developer debugging)." OFF)
|
|
|
|
|
OPTION (HDF5_ENABLE_HSIZET "Enable datasets larger than memory" ON)
|
|
|
|
|
OPTION (HDF5_ENABLE_LARGE_FILE "Enable support for large (64-bit) files on Linux." ON)
|
|
|
|
|
OPTION (HDF5_ENABLE_GPFS "Enable GPFS hints for the MPI/POSIX file driver" OFF)
|
|
|
|
|
IF (APPLE) OPTION (HDF5_BUILD_WITH_INSTALL_NAME "Build with library install_name set to the installation path" OFF)
|
|
|
|
|
IF (WIN32 AND NOT CYGWIN) OPTION (HDF_LEGACY_NAMING "Use Legacy Names for Libraries and Programs" OFF)
|
|
|
|
|
OPTION (BUILD_SHARED_LIBS "Build Shared Libraries" OFF)
|
|
|
|
|
OPTION (BUILD_STATIC_EXECS "Build Static Executabless" OFF)
|
|
|
|
|
OPTION (BUILD_STATIC_PIC "Build Static PIC" OFF)
|
|
|
|
|
OPTION (HDF5_ENABLE_COVERAGE "Enable code coverage for Libraries and Programs" OFF)
|
|
|
|
|
OPTION (HDF5_ENABLE_USING_MEMCHECKER "Indicate that a memory checker is used" OFF)
|
|
|
|
|
OPTION (HDF5_ENABLE_DEPRECATED_SYMBOLS "Enable deprecated public API symbols" ON)
|
|
|
|
|
OPTION (HDF5_ENABLE_TRACE "Enable API tracing capability" ON)
|
|
|
|
|
OPTION (HDF5_ENABLE_TRACE "Enable API tracing capability" OFF)
|
|
|
|
|
OPTION (HDF5_ENABLE_EMBEDDED_LIBINFO "embed library info into executables" ON)
|
|
|
|
|
OPTION (HDF5_DISABLE_COMPILER_WARNINGS "Disable compiler warnings" OFF)
|
|
|
|
|
OPTION (HDF5_ENABLE_PARALLEL "Enable parallel build (requires MPI)" OFF)
|
|
|
|
|
OPTION (HDF5_USE_16_API_DEFAULT "Use the HDF5 1.6.x API by default" OFF)
|
|
|
|
|
OPTION (HDF5_USE_18_API_DEFAULT "Use the HDF5 1.8.x API by default" OFF)
|
|
|
|
|
OPTION (HDF5_USE_FILTER_${FILTER} "Use the ${FILTER} Filter" ON)
|
|
|
|
|
OPTION (HDF5_ALLOW_EXTERNAL_SUPPORT "Allow External Library Building" "NO")
|
|
|
|
|
OPTION (ZLIB_USE_EXTERNAL "Use External Library Building for ZLIB" 0)
|
|
|
|
|
OPTION (SZIP_USE_EXTERNAL "Use External Library Building for SZIP" 0)
|
|
|
|
|
OPTION (HDF5_ENABLE_Z_LIB_SUPPORT "Enable Zlib Filters" OFF)
|
|
|
|
|
OPTION (HDF5_ENABLE_SZIP_SUPPORT "Use SZip Filter" OFF)
|
|
|
|
|
IF (HDF5_ENABLE_SZIP_SUPPORT) OPTION (HDF5_ENABLE_SZIP_ENCODING "Use SZip Encoding" OFF)
|
|
|
|
|
OPTION (HDF5_PACKAGE_EXTLIBS "CPACK - include external libraries" OFF)
|
|
|
|
|
IF (WIN32 AND NOT CYGWIN) OPTION (HDF5_ENABLE_THREADSAFE "Enable Threadsafety" OFF)
|
|
|
|
|
OPTION (BUILD_TESTING "Build HDF5 Unit Testing" OFF)
|
|
|
|
|
OPTION (HDF5_TEST_VFD "Execute tests with different VFDs" OFF)
|
|
|
|
|
IF (HDF5_TEST_VFD) OPTION (HDF5_TEST_FHEAP_VFD "Execute tests with different VFDs" ON)
|
|
|
|
|
OPTION (HDF5_BUILD_FORTRAN "Build FORTRAN support" OFF)
|
|
|
|
|
IF (HDF5_BUILD_FORTRAN) OPTION (HDF5_ENABLE_F2003 "Enable FORTRAN 2003 Standard" OFF)
|
|
|
|
|
OPTION (HDF5_BUILD_EXAMPLES "Build HDF5 Library Examples" OFF)
|
|
|
|
|
OPTION (HDF5_BUILD_CPP_LIB "Build HDF5 C++ Library" OFF)
|
|
|
|
|
OPTION (HDF5_BUILD_TOOLS "Build HDF5 Tools" OFF)
|
|
|
|
|
OPTION (HDF5_BUILD_HL_LIB "Build HIGH Level HDF5 Library" OFF)
|
2011-10-26 00:52:58 +08:00
|
|
|
OPTION (HDF5_NO_PACKAGES "Do not include CPack Packaging" OFF)
|
|
|
|
|
OPTION (HDF5_USE_FOLDERS "Do not include CPack Packaging" OFF)
|
2010-05-27 00:47:12 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
************************************************************************
|
|
|
|
|
|
|
|
|
|
Need further assistance, send email to help@hdfgroup.org
|
|
|
|
|
|
