diff options
Diffstat (limited to 'release_docs/INSTALL_CMake.txt')
| -rw-r--r-- | release_docs/INSTALL_CMake.txt | 313 |
1 files changed, 198 insertions, 115 deletions
diff --git a/release_docs/INSTALL_CMake.txt b/release_docs/INSTALL_CMake.txt index d431644..438d7e2 100644 --- a/release_docs/INSTALL_CMake.txt +++ b/release_docs/INSTALL_CMake.txt @@ -4,23 +4,76 @@ Table of Contents -Section I: Quick Step Building HDF5 Libraries with CMake -Section II: Preconditions -Section III: Building HDF5 C/C++ Libraries with CMake -Section IV: All Options for HDF5 C/C++ Libraries with CMake -Section V: User Defined Options for HDF5 Libraries with CMake -Section VI: APPENDIX +Section I: Quick Step Building HDF5 Libraries with CMake Script Mode +Section II: Quick Step Building HDF5 Libraries with CMake Command Mode +Section III: Preconditions +Section IV: Building HDF5 C/C++ Libraries with CMake +Section V: All Options for HDF5 C/C++ Libraries with CMake +Section VI: User Defined Options for HDF5 Libraries with CMake +Section VII: APPENDIX ************************************************************************ ======================================================================== -I. Quick Step Building HDF5 Libraries with CMake +I. Quick Step Building HDF5 Libraries with CMake Script Mode +======================================================================== +This short set of instructions is written for users who want to quickly +build the HDF5 Library and tools from the HDF5 source code package +using the CMake tools. HDF Group recommends using a ctest script to build +HDF5. + +To build HDF5 with the SZIP and ZLIB external libraries you will need to: + + 1. Create a directory for your development; myhdfstuff. + + 2. Create a directory for the HDF5 source; hdf5-1.8 in myhdfstuff. + + 3. Download the SZip.tar.gz and ZLib.tar.gz to your development directory, + (See Section VII: APPENDIX for instructions). Both are needed if + building with external libraries; do not uncompress them. + + 4. Download or create the CTestScript.cmake file in your development + directory, (See Section VII: APPENDIX for instructions and an example). + + 5. Download or create a platform configuration file in your development + directory, (See Section VII: APPENDIX for instructions and an example). + This file calls CTestScript.cmake; the platform configuration file can + be modified. CTestScript.cmake file should not be modified. + + 6. From your development directory execute the CTest Script with the + following options: + + ctest -S <configuration file>,<hdf5src> -C RelWithDebInfo -VV -O hdf5.log + + 7. This will create an install package in the myhdfstuff/hdf5-1.8/build folder. + + Where: + "configuration file" is the platform configuration file from step6; + HDF518WindowsRWDICMake.cmake, HDF518LinuxRWDICMake.cmake, or + HDF518MacRWDICMake.cmake can be downloaded from the HDF Group website. + "hdf5src" is the uncompressed HDF5 source code directory. No path + should be specified. + + The -S option uses the script version of ctest. + + The value for the -C option (as shown above, "-C RelWithDebInfo") must + match the setting for CTEST_BUILD_CONFIGURATION in the platform + configuration file. + + The -VV option is for verbose; Use -V for less verbose. + + The "-O hdf5.log" option saves the output to a log file hdf5.log. + + + +======================================================================== +II. Quick Step Building HDF5 Libraries with CMake ======================================================================== Notes: This short set of instructions is written for users who want to quickly build the HDF5 Library and tools from the HDF5 source code - package using the CMake tools. + package using the CMake command line tools. A. Windows Quick Step Building HDF5 Libraries with CMake Using VS2010 @@ -37,6 +90,7 @@ Notes: This short set of instructions is written for users who want to 4. Configure the C library, tools and tests with this command: cmake -G "Visual Studio 10" -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON .. + The two dots on the end of the command is the location of the source. 5. Build the C library, tools and tests with this command: cmake --build . --config Release @@ -55,16 +109,17 @@ Notes: This short set of instructions is written for users who want to Go through these steps: 1. Locate the source files in: - ~\MyHDFstuff\hdf5 + ~/MyHDFstuff/hdf5 2. Create a build folder at: - ~\MyHDFstuff\hdf5\build + ~/MyHDFstuff/hdf5/build 3. Open a command prompt at: - ~\MyHDFstuff\hdf5\build + ~/MyHDFstuff/hdf5/build 4. Configure the C library, tools and tests with this command: cmake -G "Unix Makefiles" -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON .. + The two dots on the end of the command is the location of the source. 5. Build the C library, tools and tests with this command: cmake --build . --config Release @@ -82,14 +137,14 @@ Notes: This short set of instructions is written for users who want to ======================================================================== -II. Preconditions +III. 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 2.8.10. 2. If you plan to use Zlib or Szip: - A. Download the packages and install them in a central location. + A. Download the binary packages and install them in a central location. For example on Windows, create a folder extlibs and install the packages there. B. Use source packages from an SVN server by adding the following CMake @@ -121,7 +176,7 @@ II. Preconditions Visual Studio Express users will not be able to package HDF5 into an install image executable. - 5. Developers should copy the config/cmake/cacheinit.cmake file and alter the + 5. Developers can copy the config/cmake/cacheinit.cmake file and alter the the settings for the developers' environment. Then the only options needed on the command line are those options that are different. Example using HDF default cache file: @@ -162,7 +217,7 @@ Notes: CMake in General ======================================================================== -III. Building HDF5 C/C++ Libraries with CMake +IV. Building HDF5 C/C++ Libraries with CMake ======================================================================== To build the HDF5 C/C++ Libraries with CMake, go through these five steps: @@ -192,7 +247,7 @@ These five steps are described in detail below. then use c:\MyHDFstuff\hdf5\build or c:\MyHDFstuff\build\hdf5 as the build directory. - PREFERRED: + RECOMMENDED: 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 @@ -389,7 +444,7 @@ These five steps are described in detail below. ======================================================================== -IV. All Options for HDF5 C/C++ Libraries with CMake +V. All Options for HDF5 C/C++ Libraries with CMake ======================================================================== In the options listed below, there are three columns of information: @@ -465,7 +520,7 @@ ENDIF (WINDOWS) ======================================================================== -V. User Defined Options for HDF5 Libraries with CMake +VI. User Defined Options for HDF5 Libraries with CMake ======================================================================== Support for User Defined macros and options has been added. The file @@ -478,7 +533,7 @@ UserMacros.cmake file. Then enable the option to the CMake configuration, build and test process. ======================================================================== -VI. APPENDIX +VII. APPENDIX ======================================================================== Below are examples of the ctest scripts used by The HDF Group. @@ -552,7 +607,7 @@ else(NOT SITE_OS_NAME) endif(CMAKE_HOST_UNIX) if(SITE_BUILDNAME_SUFFIX) set(CTEST_BUILD_NAME ${CTEST_BUILD_NAME}-${SITE_BUILDNAME_SUFFIX}) - endif() + endif(SITE_BUILDNAME_SUFFIX) set(BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DSITE:STRING=${CTEST_SITE} -DBUILDNAME:STRING=${CTEST_BUILD_NAME}") endif(NOT SITE_OS_NAME) @@ -563,10 +618,16 @@ if(APPLE) # Compiler choice execute_process(COMMAND xcrun --find cc OUTPUT_VARIABLE XCODE_CC OUTPUT_STRIP_TRAILING_WHITESPACE) execute_process(COMMAND xcrun --find c++ OUTPUT_VARIABLE XCODE_CXX OUTPUT_STRIP_TRAILING_WHITESPACE) - SET(ENV{CC} "${XCODE_CC}") - SET(ENV{CXX} "${XCODE_CXX}") - # Shared fortran is not supported, build static - set (BUILD_OPTIONS "${BUILD_OPTIONS} -DBUILD_SHARED_LIBS:BOOL=OFF -DCMAKE_ANSI_CFLAGS:STRING=-fPIC") + set(ENV{CC} "${XCODE_CC}") + set(ENV{CXX} "${XCODE_CXX}") + + if(NOT NO_MAC_FORTRAN) + # Shared fortran is not supported, build static + set(BUILD_OPTIONS "${BUILD_OPTIONS} -DBUILD_SHARED_LIBS:BOOL=OFF -DCMAKE_ANSI_CFLAGS:STRING=-fPIC") + else(NOT NO_MAC_FORTRAN) + set(BUILD_OPTIONS "${BUILD_OPTIONS} -DHDF5_BUILD_FORTRAN:BOOL=OFF") + endif(NOT NO_MAC_FORTRAN) + set(BUILD_OPTIONS "${BUILD_OPTIONS} -DCTEST_USE_LAUNCHERS:BOOL=ON -DCMAKE_BUILD_WITH_INSTALL_RPATH:BOOL=OFF") endif(APPLE) @@ -583,7 +644,7 @@ endif(NOT SITE_CYGWIN}) #----------------------------------------------------------------------------- set(NEED_REPOSITORY_CHECKOUT 0) set(CTEST_CMAKE_COMMAND "\"${CMAKE_COMMAND}\"") -if (CTEST_USE_TAR_SOURCE) +if(CTEST_USE_TAR_SOURCE) ## Uncompress source if tar file provided ## -------------------------- if(WIN32) @@ -603,20 +664,20 @@ if (CTEST_USE_TAR_SOURCE) file(RENAME ${CTEST_USE_TAR_SOURCE} ${CTEST_SOURCE_DIRECTORY}) set(LOCAL_SKIP_UPDATE "TRUE") -else (CTEST_USE_TAR_SOURCE) +else(CTEST_USE_TAR_SOURCE) ## use subversion to get source ## -------------------------- - if (NOT EXISTS "${CTEST_SOURCE_DIRECTORY}") - set (NEED_REPOSITORY_CHECKOUT 1) - endif (NOT EXISTS "${CTEST_SOURCE_DIRECTORY}") + if(NOT EXISTS "${CTEST_SOURCE_DIRECTORY}") + set(NEED_REPOSITORY_CHECKOUT 1) + endif(NOT EXISTS "${CTEST_SOURCE_DIRECTORY}") - if (${NEED_REPOSITORY_CHECKOUT}) - set (CTEST_CHECKOUT_COMMAND + if(${NEED_REPOSITORY_CHECKOUT}) + set(CTEST_CHECKOUT_COMMAND "${CTEST_UPDATE_COMMAND} co ${REPOSITORY_URL} \"${CTEST_SOURCE_DIRECTORY}\" -r HEAD") - else (${NEED_REPOSITORY_CHECKOUT}) - set (CTEST_CHECKOUT_COMMAND "${CTEST_UPDATE_COMMAND} update") - endif (${NEED_REPOSITORY_CHECKOUT}) -endif (CTEST_USE_TAR_SOURCE) + else(${NEED_REPOSITORY_CHECKOUT}) + set(CTEST_CHECKOUT_COMMAND "${CTEST_UPDATE_COMMAND} update") + endif(${NEED_REPOSITORY_CHECKOUT}) +endif(CTEST_USE_TAR_SOURCE) #----------------------------------------------------------------------------- ## Clear the build directory @@ -718,62 +779,69 @@ endforeach(v) message("Dashboard script configuration:\n${vars}\n") #----------------------------------------------------------------------------- -## NORMAL process -## -- LOCAL_UPDATE updates the source folder from svn -## -- LOCAL_SUBMIT reports to CDash server -## -- LOCAL_SKIP_TEST skips the test process (only builds) -## -- LOCAL_MEMCHECK_TEST executes the Valgrind testing -## -- LOCAL_COVERAGE_TEST executes code coverage process -## -------------------------- -CTEST_START (${MODEL} TRACK ${MODEL}) -if(LOCAL_UPDATE) - CTEST_UPDATE (SOURCE "${CTEST_SOURCE_DIRECTORY}") -endif(LOCAL_UPDATE) -CTEST_CONFIGURE (BUILD "${CTEST_BINARY_DIRECTORY}") -CTEST_READ_CUSTOM_FILES ("${CTEST_BINARY_DIRECTORY}") -if(LOCAL_SUBMIT) - CTEST_SUBMIT (PARTS Update Configure Notes) -endif(LOCAL_SUBMIT) - CTEST_BUILD (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND) -if(LOCAL_SUBMIT) - CTEST_SUBMIT (PARTS Build) -endif(LOCAL_SUBMIT) -if(NOT LOCAL_SKIP_TEST) - if(NOT LOCAL_MEMCHECK_TEST) - CTEST_TEST (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND ${ctest_test_args}) - if(LOCAL_SUBMIT) - CTEST_SUBMIT (PARTS Test) - endif(LOCAL_SUBMIT) - else(NOT LOCAL_MEMCHECK_TEST) - CTEST_MEMCHECK (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND ${ctest_test_args}) - if(LOCAL_SUBMIT) - CTEST_SUBMIT (PARTS MemCheck) - endif(LOCAL_SUBMIT) - endif(NOT LOCAL_MEMCHECK_TEST) - if(LOCAL_COVERAGE_TEST) - CTEST_COVERAGE (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND) - if(LOCAL_SUBMIT) - CTEST_SUBMIT (PARTS Coverage) - endif(LOCAL_SUBMIT) - endif(LOCAL_COVERAGE_TEST) -endif(NOT LOCAL_SKIP_TEST) -if(NOT LOCAL_MEMCHECK_TEST) - ##----------------------------------------------- - ## Package the product - ##----------------------------------------------- - execute_process(COMMAND cpack -C ${CTEST_BUILD_CONFIGURATION} -V - WORKING_DIRECTORY ${CTEST_BINARY_DIRECTORY} - RESULT_VARIABLE cpackResult - OUTPUT_VARIABLE cpackLog - ERROR_VARIABLE cpackLog.err - ) - file(WRITE ${CTEST_BINARY_DIRECTORY}/cpack.log "${cpackLog.err}" "${cpackLog}") -endif(NOT LOCAL_MEMCHECK_TEST) #----------------------------------------------------------------------------- + ## NORMAL process + ## -- LOCAL_UPDATE updates the source folder from svn + ## -- LOCAL_SUBMIT reports to CDash server + ## -- LOCAL_SKIP_TEST skips the test process (only builds) + ## -- LOCAL_MEMCHECK_TEST executes the Valgrind testing + ## -- LOCAL_COVERAGE_TEST executes code coverage process + ## -------------------------- + CTEST_START (${MODEL} TRACK ${MODEL}) + if(LOCAL_UPDATE) + CTEST_UPDATE (SOURCE "${CTEST_SOURCE_DIRECTORY}") + endif(LOCAL_UPDATE) + CTEST_CONFIGURE (BUILD "${CTEST_BINARY_DIRECTORY}") + CTEST_READ_CUSTOM_FILES ("${CTEST_BINARY_DIRECTORY}") + if(LOCAL_SUBMIT) + CTEST_SUBMIT (PARTS Update Configure Notes) + endif(LOCAL_SUBMIT) + CTEST_BUILD (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND) + if(LOCAL_SUBMIT) + CTEST_SUBMIT (PARTS Build) + endif(LOCAL_SUBMIT) + if(NOT LOCAL_SKIP_TEST) + if(NOT LOCAL_MEMCHECK_TEST) + CTEST_TEST (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND ${ctest_test_args} RETURN_VALUE res) + if(LOCAL_SUBMIT) + CTEST_SUBMIT (PARTS Test) + endif(LOCAL_SUBMIT) + if(res GREATER 0) + message(FATAL_ERROR "Failed tests: ${res}\n") + endif(res GREATER 0) + else(NOT LOCAL_MEMCHECK_TEST) + CTEST_MEMCHECK (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND ${ctest_test_args}) + if(LOCAL_SUBMIT) + CTEST_SUBMIT (PARTS MemCheck) + endif(LOCAL_SUBMIT) + endif(NOT LOCAL_MEMCHECK_TEST) + if(LOCAL_COVERAGE_TEST) + CTEST_COVERAGE (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND) + if(LOCAL_SUBMIT) + CTEST_SUBMIT (PARTS Coverage) + endif(LOCAL_SUBMIT) + endif(LOCAL_COVERAGE_TEST) + endif(NOT LOCAL_SKIP_TEST) + if(NOT LOCAL_MEMCHECK_TEST AND NOT LOCAL_NO_PACKAGE) + ##----------------------------------------------- + ## Package the product + ##----------------------------------------------- + execute_process(COMMAND cpack -C ${CTEST_BUILD_CONFIGURATION} -V + WORKING_DIRECTORY ${CTEST_BINARY_DIRECTORY} + RESULT_VARIABLE cpackResult + OUTPUT_VARIABLE cpackLog + ERROR_VARIABLE cpackLog.err + ) + file(WRITE ${CTEST_BINARY_DIRECTORY}/cpack.log "${cpackLog.err}" "${cpackLog}") + if(cpackResult GREATER 0) + message(FATAL_ERROR "Failed packaging: ${cpackResult}\n") + endif(cpackResult GREATER 0) + endif(NOT LOCAL_MEMCHECK_TEST AND NOT LOCAL_NO_PACKAGE) +#----------------------------------------------------------------------------- + message("DONE:CTestScript") - ======================================================================== ctest ======================================================================== @@ -791,46 +859,61 @@ and the build folder is created as a sub-folder. # "ctest -S HDF518Static.cmake,hdf518 -C Release -O hdf518static.log" # where hdf518 is the source folder relative to the location of these scripts ############################################################################ - cmake_minimum_required(VERSION 2.8.10 FATAL_ERROR) - -# CTEST_SCRIPT_ARG is the source folder passed on the command line -set(CTEST_DASHBOARD_ROOT ${CTEST_SCRIPT_DIRECTORY}) set(CTEST_SOURCE_NAME ${CTEST_SCRIPT_ARG}) -set(CTEST_BINARY_NAME ${CTEST_SOURCE_NAME}/buildstatic) +set(CTEST_BINARY_NAME ${CTEST_SOURCE_NAME}/build) +set(CTEST_DASHBOARD_ROOT "${CTEST_SCRIPT_DIRECTORY}") 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 +####### Following Line is one of [Release, RelWithDebInfo, Debug] ############# +set(CTEST_BUILD_CONFIGURATION "RelWithDebInfo") +######### Following describes computer ############ 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") - -# extra CDash build name description -set(SITE_BUILDNAME_SUFFIX "STATIC") - -# needed for source updates, change as required +## Set the following to unique id your computer ## +set(CTEST_SITE "LINUX.XXXX") +## following is optional to describe build ## +set(SITE_BUILDNAME_SUFFIX "RWDI-SHARED") +#################################################### + +##### Following controls CDash submission ##### +#set(LOCAL_SUBMIT "TRUE") +##### Following controls test process ##### +#set(LOCAL_SKIP_TEST "TRUE") +#set(LOCAL_MEMCHECK_TEST "TRUE") +#set(LOCAL_COVERAGE_TEST "TRUE") +##### Following controls cpack command ##### +set(LOCAL_NO_PACKAGE "TRUE") +##### Following controls source update ##### +#set(LOCAL_UPDATE "TRUE") set(REPOSITORY_URL "http://svn.hdfgroup.uiuc.edu/hdf5/branches/hdf5_1_8") +#uncomment to use a compressed source file *.zip +#set(CTEST_USE_TAR_SOURCE "hdf5-1.8.12") +############################################ + +#### Change default configuration of options in config/cmake/cacheinit.cmake file ### +### uncomment and change the following line for more configuration options +#set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DXXX:XXX=XXX") +### uncomment the following line to build static libraries +#set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DBUILD_SHARED_LIBS:BOOL=OFF") +### ext libs from svn +#set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING=SVN") +### ext libs from tgz for 1.8.12 and after +set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING=TGZ -DTGZPATH:PATH=${CTEST_SCRIPT_DIRECTORY}") +### ext libs from tgz for 1.8.11 and before +#set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS}-DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING=TGZ -DTGZ_PATH:PATH=${CTEST_SCRIPT_DIRECTORY}") +### Create install package with external libraries (szip, zlib) +set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_PACKAGE_EXTLIBS:BOOL=ON") +### disable test program builds +#set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DBUILD_TESTING:BOOL=OFF") +### disable packaging +#set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_NO_PACKAGES:BOOL=ON") +############################################ -# options to add/change from the cacheinit.cmake in the config/cmake folder -set(ADD_BUILD_OPTIONS "-DBUILD_SHARED_LIBS:BOOL=OFF -DCMAKE_INSTALL_PREFIX:PATH=/usr/local/hdf5.1.8_static") -set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DCMAKE_ANSI_CFLAGS:STRING=-fPIC -DHDF5_PACKAGE_EXTLIBS:BOOL=ON") -set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING=\"SVN\"") - -# include common script file include(${CTEST_SCRIPT_DIRECTORY}/CTestScript.cmake) -message("DONE") - - ======================================================================== For further assistance, send email to help@hdfgroup.org |