This web site is no longer maintained (but will remain online).
Please see The HDF Group's new Support Portal for the latest information.

HOME > HDF5 > RELEASE

Building HDF5-1.8 With CMake

A CTest script and platform configuration file can be used to simplify building with CMake. The following instructions are provided for this purpose.

If you need to build with more complex options, you may prefer to follow the instructions in the release_docs/ directory of the HDF5 source code.

Preconditions
Build Instructions
Compiling an Application
Troubleshooting
Common CMake and configure Options

Preconditions:

CMake MUST be installed. The configuration scripts were tested with CMake 3.2.2.
Blank spaces MUST NOT be used in directory path names as this will cause the build to fail.
(Optional) On Windows, an NSIS or WiX should be installed in order to create an install image with CPack. NSIS will create a .exe installer. WiX will create a .msi installer.

Build Instructions

Please follow the instructions below for building.

Review the preconditions to be sure all needed software is on your machine.
Create a working directory.
From the table below download the appropriate file for your platform to your working directory. Uncompress it. It will contain a CMake-hdf5-1.8.20 directory.

Software Comments

Windows Contains files to build HDF5 with CMake on Windows

Unix Contains files to build HDF5 with CMake on Unix (see Browser Issue)

MD5 Checksums (for the files above)

From the command line, go into the CMake-hdf5-1.8.20 directory, which contains:

    build*.sh (.bat)         Build Script(s)
    CTestScript.cmake        ctest Command
    hdf5-1.8.20/             HDF5 Source Code
    HDF5config.cmake         Configuration File
    SZip.tar.gz              External Library for SZIP Compression
    ZLib.tar.gz              External Library for ZLIB Compression

These files will build the static HDF5 C and C++ libraries with SZIP and ZLIB compression included.

(If needed) Change the options that the HDF5 library is built with. See the Changing CMake Build Options page for details.
REQUIRED for Visual Studio Express: users must change the build options to turn off packaging or the build will fail. To do this edit HDF5config.cmake and uncomment:
```
  #set(LOCAL_NO_PACKAGE "TRUE")
  #set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_NO_PACKAGES:BOOL=ON")
```

Execute the batch file or shell script for your platform. It contains the ctest command that you need to run to build HDF5. (See Troubleshooting if you do not see your platform).

Platform	Batch File or Shell Script	Contains following ctest command
Windows 64-bit VS 2015	build-VS2015-64.bat	ctest -S HDF5config.cmake,BUILD_GENERATOR=VS201564 -C Release -V -O hdf5.log
Windows 32-bit VS 2015	build-VS2015-32.bat	ctest -S HDF5config.cmake,BUILD_GENERATOR=VS2015 -C Release -V -O hdf5.log
Windows 64-bit VS 2013	build-VS2013-64.bat	ctest -S HDF5config.cmake,BUILD_GENERATOR=VS201364 -C Release -V -O hdf5.log
Windows 32-bit VS 2013	build-VS2013-32.bat	ctest -S HDF5config.cmake,BUILD_GENERATOR=VS2013 -C Release -V -O hdf5.log
Windows 64-bit VS 2012	build-VS2012-64.bat	ctest -S HDF5config.cmake,BUILD_GENERATOR=VS201264 -C Release -V -O hdf5.log
Windows 32-bit VS 2012	build-VS2013-32.bat	ctest -S HDF5config.cmake,BUILD_GENERATOR=VS2012 -C Release -V -O hdf5.log
Unix	build-unix.sh	ctest -S HDF5config.cmake,BUILD_GENERATOR=Unix -C Release -V -O hdf5.log

Where the ctest command is using these options:

The -S option uses the script version of ctest. HDF5config.cmake is the configuration file.
The -C option specifies the build configuration which matches CTEST_BUILD_CONFIGURATION in the configuration file.
The -V option indicates verbose. If encountering problems, specify -VV for more verbose output.
The -O option saves the output to a log file, hdf5.log.

