mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-12-21 07:51:46 +08:00
283 lines
11 KiB
Plaintext
283 lines
11 KiB
Plaintext
************************************************************************
|
|
* Build and Install HDF5 Applications with CMake *
|
|
************************************************************************
|
|
|
|
Notes: This short instruction is written for users who want to quickly
|
|
build HDF5 applications using the CMake tools. Users can adapt
|
|
these instructions for their own applications. For more information,
|
|
see the "Minimum C Project Files for CMake" section.
|
|
|
|
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
|
|
available for the configuration step. The steps are similar for
|
|
all of the operating systems supported by CMake.
|
|
|
|
NOTES:
|
|
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 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.
|
|
|
|
3. See the appendix at the bottom of this file for an example
|
|
of using a ctest script for building and testing. See
|
|
CMake.txt for more information.
|
|
|
|
|
|
|
|
========================================================================
|
|
I. Preconditions
|
|
========================================================================
|
|
|
|
1. We suggest you obtain the latest CMake for windows from the Kitware
|
|
web site. The HDF5 1.8.x product requires a minimum CMake version
|
|
of 2.8.12.
|
|
|
|
2. You have installed the HDF5 library built with CMake, by executing
|
|
the HDF Install Utility (the *.exe file in the binary package for
|
|
Windows). If you are using a Windows platform, you can obtain a
|
|
pre-built Windows binary from The HDF Group's website at
|
|
www.hdfgroup.org.
|
|
|
|
3. Set the environment variable HDF5_DIR to the installed location of
|
|
the config files for HDF5. On Windows:
|
|
HDF5_DIR=C:/Program Files/HDF_Group/HDF5/1.8.x/cmake/hdf5
|
|
|
|
(Note there are no quote characters used on Windows and all platforms
|
|
use forward slashes)
|
|
|
|
4. Created separate source and build directories.
|
|
(CMake commands are executed in the build directory)
|
|
|
|
5. Created a CMakeLists.txt file(s) for your source. See Section III
|
|
below.
|
|
|
|
|
|
|
|
========================================================================
|
|
II. Building HDF5 Applications with CMake
|
|
========================================================================
|
|
|
|
Go through these steps to build HDF5 applications with CMake.
|
|
|
|
1. Run CMake
|
|
2. Configure the cache settings
|
|
3. Build HDF5 Applications
|
|
4. Test HDF5 Applications.
|
|
|
|
These steps are described in more 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 for the build directory.
|
|
|
|
PREFERRED:
|
|
Users can perform the configuration step without using the visual
|
|
cmake-gui program. The following is an example command line
|
|
configuration step executed within the build directory:
|
|
|
|
cmake -G "<generator>" [-D<options>] <sourcepath>
|
|
|
|
Where <generator> is
|
|
* Borland Makefiles
|
|
* MSYS Makefiles
|
|
* MinGW Makefiles
|
|
* NMake Makefiles
|
|
* Unix Makefiles
|
|
* Visual Studio 11
|
|
* Visual Studio 11 Win64
|
|
* 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:
|
|
* BUILD_TESTING:BOOL=ON
|
|
* USE_SHARED_LIBS:BOOL=[ON | OFF]
|
|
|
|
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 10).
|
|
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.
|
|
|
|
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 Alternative command line example on Windows in c:\MyHDFstuff\hdf5\build directory:
|
|
|
|
cmake -G "Visual Studio 10" -DBUILD_TESTING:BOOL=ON -DUSE_SHARED_LIBS:BOOL=ON ..
|
|
|
|
3. Build HDF5 Applications
|
|
|
|
On Windows, you can build HDF5 applications using either the Visual Studio Environment
|
|
or the command line. The command line is normally 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. If you are
|
|
using the pre-built binaries from HDF, use Release.
|
|
|
|
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 Applications
|
|
|
|
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. The files that support building with CMake are all of 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.
|
|
|
|
|
|
|
|
========================================================================
|
|
III. Minimum C Project Files for CMake
|
|
========================================================================
|
|
|
|
6. Create a CMakeLists.txt file at the source root. Include the
|
|
following text in the file:
|
|
|
|
##########################################################
|
|
cmake_minimum_required (VERSION 2.8.12)
|
|
PROJECT (HDF5MyApp C CXX)
|
|
|
|
FIND_PACKAGE (HDF5 NAMES hdf5)
|
|
# FIND_PACKAGE (HDF5) # Find non-cmake built HDF5
|
|
INCLUDE_DIRECTORIES (${HDF5_INCLUDE_DIR})
|
|
set (LINK_LIBS ${LINK_LIBS} ${HDF5_LIBRARIES})
|
|
|
|
set (example hdf_example)
|
|
|
|
add_executable (${example} ${PROJECT_SOURCE_DIR}/${example}.c)
|
|
TARGET_C_PROPERTIES (${example} " " " ")
|
|
target_link_libraries (${example} ${LINK_LIBS})
|
|
|
|
ENABLE_TESTING ()
|
|
include (CTest)
|
|
|
|
add_test (NAME test_example COMMAND ${example})
|
|
##########################################################
|
|
|
|
|
|
|
|
========================================================================
|
|
IV. APPENDIX
|
|
========================================================================
|
|
|
|
Below is an example of the ctest script used by The HDF Group. See the
|
|
Appendix in the INSTALL_CMake.txt file for the CTestScript.cmake file used
|
|
by this script. Adjust the values as necessary. Note that the source folder
|
|
is entered on the command line and the build folder is created as a sub-folder.
|
|
Windows should adjust the forward slash to double backslashes, except for
|
|
the HDF_DIR environment variable.
|
|
|
|
NOTE: these files are available at the HDF web site:
|
|
http://www.hdfgroup.org/HDF5/release/cmakebuild.html
|
|
|
|
CTestScript.cmake
|
|
|
|
HDF518ExamplesWindowsbinaryCMake.cmake
|
|
|
|
|
|
|
|
========================================================================
|
|
ctest
|
|
========================================================================
|
|
|
|
############################################################################
|
|
# Product specific script, HDF518Example.cmake, that uses the
|
|
# CTestScript.cmake file (see Appendix in the CMake.txt). Usage:
|
|
# "ctest -S HDF518Example.cmake,hdf518Examples -C Release -O hdf518EX.log"
|
|
# where hdf518Examples is the source folder relative to the location of these scripts
|
|
############################################################################
|
|
|
|
cmake_minimum_required(VERSION 2.8.12 FATAL_ERROR)
|
|
|
|
set(CTEST_DASHBOARD_ROOT ${CTEST_SCRIPT_DIRECTORY})
|
|
set(CTEST_SOURCE_NAME ${CTEST_SCRIPT_ARG})
|
|
set(CTEST_BINARY_NAME ${CTEST_SOURCE_NAME}/build)
|
|
set(CTEST_SOURCE_DIRECTORY "${CTEST_DASHBOARD_ROOT}/${CTEST_SOURCE_NAME}")
|
|
set(CTEST_BINARY_DIRECTORY "${CTEST_DASHBOARD_ROOT}/${CTEST_BINARY_NAME}")
|
|
set(CTEST_BUILD_CONFIGURATION "Release")
|
|
set(MODEL "Experimental")
|
|
|
|
# build generator name, see cmake generator list
|
|
set(CTEST_CMAKE_GENERATOR "Unix Makefiles")
|
|
|
|
# machine description, can be removed on linux
|
|
set(CTEST_SITE "machine.domain")
|
|
set(SITE_OS_NAME "os name")
|
|
set(SITE_OS_VERSION "os version")
|
|
set(SITE_OS_BITS "os size")
|
|
set(SITE_COMPILER_NAME "compiler name")
|
|
set(SITE_COMPILER_VERSION "compiler version")
|
|
|
|
# needed for source updates, change as required
|
|
set(REPOSITORY_URL "http://svn.hdfgroup.uiuc.edu/hdf5-examples/trunk/1_8")
|
|
|
|
set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DCMAKE_INSTALL_PREFIX:PATH=/usr/local/hdf5Examples-1.8")
|
|
|
|
# location of the installed hdf5 (cmake configuration folder)
|
|
set(ENV{HDF5_DIR} "/usr/share/cmake/hdf5")
|
|
|
|
include(${CTEST_SCRIPT_DIRECTORY}/CTestScript.cmake)
|
|
|
|
message("DONE")
|
|
#################################################################################
|
|
|
|
|
|
|
|
========================================================================
|
|
For further assistance, send email to help@hdfgroup.org
|
|
========================================================================
|
|
|
|
|