[svn-r24672] Update document with ctest script changes.

This commit is contained in:
Allen Byrne 2014-01-31 13:15:02 -05:00
parent a3e2fabb53
commit 0a2ed24d0f

View File

@ -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")
## 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")
####################################################
# extra CDash build name description
set(SITE_BUILDNAME_SUFFIX "STATIC")
# needed for source updates, change as required
##### 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")
############################################
# 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\"")
#### 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")
############################################
# include common script file
include(${CTEST_SCRIPT_DIRECTORY}/CTestScript.cmake)
message("DONE")
========================================================================
For further assistance, send email to help@hdfgroup.org