Locate the built binary.
The built binary will be in the bin directory and will also be copied to the CMake-hdf5-1.8.20 directory if successful. It will have the format:
```
  HDF5-1.8.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).
If the built binary is not there, then see Troubleshooting for help.
Check what is included with your built binaries.
You will find the libhdf5.settings file in the build directory. It contains information on how the binaries were built.

If you uncompress the built binary, you will find the hdf5-config.cmake and hdf5-targets.cmake files (among others) in a cmake directory. This cmake directory can be found in the same location as the lib, include, and bin directories on Windows and under share/ on Unix. The options in the hdf5-config.cmake file match those in the libhdf5.settings file.

The binaries by default will include the static HDF5 C and C++ libraries, as well as the SZIP and ZLIB external libraries. Please NOTE that they will NOT include the HDF5 Fortran library. See the Changing CMake Build Options page for instructions on building with Fortran.
Follow the instructions below for Compiling an Application with the binaries that are built.

Compiling an Application

Please see the framework for building applications that is provided on the HDF5-1.10 CMake build page.

For building these or other applications, please refer to the instructions in the release_docs/ directory of the HDF5 source code:

USING_HDF5_CMake.txt: Basic instructions for building HDF5 applications using the CMake tools.
USING_CMake_Examples.txt: Instructions for building the HDF5 Examples.

In general, users must first set the HDF5_DIR environment variable to the installed location of the CMake configuration files for HDF5. For example, on Windows the following path might be set:

   HDF5_DIR=C:/Program Files/HDF_Group/HDF5/1.8.x/cmake

Look at find_package provided with the HDF5 examples for how to compile an application. Please be aware that FindHDF5.cmake is not provided by and cannot be fixed by The HDF Group.

Troubleshooting

I can build HDF5 successfully but the findHDF5.cmake package does not populate HDF5_LIBRARIES. How do you use the HDF5 libraries that you built ?

The FindHDF5.cmake package is not supported or provided by The HDF Group. The HDF Group cannot change it. However, you can use find_package.

See the question below on how to use find_package.
How do you use find_package with HDF5?

To use find_package you will first need to make sure that HDF5_DIR is set correctly. For setting this environment variable see the Preconditions in the USING_HDF5_CMake.txt file in the source code.

Please note that the find_package invocation changed as of HDF5-1.8.16 to require "shared" or "static." This change allows both shared and static libraries to be built at the same time with CMake:
```
      FIND_PACKAGE(HDF5 COMPONENTS C HL NO_MODULE REQUIRED shared)
      FIND_PACKAGE(HDF5 COMPONENTS C HL NO_MODULE REQUIRED static)
  
```
Previously, the find_package invocation was:
```
      FIND_PACKAGE(HDF5 COMPONENTS C HL NO_MODULE REQUIRED)
   
```
My platform/compiler is not included. Can I still use the configuration files?

Yes, you can but you will have to edit the HDF5config.cmake file and update the variable:
```
   CTEST_CMAKE_GENERATOR
  
```
Other variables may be updated for informational purposes but are not required (for example, SITE_OS_BITS).

The generators for your platform can be seen by typing:
```
   cmake --help
  
```
What do I do if the build fails?

I received an error during the build and the built and compressed HDF5 binary is not in the CMake-hdf5-1.8.20/build directory as I expected. How do I determine what the problem is?

If the error is not clear, then the first thing you may want to do is replace the -V (Dash Vee) option for ctest in the build script to -VV (Dash Vee Vee). Then remove the build directory and re-run the build script. The output should be more verbose.

If the error is still not clear, then check the log files. You will find those in the build directory under CMake-hdf5-1.8.20. For example, on Unix the log files will be in:
```
   CMake-hdf5-1.8.20/build/Testing/Temporary/
  
```
There are log files for the configure, test, and build.
What do I do if I need to rebuild the software?

If you have to rebuild HDF5, remove the build directory first.
The library was built but there are no binaries. What do I do?

To install or package the binaries, run either make install or cpack in the build/ directory.

- - Last modified: 29 November 2017

Software	Comments
Windows	Contains files to build HDF5 with CMake on Windows
Unix	Contains files to build HDF5 with CMake on Unix (see Browser Issue)