diff options
Diffstat (limited to 'release_docs/USING_HDF5_CMake.txt')
-rw-r--r-- | release_docs/USING_HDF5_CMake.txt | 279 |
1 files changed, 279 insertions, 0 deletions
diff --git a/release_docs/USING_HDF5_CMake.txt b/release_docs/USING_HDF5_CMake.txt new file mode 100644 index 0000000..2b3c02b --- /dev/null +++ b/release_docs/USING_HDF5_CMake.txt @@ -0,0 +1,279 @@ +************************************************************************ +* 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.10. + + 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 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. + + OPTIONAL: + 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 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. + + 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 9 2008" -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.10) +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_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. + + + +======================================================================== +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.10 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") + +# skip submit to cdash +set(LOCAL_NO_SUBMIT "True") +# skip update source from repository +set(LOCAL_SKIP_UPDATE "True") + +# 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 +======================================================================== + + |