diff options
author | Vailin Choi <vchoi@hdfgroup.org> | 2013-04-19 15:23:01 (GMT) |
---|---|---|
committer | Vailin Choi <vchoi@hdfgroup.org> | 2013-04-19 15:23:01 (GMT) |
commit | 14d8e1c2b5ecaf2e298984f269094dd5f2bd735f (patch) | |
tree | cc250461294a2c9118b10a95d0459d7314fa5e50 /release_docs | |
parent | 6ee0e05fb94445551840fcb80b9b1c254c736799 (diff) | |
download | hdf5-14d8e1c2b5ecaf2e298984f269094dd5f2bd735f.zip hdf5-14d8e1c2b5ecaf2e298984f269094dd5f2bd735f.tar.gz hdf5-14d8e1c2b5ecaf2e298984f269094dd5f2bd735f.tar.bz2 |
[svn-r23600] Bring revisions #23085 - #23341 from trunk to revise_chunks.
h5committested.
Diffstat (limited to 'release_docs')
-rw-r--r-- | release_docs/CMake.txt | 450 | ||||
-rw-r--r-- | release_docs/INSTALL_Windows.txt | 3 | ||||
-rw-r--r-- | release_docs/INSTALL_parallel | 28 | ||||
-rw-r--r-- | release_docs/RELEASE.txt | 50 | ||||
-rw-r--r-- | release_docs/USING_CMake.txt | 88 | ||||
-rw-r--r-- | release_docs/USING_Windows.txt | 643 |
6 files changed, 566 insertions, 696 deletions
diff --git a/release_docs/CMake.txt b/release_docs/CMake.txt index 1d36e21..81dfb61 100644 --- a/release_docs/CMake.txt +++ b/release_docs/CMake.txt @@ -10,7 +10,7 @@ Notes: This short instruction is written for users who want to quickly build www.cmake.org. CMake uses the command line, however the visual CMake tool is - recommended for the configuration step. The steps are similiar for + recommended for the configuration step. The steps are similar for all the operating systems supported by CMake. NOTES: @@ -25,27 +25,26 @@ Notes: This short instruction is written for users who want to quickly build Please send us any comments on how CMake support can be improved on any system. Visit the KitWare site for more information about CMake. - 3. If you are building HDF5 on Windows, do NOT use or execute any - files from the windows folder. - - 4. Build and test results can be submitted to our CDash server at: + 3. Build and test results can be submitted to our CDash server at: cdash.hdfgroup.uiuc.edu. Please read the HDF and CDash document at: www.hdfgroup.org/CDash/HowToSubmit. + 4. See the appendix at the bottom of this file for examples of using + a ctest script for building and testing. + ======================================================================== 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.6. + web site. The HDF5 1.8.x product requires 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. For example on Windows, create a folder extlibs - and install the packages there. Windows users should also read Section V - in INSTALL_Windows.txt. + and install the packages there. B. Use source packages from a SVN server by adding the following CMake options: HDF5_ALLOW_EXTERNAL_SUPPORT:STRING="SVN" @@ -61,6 +60,15 @@ Notes: This short instruction is written for users who want to quickly build where "some_location" is the URL or full path to the compressed file and ext is the type of compression file. + 3. Building on Apple Darwin platforms should add the following options: + Compiler choice - use xcode by setting the ENV variables of CC and CXX + Shared fortran is not supported, build static: + BUILD_SHARED_LIBS:BOOL=OFF + Additional options: + CMAKE_ANSI_CFLAGS:STRING=-fPIC + CTEST_USE_LAUNCHERS:BOOL=ON + CMAKE_BUILD_WITH_INSTALL_RPATH:BOOL=OFF + ======================================================================== Building HDF5 C/C++ Libraries with CMake @@ -72,8 +80,9 @@ Notes: This short instruction is written for users who want to quickly build 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 then the source directory + Specify the source and build directories. + ***** It is recommemded that you choose a build directory ****** + ***** different then 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). @@ -110,24 +119,46 @@ Notes: This short instruction is written for users who want to quickly build * <HDF5OPTION>:BOOL=[ON | OFF] <cacheinit.cmake> is: - # This is the CMakeCache file. - ######################## - # EXTERNAL cache entries - ######################## - SET (BUILD_SHARED_LIBS ON CACHE BOOL "Build Shared Libraries" FORCE) - SET (BUILD_TESTING ON CACHE BOOL "Build HDF5 Unit Testing" FORCE) - SET (HDF5_BUILD_CPP_LIB ON CACHE BOOL "Build HDF5 C++ Library" FORCE) - SET (HDF5_BUILD_EXAMPLES ON CACHE BOOL "Build HDF5 Library Examples" FORCE) - SET (HDF5_BUILD_FORTRAN ON CACHE BOOL "Build FORTRAN support" FORCE) - SET (HDF5_BUILD_HL_LIB ON CACHE BOOL "Build HIGH Level HDF5 Library" FORCE) - SET (HDF5_BUILD_TOOLS ON CACHE BOOL "Build HDF5 Tools" FORCE) - SET (HDF5_DISABLE_COMPILER_WARNINGS OFF CACHE BOOL "Disable compiler warnings" FORCE) - SET (HDF5_ENABLE_HSIZET ON CACHE BOOL "Enable datasets larger than memory" FORCE) - SET (HDF5_ENABLE_PARALLEL OFF CACHE BOOL "Enable parallel build (requires MPI)" FORCE) - SET (HDF5_ENABLE_SZIP_ENCODING ON CACHE BOOL "Use SZip Encoding" FORCE) - SET (HDF5_ENABLE_SZIP_SUPPORT ON CACHE BOOL "Use SZip Filter" FORCE) - SET (HDF5_ENABLE_Z_LIB_SUPPORT ON CACHE BOOL "Enable Zlib Filters" FORCE) - SET (HDF5_ENABLE_COVERAGE OFF CACHE BOOL "Enable code coverage for Libraries and Programs" FORCE) + # This is the CMakeCache file. + ######################## + # EXTERNAL cache entries + ######################## + SET (BUILD_SHARED_LIBS ON CACHE BOOL "Build Shared Libraries" FORCE) + SET (BUILD_TESTING ON CACHE BOOL "Build HDF5 Unit Testing" FORCE) + SET (HDF_PACKAGE_EXT "" CACHE STRING "Name of HDF package extension" FORCE) + SET (HDF5_BUILD_CPP_LIB ON CACHE BOOL "Build HDF5 C++ Library" FORCE) + SET (HDF5_BUILD_EXAMPLES ON CACHE BOOL "Build HDF5 Library Examples" FORCE) + SET (HDF5_BUILD_FORTRAN ON CACHE BOOL "Build FORTRAN support" FORCE) + SET (HDF5_ENABLE_F2003 OFF CACHE BOOL "Enable FORTRAN 2003 Standard" FORCE) + SET (HDF5_BUILD_HL_LIB ON CACHE BOOL "Build HIGH Level HDF5 Library" FORCE) + SET (HDF5_BUILD_TOOLS ON CACHE BOOL "Build HDF5 Tools" FORCE) + SET (HDF5_BUILD_GENERATORS OFF CACHE BOOL "Build Test Generators" FORCE) + SET (HDF5_ENABLE_Z_LIB_SUPPORT ON CACHE BOOL "Enable Zlib Filters" FORCE) + SET (HDF5_ENABLE_SZIP_SUPPORT ON CACHE BOOL "Use SZip Filter" FORCE) + SET (HDF5_ENABLE_SZIP_ENCODING ON CACHE BOOL "Use SZip Encoding" FORCE) + SET (HDF5_ENABLE_HSIZET ON CACHE BOOL "Enable datasets larger than memory" FORCE) + SET (HDF5_ENABLE_UNSUPPORTED OFF CACHE BOOL "Enable unsupported combinations of configuration options" FORCE) + SET (HDF5_ENABLE_DEPRECATED_SYMBOLS ON CACHE BOOL "Enable deprecated public API symbols" FORCE) + SET (HDF5_ENABLE_DIRECT_VFD OFF CACHE BOOL "Build the Direct I/O Virtual File Driver" FORCE) + SET (HDF5_ENABLE_PARALLEL OFF CACHE BOOL "Enable parallel build (requires MPI)" FORCE) + SET (MPIEXEC_MAX_NUMPROCS "3" CACHE STRING "Minimum number of processes for HDF parallel tests" FORCE) + SET (HDF5_BUILD_PARALLEL_ALL OFF CACHE BOOL "Build Parallel Programs" FORCE) + SET (HDF5_ENABLE_COVERAGE OFF CACHE BOOL "Enable code coverage for Libraries and Programs" FORCE) + SET (HDF5_ENABLE_USING_MEMCHECKER OFF CACHE BOOL "Indicate that a memory checker is used" FORCE) + SET (HDF5_DISABLE_COMPILER_WARNINGS OFF CACHE BOOL "Disable compiler warnings" FORCE) + SET (HDF5_USE_FOLDERS ON CACHE BOOL "Enable folder grouping of projects in IDEs." FORCE) + SET (HDF5_USE_16_API_DEFAULT OFF CACHE BOOL "Use the HDF5 1.6.x API by default" FORCE) + SET (HDF5_USE_18_API_DEFAULT OFF CACHE BOOL "Use the HDF5 1.8.x API by default" FORCE) + SET (HDF5_ENABLE_THREADSAFE OFF CACHE BOOL "(WINDOWS)Enable Threadsafety" FORCE) + SET (HDF5_PACKAGE_EXTLIBS OFF CACHE BOOL "(WINDOWS)CPACK - include external libraries" FORCE) + SET (HDF5_NO_PACKAGES OFF CACHE BOOL "CPACK - Disable packaging" FORCE) + SET (HDF5_ALLOW_EXTERNAL_SUPPORT "NO" CACHE STRING "Allow External Library Building" FORCE) + SET (ZLIB_SVN_URL "http://svn.hdfgroup.uiuc.edu/zlib/trunk" CACHE STRING "Use ZLib from HDF repository" FORCE) + SET (SZIP_SVN_URL "http://svn.hdfgroup.uiuc.edu/szip/trunk" CACHE STRING "Use SZip from HDF repository" FORCE) + SET (ZLIB_TGZ_NAME "ZLib.tar.gz" CACHE STRING "Use ZLib from compressed file" FORCE) + SET (SZIP_TGZ_NAME "SZip.tar.gz" CACHE STRING "Use SZip from compressed file" FORCE) + SET (ZLIB_PACKAGE_NAME "zlib" CACHE STRING "Name of ZLIB package" FORCE) + SET (SZIP_PACKAGE_NAME "szip" CACHE STRING "Name of SZIP package" FORCE) 2. Configure the cache settings @@ -286,7 +317,7 @@ HDF5_STRICT_FORMAT_CHECKS "Whether to perform strict file format checks" OFF HDF5_TEST_VFD "Execute tests with different VFDs" OFF HDF5_USE_16_API_DEFAULT "Use the HDF5 1.6.x API by default" OFF HDF5_USE_18_API_DEFAULT "Use the HDF5 1.8.x API by default" OFF -HDF5_USE_FOLDERS "Do not include CPack Packaging" OFF +HDF5_USE_FOLDERS "Enable folder grouping of projects in IDEs." OFF HDF5_WANT_DATA_ACCURACY "IF data accuracy is guaranteed during data conversions" ON HDF5_WANT_DCONV_EXCEPTION "exception handling functions is checked during data conversions" ON IF (APPLE) @@ -294,7 +325,7 @@ IF (APPLE) IF (CMAKE_BUILD_TYPE MATCHES Debug) HDF5_ENABLE_TRACE "Enable API tracing capability" ON IF (HDF5_TEST_VFD) - HDF5_TEST_FHEAP_VFD "Execute tests with different VFDs" ON + HDF5_TEST_FHEAP_VFD "Execute fheap test with different VFDs" ON IF (WIN32 AND NOT CYGWIN) HDF_LEGACY_NAMING "Use Legacy Names for Libraries and Programs" OFF HDF5_ENABLE_THREADSAFE "Enable Threadsafety" OFF @@ -314,6 +345,365 @@ IF (HDF5_ENABLE_SZIP_SUPPORT) ************************************************************************ + APPENDIX + +Below are examples of the ctest scripts used by The HDF Group. +See the script, cmakehdf5, in the bin folder for a smaller and limited +function shell script version of the following general scripts. +The example is for a linux machine, but the same scripts can be used on +a windows machine by adjusting the CTEST_CMAKE_GENERATOR option in the +product specific script. + +************************************************************************ + +CTestScript.cmake: common ctest script used to build, test and package +======================================================================== + +cmake_minimum_required(VERSION 2.8.6 FATAL_ERROR) +######################################################## +# This dashboard is maintained by The HDF Group +# For any comments please contact cdashhelp@hdfgroup.org +# +######################################################## +# ----------------------------------------------------------- +# -- Get environment +# ----------------------------------------------------------- +if(NOT SITE_OS_NAME) + ## machine name not provided - attempt to discover with uname + ## -- set hostname + ## -------------------------- + find_program(HOSTNAME_CMD NAMES hostname) + exec_program(${HOSTNAME_CMD} ARGS OUTPUT_VARIABLE HOSTNAME) + set(CTEST_SITE "${HOSTNAME}${CTEST_SITE_EXT}") + find_program(UNAME NAMES uname) + macro(getuname name flag) + exec_program("${UNAME}" ARGS "${flag}" OUTPUT_VARIABLE "${name}") + endmacro(getuname) + + getuname(osname -s) + getuname(osrel -r) + getuname(cpu -m) + message("Dashboard script uname output: ${osname}-${osrel}-${cpu}\n") + + set(CTEST_BUILD_NAME "${osname}-${osrel}-${cpu}") + if(USE_AUTOTOOLS) + set(CTEST_BUILD_NAME "AT-${CTEST_BUILD_NAME}") + endif(USE_AUTOTOOLS) + if(SITE_BUILDNAME_SUFFIX) + set(CTEST_BUILD_NAME "${CTEST_BUILD_NAME}-${SITE_BUILDNAME_SUFFIX}") + endif(SITE_BUILDNAME_SUFFIX) + set(BUILD_OPTIONS "${ADD_BUILD_OPTIONS}") +else(NOT SITE_OS_NAME) + ## machine name provided + ## -------------------------- + if(CMAKE_HOST_UNIX) + set(CTEST_BUILD_NAME "${SITE_OS_NAME}-${SITE_OS_VERSION}-${SITE_OS_BITS}-${SITE_COMPILER_NAME}-${SITE_COMPILER_VERSION}") + else(CMAKE_HOST_UNIX) + set(CTEST_BUILD_NAME "${SITE_OS_NAME}-${SITE_OS_VERSION}-${SITE_COMPILER_NAME}") + endif(CMAKE_HOST_UNIX) + if(SITE_BUILDNAME_SUFFIX) + set(CTEST_BUILD_NAME ${CTEST_BUILD_NAME}-${SITE_BUILDNAME_SUFFIX}) + endif() + set(BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DSITE:STRING=${CTEST_SITE} -DBUILDNAME:STRING=${CTEST_BUILD_NAME}") +endif(NOT SITE_OS_NAME) + +#----------------------------------------------------------------------------- +# MAC machines need special option +#----------------------------------------------------------------------------- +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(BUILD_OPTIONS "${BUILD_OPTIONS} -DCTEST_USE_LAUNCHERS:BOOL=ON -DCMAKE_BUILD_WITH_INSTALL_RPATH:BOOL=OFF") +endif(APPLE) + +#----------------------------------------------------------------------------- +## cygwin does not handle the find_package() call +## -------------------------- +if(NOT SITE_CYGWIN}) + find_package (Subversion) + set(CTEST_UPDATE_COMMAND "${Subversion_SVN_EXECUTABLE}") +else(NOT SITE_CYGWIN}) + set(CTEST_UPDATE_COMMAND "/usr/bin/svn") +endif(NOT SITE_CYGWIN}) + +#----------------------------------------------------------------------------- +set(NEED_REPOSITORY_CHECKOUT 0) +set(CTEST_CMAKE_COMMAND "\"${CMAKE_COMMAND}\"") +if (CTEST_USE_TAR_SOURCE) + ## Uncompress source if tar file provided + ## -------------------------- + if(WIN32) + set(CTEST_7Z_COMMAND "C:/Program Files/7-Zip/7z.exe") + message("extracting... [${CTEST_7Z_COMMAND} x ${CTEST_USE_TAR_SOURCE}.zip]") + execute_process(COMMAND ${CTEST_7Z_COMMAND} x ${CTEST_USE_TAR_SOURCE}.zip RESULT_VARIABLE rv) + else(WIN32) + message("extracting... [${CTEST_CMAKE_COMMAND} -E tar -xvf ${CTEST_USE_TAR_SOURCE}.tar]") + execute_process(COMMAND tar -xvf ${CTEST_USE_TAR_SOURCE}.tar RESULT_VARIABLE rv) + endif(WIN32) + + if(NOT rv EQUAL 0) + message("extracting... [error-(${rv}) clean up]") + file(REMOVE_RECURSE "${CTEST_SOURCE_DIRECTORY}") + message(FATAL_ERROR "error: extract of ${CTEST_USE_TAR_SOURCE} failed") + endif(NOT rv EQUAL 0) + + file(RENAME ${CTEST_USE_TAR_SOURCE} ${CTEST_SOURCE_DIRECTORY}) + set(LOCAL_SKIP_UPDATE "TRUE") +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 (${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) + +#----------------------------------------------------------------------------- +## Clear the build directory +## -------------------------- +set(CTEST_START_WITH_EMPTY_BINARY_DIRECTORY TRUE) +file(MAKE_DIRECTORY "${CTEST_BINARY_DIRECTORY}") +#include(${CTEST_SOURCE_DIRECTORY}/CTestConfig.cmake) +ctest_empty_binary_directory(${CTEST_BINARY_DIRECTORY}) + +# Use multiple CPU cores to build +include(ProcessorCount) +ProcessorCount(N) +if(NOT N EQUAL 0) + if(NOT WIN32) + set(CTEST_BUILD_FLAGS -j${N}) + endif(NOT WIN32) + set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N}) +endif() + +#----------------------------------------------------------------------------- +# Send the main script as a note. +if(USE_AUTOTOOLS) + ## autotools builds need to use make and does not use the cacheinit.cmake file + ## -- make command + ## ----------------- + find_program(MAKE NAMES make) + + list(APPEND CTEST_NOTES_FILES + "${CTEST_SCRIPT_DIRECTORY}/${CTEST_SCRIPT_NAME}" + "${CMAKE_CURRENT_LIST_FILE}" + ) +else(USE_AUTOTOOLS) + list(APPEND CTEST_NOTES_FILES + "${CTEST_SCRIPT_DIRECTORY}/${CTEST_SCRIPT_NAME}" + "${CMAKE_CURRENT_LIST_FILE}" + "${CTEST_SOURCE_DIRECTORY}/config/cmake/cacheinit.cmake" + ) +endif(USE_AUTOTOOLS) + +#----------------------------------------------------------------------------- +# Check for required variables. +# -------------------------- +foreach(req + CTEST_CMAKE_GENERATOR + CTEST_SITE + CTEST_BUILD_NAME + ) + if(NOT DEFINED ${req}) + message(FATAL_ERROR "The containing script must set ${req}") + endif(NOT DEFINED ${req}) +endforeach(req) + +#----------------------------------------------------------------------------- +# Initialize the CTEST commands +#------------------------------ +if(USE_AUTOTOOLS) + set(CTEST_CONFIGURE_COMMAND "${CTEST_SOURCE_DIRECTORY}/configure ${ADD_BUILD_OPTIONS}") + set(CTEST_BUILD_COMMAND "${MAKE} ${CTEST_BUILD_FLAGS}") + ## -- CTest Config + #configure_file($ENV{HOME}/CTestConfiguration/CTestConfig.cmake ${CTEST_SOURCE_DIRECTORY}/CTestConfig.cmake) + configure_file(${CTEST_SOURCE_DIRECTORY}/config/cmake/CTestCustom.cmake ${CTEST_BINARY_DIRECTORY}/CTestCustom.cmake) + ## -- CTest Testfile +# configure_file(${CTEST_SCRIPT_DIRECTORY}/CTestTestfile.cmake ${CTEST_BINARY_DIRECTORY}/CTestTestfile.cmake) + file(WRITE ${CTEST_BINARY_DIRECTORY}/CTestTestfile.cmake "ADD_TEST(makecheck \"${MAKE}\" \"${CTEST_BUILD_FLAGS}\" \"-i\" \"check\")") +else(USE_AUTOTOOLS) + if(LOCAL_MEMCHECK_TEST) + find_program(CTEST_MEMORYCHECK_COMMAND NAMES valgrind) + set (CTEST_CONFIGURE_COMMAND + "${CTEST_CMAKE_COMMAND} -C \"${CTEST_SOURCE_DIRECTORY}/config/cmake/mccacheinit.cmake\" -DCMAKE_BUILD_TYPE:STRING=${CTEST_BUILD_CONFIGURATION} ${BUILD_OPTIONS} \"-G${CTEST_CMAKE_GENERATOR}\" \"${CTEST_SOURCE_DIRECTORY}\"" + ) + else(LOCAL_MEMCHECK_TEST) + find_program(CTEST_COVERAGE_COMMAND NAMES gcov) + set (CTEST_CONFIGURE_COMMAND + "${CTEST_CMAKE_COMMAND} -C \"${CTEST_SOURCE_DIRECTORY}/config/cmake/cacheinit.cmake\" -DCMAKE_BUILD_TYPE:STRING=${CTEST_BUILD_CONFIGURATION} ${BUILD_OPTIONS} \"-G${CTEST_CMAKE_GENERATOR}\" \"${CTEST_SOURCE_DIRECTORY}\"" + ) + endif(LOCAL_MEMCHECK_TEST) +endif(USE_AUTOTOOLS) + +#----------------------------------------------------------------------------- +## -- set output to english +set($ENV{LC_MESSAGES} "en_EN") + +# Print summary information. +foreach(v + CTEST_SITE + CTEST_BUILD_NAME + CTEST_SOURCE_DIRECTORY + CTEST_BINARY_DIRECTORY + CTEST_CMAKE_GENERATOR + CTEST_BUILD_CONFIGURATION + CTEST_GIT_COMMAND + CTEST_CHECKOUT_COMMAND + CTEST_CONFIGURE_COMMAND + CTEST_SCRIPT_DIRECTORY + CTEST_USE_LAUNCHERS + ) + set(vars "${vars} ${v}=[${${v}}]\n") +endforeach(v) +message("Dashboard script configuration:\n${vars}\n") + +#----------------------------------------------------------------------------- +if(${MODEL} STREQUAL "Continuous") + ## Continuous mode is used for commit test processing + ## -------------------------- + while (${CTEST_ELAPSED_TIME} LESS 36000) + set(START_TIME ${CTEST_ELAPSED_TIME}) + CTEST_START (Continuous) + CTEST_UPDATE (SOURCE "${CTEST_SOURCE_DIRECTORY}" RETURN_VALUE res) + set (CTEST_CHECKOUT_COMMAND) # checkout on first iteration only + message("Dashboard updated files: ${res}\n") + if(res GREATER 0) + CTEST_CONFIGURE (BUILD "${CTEST_BINARY_DIRECTORY}") + CTEST_READ_CUSTOM_FILES ("${CTEST_BINARY_DIRECTORY}") + CTEST_SUBMIT (PARTS Update Configure Notes) + CTEST_BUILD (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND) + CTEST_SUBMIT (PARTS Build) + CTEST_TEST (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND ${ctest_test_args}) + CTEST_SUBMIT (PARTS Test) + + execute_process (COMMAND cpack -C ${CTEST_BUILD_CONFIGURATION} + 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(${res} GREATER 0) + + CTEST_SLEEP(${START_TIME} 300 ${CTEST_ELAPSED_TIME}) + endwhile (${CTEST_ELAPSED_TIME} LESS 36000) +#----------------------------------------------------------------------------- +else(${MODEL} STREQUAL "Continuous") +#----------------------------------------------------------------------------- + ## NORMAL process + ## -- LOCAL_SKIP_UPDATE skips updating the source folder from svn + ## -- LOCAL_NO_SUBMIT skips reporting 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(NOT LOCAL_SKIP_UPDATE) + CTEST_UPDATE (SOURCE "${CTEST_SOURCE_DIRECTORY}") + endif(NOT LOCAL_SKIP_UPDATE) + CTEST_CONFIGURE (BUILD "${CTEST_BINARY_DIRECTORY}") + CTEST_READ_CUSTOM_FILES ("${CTEST_BINARY_DIRECTORY}") + if(NOT LOCAL_NO_SUBMIT) + CTEST_SUBMIT (PARTS Update Configure Notes) + endif(NOT LOCAL_NO_SUBMIT) + CTEST_BUILD (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND) + if(NOT LOCAL_NO_SUBMIT) + CTEST_SUBMIT (PARTS Build) + endif(NOT LOCAL_NO_SUBMIT) + if(NOT LOCAL_SKIP_TEST) + if(NOT LOCAL_MEMCHECK_TEST) + CTEST_TEST (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND ${ctest_test_args}) + if(NOT LOCAL_NO_SUBMIT) + CTEST_SUBMIT (PARTS Test) + endif(NOT LOCAL_NO_SUBMIT) + else(NOT LOCAL_MEMCHECK_TEST) + CTEST_MEMCHECK (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND ${ctest_test_args}) + if(NOT LOCAL_NO_SUBMIT) + CTEST_SUBMIT (PARTS MemCheck) + endif(NOT LOCAL_NO_SUBMIT) + endif(NOT LOCAL_MEMCHECK_TEST) + if(LOCAL_COVERAGE_TEST) + CTEST_COVERAGE (BUILD "${CTEST_BINARY_DIRECTORY}" APPEND) + if(NOT LOCAL_NO_SUBMIT) + CTEST_SUBMIT (PARTS Coverage) + endif(NOT LOCAL_NO_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) +endif(${MODEL} STREQUAL "Continuous") +#----------------------------------------------------------------------------- + +message("DONE:CTestScript") +************************************************************************ + +************************************************************************ +Product specific script, HDF518Static.cmake, that uses the +CTestScript.cmake file (see above). Usage: +"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.6 FATAL_ERROR) + +# CTEST_SCRIPT_ARG is the source folder passed on the command line +set(CTEST_SOURCE_NAME ${CTEST_SCRIPT_ARG}) +set(CTEST_BINARY_NAME ${CTEST_SOURCE_NAME}/buildstatic) +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 +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(REPOSITORY_URL "http://svn.hdfgroup.uiuc.edu/hdf5/branches/hdf5_1_8") + +# 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") + +************************************************************************ Need further assistance, send email to help@hdfgroup.org diff --git a/release_docs/INSTALL_Windows.txt b/release_docs/INSTALL_Windows.txt index 967675f..4344ea4 100644 --- a/release_docs/INSTALL_Windows.txt +++ b/release_docs/INSTALL_Windows.txt @@ -9,8 +9,5 @@ We now recommend that users build, test and install HDF5 using CMake. Instructions for building and testing HDF5 using CMake can be found in the CMake.txt file found in this folder. -The old solutions and projects found in the windows\ folder will be -maintained for legacy users until HDF5 1.10. - The old INSTALL_Windows documentation can be found in the obsolete_windows_docs\ folder located with this document. diff --git a/release_docs/INSTALL_parallel b/release_docs/INSTALL_parallel index b2e1eec..eacaf68 100644 --- a/release_docs/INSTALL_parallel +++ b/release_docs/INSTALL_parallel @@ -17,12 +17,14 @@ of running the parallel test suites. 1.1. Requirements ----------------- -PHDF5 requires an MPI compiler with MPI-IO support and a parallel file system. -If you don't know yet, you should first consult with your system support staff -of information how to compile an MPI program, how to run an MPI application, -and how to access the parallel file system. There are sample MPI-IO C and -Fortran programs in the appendix section of "Sample programs". You can use -them to run simple tests of your MPI compilers and the parallel file system. +PHDF5 requires an MPI compiler with MPI-IO support and a POSIX compliant +(Ref. 1) parallel file system. If you don't know yet, you should first consult +with your system support staff of information how to compile an MPI program, +how to run an MPI application, and how to access the parallel file system. +There are sample MPI-IO C and Fortran programs in the appendix section of +"Sample programs". You can use them to run simple tests of your MPI compilers +and the parallel file system. Also, the t_posix_compliant test in testpar +verifies if the file system is POSIX compliant. 1.2. Further Help @@ -274,6 +276,20 @@ if the tests should use directory /PFS/user/me, do shell initial files like .profile, .cshrc, etc.) +Reference +--------- +1. POSIX Compliant. A good explanation is by Donald Lewin, + After a write() to a regular file has successfully returned, any + successful read() from each byte position on the file that was modified + by that write() will return the date that was written by the write(). A + subsequent write() to the same byte will overwrite the file data. If a + read() of a file data can be proven by any means [e.g., MPI_Barrier()] + to occur after a write() of that data, it must reflect that write(), + even if the calls are made by a different process. + Lewin, D. (1994). "POSIX Programmer's Guide (pg. 513-4)". O'Reilly + & Associates. + + Appendix A. Sample programs --------------------------- Here are sample MPI-IO C and Fortran programs. You may use them to run simple diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt index 4742542..d2901ab 100644 --- a/release_docs/RELEASE.txt +++ b/release_docs/RELEASE.txt @@ -1,4 +1,4 @@ -HDF5 version 1.9.137-FA_a5 currently under development +HDF5 version 1.9.148-FA_a5 currently under development INTRODUCTION @@ -40,6 +40,10 @@ New Features Configuration: ------------- + - CMake minimum is now 2.8.10. (ADB 2013/1/14) + - A new tool, cmakehdf5, which is a build command script similar to + buildhdf5 is added and is available in the bin directory. + (AKC - 2012/12/12) - Fixed AIX Fortran compiler flags to use appropriate settings for debugging, profiling, optimization situations. HDFFV-8069. (AKC 2012/09/27) @@ -101,6 +105,9 @@ New Features Library: -------- + - Added new API functions H5Dscatter and H5Dgather to scatter data to and + and gather data from a selection within a memory buffer. + (NAF - 2013/02/05) - The library now supports the data conversion from enumeration to numeric (integer and floating-point number) datatypes. See Issue 8221. (SLU - 2012/10/23) @@ -363,9 +370,9 @@ New Features High-Level APIs: ------ - Table: In version 3.0 of Table, "NROWS" (used to store number of records) was - deprecated (PVN - 2008/11/24) + deprecated (PVN - 2008/11/24) - - Added Fortran wrappers for Dimension Scale APIs. HDFFV-3797 + - Added Fortran wrappers for Dimension Scale APIs. HDFFV-3797 h5dsset_scale_f h5dsattach_scale_f h5dsdetach_scale_f @@ -378,9 +385,15 @@ New Features (EIP for SB - 2011/10/13) - New API: h5ltpath_valid (Fortran: h5ltpath_valid_f) which checks - if a path is correct and determines if a link resolves to a valid - object and checks that the link does not dangle. (MSB- 2012/3/15) - + if a path is correct and determines if a link resolves to a valid + object and checks that the link does not dangle. (MSB- 2012/3/15) + + - A new API function H5DOwrite_chunk. It writes a data chunk directly + into a file bypassing hyperslab selection, data conversion, and + filter pipeline. The user must be careful with the function and + clearly understand the I/O process of the library. + (SLU - 2013/2/11) + Documentation ------------- @@ -737,9 +750,12 @@ Bug Fixes since HDF5-1.8.0 release Tools ----- + - h5diff: Fixed to return correct exit code 1 when detect unique extra + attribute. Prior to this fix, h5diff returned exit code 0 indicating + two files are identical. HDFFV-7643 (JKM 2013/02/15) - h5diff: Improved speed when comparing HDF5 files with lots of - attributes. Much slower performance was identified with release version - from 1.8.7 to 1.8.10 compared to 1.8.6. (JKM 2012/10/19) + attributes. Much slower performance was identified with release + version from 1.8.7 to 1.8.10 compared to 1.8.6. (JKM 2012/10/19) - h5repack: "h5repack -f NONE file1.h5 out.h5" command failed if source file contains chunked dataset and a chunk dim is bigger than the dataset dim. Another issue is that the command changed max dims @@ -967,7 +983,10 @@ Bug Fixes since HDF5-1.8.0 release High-Level APIs: ------ - + - Fixed problem with H5DSget_scale_name including the NULL terminator in + the size calculation returned by the function. The API does not + include the NULL terminator in the size returned (MSB- 2013/2/10) + - Fixed problem with H5TBdelete_record destroying all data following the deletion of a row. (MSB- 2012/7/26) @@ -1051,6 +1070,19 @@ Bug Fixes since HDF5-1.8.0 release in "New Features" section. (BMR - 2008/08/10) + Testing + ------- + - In some Mac system, testlibinfo.sh failed with this error: + Check file ../src/.libs/libhdf5.7.dylib + strings: object: ../src/.libs/libhdf5.7.dylib malformed object \ + (unknown load command 15) + The strings command of Mac inspects library files and older + versions of strings may not know newer library format, resulting + in errors. Fixed by sending the library file as stdin to the strings + coommand to avoid this problem. (AKC - 2013/03/08 HDFFV-8305) + + - Fixed a typo in the ERROR macro in test/testhdf5.h. It segmentation + faulted when used before. (AKC - 2013/02/12 HDFFV-8267) Supported Platforms diff --git a/release_docs/USING_CMake.txt b/release_docs/USING_CMake.txt index 71f2fcf..0e980ea 100644 --- a/release_docs/USING_CMake.txt +++ b/release_docs/USING_CMake.txt @@ -4,14 +4,14 @@ Notes: This short instruction is written for users who want to quickly build HDF5 Applications from the HDF5 Examples package using the CMake tools. - Users can adapt these instructions for their own applicaltions, see the + Users can adapt these instructions for their own applications, see the "Minimum Project Files" 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 similiar for + available for the configuration step. The steps are similar for all the operating systems supported by CMake. NOTES: @@ -31,13 +31,17 @@ Notes: This short instruction is written for users who want to quickly build Please read the HDF and CDash document at: www.hdfgroup.org/CDash/HowToSubmit. + 4. 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. + ======================================================================== 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.6 (minimum). + web site. The HDF5 1.8.x product requires CMake version 2.8.10 (minimum). 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). @@ -62,7 +66,7 @@ Notes: This short instruction is written for users who want to quickly build 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 + Specify the source and build directories. It is recommended that you choose a build directory different then 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). @@ -156,7 +160,7 @@ Notes: This short instruction is written for users who want to quickly build ======================================================================== - Using HDF5 Libraries with Visual Studio 2008 + Using Visual Studio 2008 with HDF5 Libraries built with Visual Studio 2008 ======================================================================== 8. Set up path for external libraries and headers @@ -168,11 +172,11 @@ Notes: This short instruction is written for users who want to quickly build and select "x64". 8.2 Find the box "Show directories for", choose "Include files", add the - header path (i.e. c:\Program Files\HDF Group\HDF5\hdf5-1.8.7\include) + header path (i.e. c:\Program Files\HDF Group\HDF5\hdf5-1.8.x\include) to the included directories. 8.3 Find the box "Show directories for", choose "Library files", add the - library path (i.e. c:\Program Files\HDF Group\HDF5\hdf5-1.8.7\lib) + library path (i.e. c:\Program Files\HDF Group\HDF5\hdf5-1.8.x\lib) to the library directories. 8.4 If using Fortran libraries, you will also need to setup the path @@ -180,12 +184,30 @@ Notes: This short instruction is written for users who want to quickly build ======================================================================== + Using Visual Studio 2010 with HDF5 Libraries built with Visual Studio 2010 +======================================================================== + + 9. Set up path for external libraries and headers + + The path settings will need to be in project property sheets per project. + Go to "Project" and select "Properties", find "Configuration Properties", + and then "VC++ Directories". + + 9.1 If you are building on 64-bit Windows, find the "Platform" dropdown + and select "x64". + + 9.2 Add the header path to the "Include Directories" setting. + + 9.3 Add the library path to the "Library Directories" setting. + + +======================================================================== Minimum C Project Files for CMake ======================================================================== - 9. Create a CMakeLists.txt file at the source root. + 10. Create a CMakeLists.txt file at the source root. .......................................................................... -cmake_minimum_required (VERSION 2.8.6) +cmake_minimum_required (VERSION 2.8.10) PROJECT (HDF5MyApp C CXX) FIND_PACKAGE (HDF5 REQURIED) @@ -196,7 +218,55 @@ ADD_EXECUTABLE (hdf_example ${PROJECT_SOURCE_DIR}/hdf_example.c) TARGET_LINK_LIBRARIES (hdf_example ${LINK_LIBS}) .......................................................................... + +************************************************************************ + APPENDIX + +Below ia an example of the ctest script used by The HDF Group. See the +Appendix in the CMake.txt file for the CTestScript.cmake file used by this +script. + ************************************************************************ +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.6 FATAL_ERROR) + +set(CTEST_SOURCE_NAME ${CTEST_SCRIPT_ARG}) +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 +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") + Need further assistance, send email to help@hdfgroup.org diff --git a/release_docs/USING_Windows.txt b/release_docs/USING_Windows.txt index 9afbeb1..97ac4ad 100644 --- a/release_docs/USING_Windows.txt +++ b/release_docs/USING_Windows.txt @@ -4,626 +4,10 @@ * (Full Version) * *********************************************************************** -The following instructions assume that the HDF5 binary code package from -HDF website (http://hdfgroup.org) is used. +We now recommend that users build, test and install HDF5 using CMake. -Warnings: -Please read CAREFULLY about the following preconditions and notes first. - -Contents: - - Section : Preconditions and Notes - Section I : What do we provide? - Section II : How to build examples (optional) - Section III : How to build an application using the HDF5 library or DLL - Section IV : How to build HDF5 for 64-bit Windows - Section V : How to build HDF5 applications using Visual Studio 2010 - Section VI : Misc. - - -======================================================================== - Preconditions and Notes -======================================================================== - -Preconditions: - - 1. Installed Microsoft Visual Studio. This document is written for Visual - Studio 2008. Express Editions may work with the project files - but not from the command line. We do not support the Express Editions. - - 2. (Optional) Installed Intel Compiler 10.1 or 11.1 if you want to use HDF5 - Fortran libraries. - - 3. Install Winzip or 7-zip for extracting source tarball. - - Note: 1. 7zip is an open-source alternative to WinZip. Some of the - advanced functionality is disabled in WinZip unless you buy the - software. With 7zip, most of this functionality is included for - free. - - 5. Set up a directory structure to unpack the library. For example: - - c:\ (any drive) - MyHDFstuff\ (any folder name) - - 6. Download the hdf5-1.8.x binary code package and use 7zip or WinZip to - extract the HDF5 package into c:\MyHDFstuff. This creates a directory - called 'hdf5-1.8.x' under MyHDFstuff which contains several files and - directories. Rename "hdf5-1.8.x" to "hdf5". - - 7. HDF5 provide options to do in-memory compression within HDF5 library. - Currently, two external compression libraries Zlib and Szip can be used - with HDF5. - - 7.1 HDF5 uses Zlib version 1.2.5 for compression and Zlib is - distributed with HDF5 library in 1.8.x release. - - 7.2 HDF5 uses Szip version 2.1 for compression and Szip compression - software is provided with HDF5 products in 1.8.x release. - - Please note that Szip is not a totally open-source free software. - For licensing issue of Szip, please check "Licensing terms" at - http://hdfgroup.org/doc_resource/SZIP/index.html. - - Szip compression feature inside HDF5 is enabled by default. - - 8. Define the following environment variables: - - HDF5_EXT_ZLIB - HDF5_EXT_SZIP - - In this section, Zlib and Szip compression packages are assumed to be - used. Please read Section V as well as this section if you do not want - to use compression feature inside HDF5. - - To define these environment variables: - - Click "Start", click "Control Panel", and then double-click "System". - On the "Advanced" tab, click "Environment Variables". - - If you are logged on as administrator to the local computer AND want to - let all other users use these two environment variables, click "New" - under "System Variables" box; otherwise, click "New" under "User - Variables" box. - - In the New Variable window, set "Variable name" as HDF5_EXT_ZLIB and - "Variable value" as zlib.lib, then click OK. - - Similarly, you can set: - - HDF5_EXT_SZIP environment variable as szip.lib - - Notes: - - a. You will have to close and reopen running programs for the new - environment variable settings to take effect. - - b. c:\zlib\zlib.dll and c:\szip\dll\szip.dll should be copied - into a location that the application can find. - - 9. Set up path for libraries and headers - - Invoke Microsoft Visual Studio and go to "Tools" and select "Options", - find "Projects", and then "VC++ Directories". - - 9.1 If you are building on 64-bit Windows, find the "Platform" dropdown - and select "x64". - - 9.2 Find the box "Show directories for", choose "Include files", if you - can not find your HDF5 header path (for example, - c:\MyHDFstuff\include) from the directory list, add the - header path (c:\MyHDFstuff\include) to the included - directories. - - 9.3 Find the box "Show directories for", choose "Library files". If you - cannot find your HDF5 library path (for example, - c:\MyHDFstuff\dll for dynamic-shared and c:\MyHDFstuff\lib for static) - from the directory list, add the library - path (c:\MyHDFstuff\dll or c:\MyHDFstuff\lib) to the library directories. - - 9.4 If building Fortran applications, you will also need to setup the path - for the Intel Fortran compiler. Please see Section VI. - - NOTE: - If you are using VS2010, the path settings will need to be in project - property sheets per project. Go to "Project" and select "Properties", find - "Configuration Properties", and then "VC++ Directories". - - 9.1 If you are building on 64-bit Windows, find the "Platform" dropdown - and select "x64". - 9.2 Add the header path to the "Include Directories" setting. - 9.3 Add the library path to the "Library Directories" setting. - -Notes: - - 1. HDF4-related tools are not built and released with HDF5 library packages - any more. To obtain HDF4 related tools, please check - http://hdfgroup.org/h4toh5/ and ftp://ftp.hdfgroup.org/HDF5/h4toh5 - - 2. For Fortran users, Intel Fortran Compiler 10.1 is currently supported - -- please see Section VI. Intel Compiler 11.1 can be used but the project files - must be upgraded within the Visual Studio IDE. - - 3. The szip and zlib dlls must be in the PATH for using the tools (including static). - - -======================================================================== - Section I: What do we provide? -======================================================================== - - 1. Provide - - HDF5 static library: - release version - - HDF5 Dynamic Link Library(DLL): - release version as well as export libraries for DLL - - HDF5 High-Level Library (Optional): - HDF5 C++ Library - HDF5 HL-Fortran Library - - HDF5 tools: - HDF5 tools - - HDF5 tool library: - release version - - HDF5 tool export library for DLL: - release version - - 2. Examples (Included in the binary distribution as a zip file) - - Unpack the examples, hdf5-examples.zip, into your "hdf5" folder - (c:\MyHDFstuff\hdf5). - The resulting structure under this folder should be: - c++ - c++/examples - examples - fortran - fortran/examples - hl - hl/c++ - hl/c++/examples - hl/examples - hl/fortran - hl/fortran/examples - windows - windows/c++ - windows/c++/examples - windows/examples - windows/fortran - windows/fortran/examples - windows/hl - windows/hl/examples - windows/hl/fortran - windows/hl/fortran/examples - hdf5build_examples.bat - InstallExamples.bat - - HDF5 examples: - Simple HDF5 C/C++/Fortran and High level C/Fortran examples - -======================================================================== - Section II: How To Build Examples (Optional) -======================================================================== - -Simple examples have been provided for users to test HDF5 C/C++/Fortran and -High level C/Fortran library and tools. - -Note: - 1) To build HDF5 C++ examples, HDF5 C++ library must have been installed in - Step I. - - 2) To build HDF5 Fortran or HL Fortran examples, please see Section VI, - Step 3. - - 3) To build HDF5 High Level C examples, HDF5 High level library must have - been installed in step I. - - 4) By default, the HDF5 binary distribution only includes the release - versions of HDF5 C/C++ libraries and DLLs. - -To build and test HDF5 C examples: ----------------------------------- - 1. Invoke Microsoft Visual Studio, go to "File" and select the "Open - Solution" option. - - Then open the solution - c:\MyHDFstuff\hdf5examples\windows\examples\allexamples\allexamples.sln. - - 2. Select "Build", and "Configuration Manager". - - To build release versions of C examples. - - In "Active Solution Configuration", select "Release". Select "Close". - Select "Build" -> "Build Solution" or "Rebuild Solution" to build - release version of project "allexamples". - - When the release build is done, there should be the following - subdirectories in c:\MyHDFstuff\hdf5examples\examples\ - - attributetest - attributetestdll - chunkread - chunkreaddll - compoundtest - compoundtestdll - extendwritetest - extendwritetestdll - grouptest - grouptestdll - readtest - readtestdll - selectest - selectestdll - writetest - writetestdll - - 3. Invoke a command prompt window and run the batch file InstallExamples.bat - which resides in the top level directory (c:\MyHDFstuff\hdf5examples). This file - creates new directories, examplesREL, examplesRELDLL in the - c:\MyHDFstuff\hdf5examples\examples directory and places - all the executables in it. - - 4. We provide a batch file named testExamples.bat and an expected examples - tests output file named testExamples_exp_output.txt in - c:\MyHDFstuff\hdf5\examples directory for you to test HDF5 C examples. - - testExamples.bat batch file has options: - - testExamples release -- for release version - - testExamples release dll -- for release DLL version - - Invoke a command prompt and run testExamples.bat with appropriate options. - You should get "All HDF5 C examples tests passed." when the C examples are - built successfully. Otherwise, the difference between the expected - outputs and actual outputs will be given. - -To build and test HDF5 C++ examples: ------------------------------------- - - 1. Invoke Microsoft Visual Studio, go to "File" and select the "Open - Solution" option. - - Then open the solution - c:\MyHDFstuff\hdf5examples\windows\examples\allexamples\allcppexamples.sln. - - 2. Select "Build", and "Configuration Manager". - - To build release versions of C examples. - - In "Active Solution Configuration", select "Release". Select "Close". - Select "Build" -> "Build Solution" or "Rebuild Solution" to build - release version of project "allcppexamples". - - When the release build is done, there should be the following - subdirectories in c:\MyHDFstuff\hdf5examples\c++\examples\ - - chunks - chunksdll - compound - compounddll - create - createdll - extend_ds - extend_dsll - h5group - h5groupdll - readdata - readdatadll - writedata - writedatadll - - 3. Invoke a command prompt window and run the batch file - InstallcppExamples.bat which resides in the top level directory - (c:\MyHDFstuff\hdf5examples). This file creates new directories, - cppexamplesREL, cppexamplesRELDLL in the - c:\MyHDFstuff\hdf5examples\c++\examples directory and places all - the executables in it. - - 4. We provide a batch file named testcppExamples.bat in - c:\MyHDFstuff\hdf5examples\c++\examples directory for you to test HDF5 C++ - examples. - - testcppExamples.bat batch file has options: - - testcppExamples release -- for release version - - testcppExamples release dll -- for release DLL version - - Invoke a command prompt and run testcppExamples.bat with appropriate - options. You should get "All HDF5 C++ examples tests passed." when the - C++ examples are built successfully. Otherwise, the difference between - the expected outputs and actual outputs will be given. - - -To build and test HDF5 High Level C examples: ---------------------------------------------- - - 1. Invoke Microsoft Visual Studio, go to "File" and select the "Open - Solution" option. - - Then open the solution - c:\MyHDFstuff\hdf5examples\windows\hl\examples\allhlcexamples\allhlcexamples.sln - - 2. Select "Build", and "Configuration Manager". - - To build release versions of C examples. - - In "Active Solution Configuration", select "Release". Select "Close". - Select "Build" -> "Build Solution" or "Rebuild Solution" to build - release version of project "allhlcexamples". - - When the release build is done, binaries will be built in the - following subdirectories of c:\MyHDFstuff\hdf5\examples\ - - ex_image[1-2](dll) - ex_lite1(dll) - ex_table[01-12](dll) - ex_ds1(dll) - ptExample[FL+VL](dll) - - 3. Invoke a command prompt and run the batch file Install_hlcexamples.bat - which resides in the top level directory (c:\MyHDFstuff\hdf5examples). This file - creates new directories, HLCexamplesRELEASE, HLCexamplesRELEASEDLL in the - c:\MyHDFstuff\hdf5examples\hl\examples directory and places all the executables in - it. - - 4. We provide a batch file named test_hl_cexamples.bat in - c:\MyHDFstuff\hdf5examples\hl\examples directory for you to test HDF5 high level C - examples. - - test_hl_cexamples.bat batch file has options: - - Options purpose - - test_hl_cexamples release -- for release version - - test_hl_cexamples release dll -- for release DLL version - - Invoke a command prompt window and run test_hl_cexamples with - appropriate options. - - Invoke a command prompt and run testExamples.bat with appropriate options. - You should get "All of the HL C Examples Passed!" when the HL C examples - are built successfully. Otherwise, the difference between the expected - outputs and actual outputs will be given. - - -======================================================================== - Section III: Building an application using the HDF5 library or DLL -======================================================================== - -Waring: The instructions below will only describe how to build an application - using the release version of the HDF5 library or DLL. To use the debug - version of the HDF5 library or DLL, you need to substitute the release - version of the HDF5 library or DLL with the debug version. - - -To build an application that uses the HDF5 static library the following -locations will need to be specified for locating header files and linking with -the HDF static library, for example: - -c:\MyHDFstuff\hdf5\hdf5lib\release\include -c:\MyHDFstuff\hdf5\hdf5lib\release\lib - -We assume that you will use Zlib and Szip compression with HDF5 library. - -1. Specifying Include Directories - -To specify the include directories in the settings for your Visual Studio -project, you may choose one of the following two methods. - - Method One: Project-wide Settings - - 1. Open your project in Microsoft Visual Studio and make sure it is the - active project. - - 2. Go to the Project menu and chose the "Properties" option. - - 3. Choose the build configuration you would like to modify in the drop - down menu labeled "Configuration:" - - 4. Choose the "C/C++" tab, and select "General". - - 5. In a text-area labeled with "Additional Include Directories:", add - HDF5, Zlib, and Szip header files directories. For example: - - c:\MyHDFstuff\hdf5\hdf5lib\release\include - c:\zlib\include - c:\szip\include - - Then click OK. - - 6. (Optional) To use HDF5 Fortran static library, the location of - Fortran module files should be specified by following Project-> - Settings->Fortran->Preprocessor, and in the text-area labeled - "Additional Include Directories", add HDF5 Fortran module files - directories. For example: - - c:\MyHDFstuff\hdf5\hdf5lib\release\include - - Method Two: Visual Studio Settings - - 1. In Visual STudio, go to Tools->Options->Projects-> - VC++ Directories. Under "Show Directories For", select "Include files" - - 2. Insert the correct HDF5, Zlib, Szip paths for headers(include). For - example, - - c:\MyHDFstuff\hdf5\hdf5lib\release\include - c:\zlib\include - c:\szip\include - - -2. Specifying Library Directories - -To specify the library directories in the settings for your Visual Studio -project, you may choose one of the following two methods. - - Method One: Project-wide Settings - - 1. Open your project in Microsoft Visual Studio and make sure it is the - active project. - - 2. Go to the Project menu and chose the "Properties" option. - - 3. Choose the build configuration you would like to modify in the drop - down menu labeled "Configuration:" - - 4. Choose the "Linker" tab, and select "General". - - 5. In a text-area labeled with "Additional Library Directories:", add - HDF5, Zlib, and Szip library files directories. For example: - - c:\MyHDFstuff\hdf5\hdf5lib\release\lib - c:\zlib\dll - c:\szip\dll - - Note: To link with HDF5 DLLs rathern that static libraries, simply - specify the "dll" directory rather than "lib", and link with the - corresponding DLL link library below. - - Then click OK. - - - Method Two: Visual Studio Settings - - 1. In Visual STudio, go to Tools->Options->Projects-> - VC++ Directories. Under "Show Directories For", select "Library files" - - 2. Insert the correct HDF5, Zlib, Szip paths for link libraries. For - example, - - c:\MyHDFstuff\hdf5\hdf5lib\release\lib - c:\zlib\dll - c:\szip\dll - - Note: To link with HDF5 DLLs rathern that static libraries, simply - specify the "dll" directory rather than "lib", and link with the - corresponding DLL link library below. - - -3. Specifying Libraries to Link - - To link the HDF5 static library with your application: - - 1. In Visual Studio, go to the Project menu and choose "Properties". - - 2. Find the "Link" option and "Input" category. In the "Additional - Dependencies" field, insert "zlib.lib, libszip.lib, hdf5.lib". - - 3. (Optional) Also insert "hdf5_cpp.lib" if you want to use HDF5 C++ - static library. - - 4. (Optional) Also insert "hdf5_fortran.lib" if you want to use HDF5 - Fortran static library. - - 5. (Optional) Also insert "hdf5_hl.lib" if you want to use HDF5 high - level static library. - - 6. (Optional) Also insert "hdf5_hl_cpp.lib" if you want to use HDF5 High - Level C++ static library. - - 7. (Optional) Also insert "hdf5_hl_fortran.lib" if you want to use HDF5 - High Level Fortran static library. - - - To link the HDF5 DLL library with your application: - - 1. Follow the steps for linking the HDF5 static library as shown above, - except now link the export library that is created with the DLL. - - The export library is called hdf5dll.lib for HDF5 C libray, - hdf5_cppdll.lib for HDF5 C++ library, and hdf5_fortrandll.lib - for HDF5 Fortran library. - - 2. In the Project Properties dialog, go to the C/C++ > Preprocessor - subsection. In the "Preprocessor Definitions" box, add "_HDF5USEDLL_" - to the list. - - 3. (Optional) Also add HDF5CPP_USEDLL to use HDF5 C++ DLL. - - 4. (Optional) Also add _HDF5USEHLDLL_ to use HDF5 high level DLL. - - 5. (Optional) Also add HDF5USE_HLCPPDLL use HDF5 high level C++ DLL. - - 6. (Optional) Follow Project->Settings->Fortran->Category->General-> - Predefined Preprocess or Symbols, and add "HDF5F90_WINDOWS" to use HDF5 - Fortran DLL. - - 7. Place the DLLs in a location that Windows will be able to locate. The - searched path and order for DLL's is - - a) The directory where the executable module for the current - process is located. - b) The current directory. - c} The Windows system directory. The GetSystemDirectory function - retrieves the path of this directory. - d) The Windows directory. The GetWindowsDirectory function - retrieves the path of this directory. - e) The directories listed in the PATH environment variable. - - -======================================================================== - Section IV: How to build HDF5 for 64-bit Windows -======================================================================== - -HDF5 is available for 64-bit Windows in Visual Studio 2008. - -Prerequisites: - - 1. A 64-bit Windows machine. - - 2. Microsoft Visual Studio 2008 installed with x64 Extensions. - - -Building: - - Building 64-bit Windows binaries is very similar to the process for 32-bit. - Therefore, you may follow the instructions in Section II with the following - modifications. - - 1. The x64 platform must be selected in the build configuration for - debug and release versions. Before building, go to "Build", - "Configuration Manager". In the "Active solution platform" box, - select "x64", and press "Close". - - 2. 64-bit HDF5 applications must be built with 64-bit external libraries. - You must add the include and - library paths for x64 configurations as you have in the - "Prerequisites" section. This is also true for Intel Fortran if - Fortran libraries are to be built. - -======================================================================== - Section V: How to build HDF5 applications using Visual Studio 2010 -======================================================================== -Building with Visual Studio 2010 is very similar to building with Visual Studio -2008, with some minor changes. Therefore, follow the build instructions above, -with the following considerations: - - 1. Visual Studio 2010 uses a new format for project files, but Visual Studio - 2008 project files can be converted. The HDF5 project files - will need to be converted on first use. To do so: - - 1.1. Open the HDF5 Visual Studio 2008 solution file as in Section II - (all.sln) - - NOTE. Intel Fortran 11.1 currently does not integrate with Visual Studio 2010. - - 1.2. You will be prompted with an automatic conversion wizard. Click - through, accepting the default values. You may choose to create - backups of the project files, although it isn't necessary. - - 1.3. When it is finished, it should state that all projects were - converted successfully with no errors. Warnings can be ignored. - - 2. Once the project files have been converted you will need to create project - property sheets for the library and include paths. Then build and test normally. - Note that the converted project files aren't backwards compatible with - previous versions of Visual Studio. +Instructions for building and testing HDF5 applications using CMake can be found in +the USING_CMake.txt file found in this folder. ======================================================================== @@ -635,26 +19,7 @@ with the following considerations: Here are some helpful notes if you are not familiar with using the Visual C++ Development Environment. - 1.1 Project name and location issues: - - It is recommended that you use the given directory structure for building - HDF5 Examples. However, it is possible to create your own structure. If you must - install all.sln and all.vcproj in another directory, relative to hdf5 - directory, you will be asked to locate the sub-project files, when you open - the project all.sln. - - If you want to rename "all" (the entire project), you will need to modify - two files all.sln and all.vcproj as text (contrary to the explicit warnings - in the files). - - - 1.2 Settings... details: - - If you create your own project, the necessary settings can be read - from the all.vcproj file (as text), or from the Project Settings in the - Visual Studio project settings dialog. - - 1.3 FAQ + 1.1 FAQ Many other common questions and hints are located online and being updated in the HDF5 FAQ. For Windows-specific questions, please see: |