************************************************************************
* Build and Install HDF5 C/C++ Library with CMake                      *
************************************************************************

   These instructions are for users who want to quickly build the 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 operating systems 
   supported by CMake.

   NOTE: CMake is being introduced in this release on an early-access basis.
         While we have attempted to provide error-free files, please understand 
         that this development with CMake has just begun; the CMake-specific 
         files may change before the next release.


========================================================================
                            Preconditions
========================================================================

   1. We suggest you obtain the latest CMake for windows from the Kitware
      web site. The HDF5 1.8.x product requires CMake version 2.8.1 or later.

   2. If you plan to use Zlib or Szip, 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.


========================================================================
          Building HDF5 C/C++ Libraries with CMake
========================================================================

   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. It is recommemded that you 
      choose a build directory different from 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). 

   2. Configure the cache settings.

      Click the Configure button. 

      If this is the first time cmake-gui has been run 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. 

      The first time you click Configure, CMake displays the default settings; 
      since nothing has yet been confirmed, they will all be displayed in red.  

      Review these settings, changing them as appropriate for your environment.

      After each configure you can adjust the cache settings and/or specify 
      locations of other programs.

      Click Configure a second time.  

      Each time you click configure, any new values and any conflicts detected 
      by CMake will be highlighted in red.  

      Review and change the settings as appropriate, and click configure again.

      Repeat this review-change-click, review-change-click cycle until you are 
      happy with all the settings and there are no more values in red.

      Then, and only then, 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.

   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.


   4. Test HDF5.

      To test the build, navigate to your build directory and execute the
      following:

              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.

   The files that support building HDF5 with CMake are all the files in the 
   Resources folder, the CMakeLists.txt files in each source folder, and two 
   additional files, ConfigureChecks.cmake and CTestConfig.cmake. The 
   distributed copy of CTestConfig.cmake is specific to the internal 
   testing performed by The HDF Group; it should be altered for the user's 
   installation and needs.

   More information about using CMake can be found at the KitWare site, 
   www.cmake.org.


************************************************************************

Need further assistance, send email to help@hdfgroup.org.

