[svn-r23649] Correct file reference in pack list

Rename and update CMake docs.

1 files changed, 279 insertions, 0 deletions

diff --git a/release_docs/USING_HDF5_CMake.txt b/release_docs/USING_HDF5_CMake.txt
new file mode 100644
index 0000000..2b3c02b
--- /dev/null
+++ b/release_docs/USING_HDF5_CMake.txt
@@ -0,0 +1,279 @@
+************************************************************************
+* Build and Install HDF5 Applications with CMake                       *
+************************************************************************
+
+Notes: This short instruction is written for users who want to quickly 
+       build HDF5 applications using the CMake tools. Users can adapt 
+       these instructions for their own applications. For more information, 
+       see the "Minimum C Project Files for CMake" section.
+       
+       More information about using CMake can be found at the KitWare 
+       site, www.cmake.org.
+         
+       CMake uses the command line; however, the visual CMake tool is 
+       available for the configuration step. The steps are similar for
+       all of the operating systems supported by CMake.
+       
+       NOTES:
+         1. Using CMake for building and using HDF5 is under active 
+            development. While we have attempted to provide error-free 
+            files, please understand that development with CMake has not 
+            been extensively tested outside of HDF. The CMake specific 
+            files may change before the next release.
+            
+         2. CMake for HDF5 development should be usable on any system 
+            where CMake is supported. Please send us any comments on how 
+            CMake support can be improved on any system. 
+            
+         3. See the appendix at the bottom of this file for an example 
+            of using a ctest script for building and testing. See 
+            CMake.txt for more information.
+
+
+
+========================================================================
+I. Preconditions                                                           
+========================================================================
+
+   1. We suggest you obtain the latest CMake for windows from the Kitware
+      web site. The HDF5 1.8.x product requires a minimum CMake version 
+      of 2.8.10.                     
+                                                                         
+   2. You have installed the HDF5 library built with CMake, by executing 
+      the HDF Install Utility (the *.exe file in the binary package for 
+      Windows). If you are using a Windows platform, you can obtain a 
+      pre-built Windows binary from The HDF Group's website at 
+      www.hdfgroup.org.
+
+   3. Set the environment variable HDF5_DIR to the installed location of 
+      the config files for HDF5. On Windows: 
+            HDF5_DIR=C:/Program Files/HDF_Group/HDF5/1.8.x/cmake/hdf5
+      
+      (Note there are no quote characters used on Windows and all platforms
+      use forward slashes)
+
+   4. Created separate source and build directories.
+      (CMake commands are executed in the build directory)
+
+   5. Created a CMakeLists.txt file(s) for your source. See Section III 
+      below.
+
+
+
+========================================================================
+II. Building HDF5 Applications with CMake
+========================================================================
+
+Go through these steps to build HDF5 applications with CMake.
+
+   1. Run CMake
+   2. Configure the cache settings
+   3. Build HDF5 Applications
+   4. Test HDF5 Applications.
+
+These steps are described in more detail below.
+
+
+
+   1. Run CMake
+
+      The CMake executable is named "cmake-gui.exe" on Windows and should be
+      available in your Start menu. For Linux, UNIX, and Mac users the
+      executable is named "cmake-gui" and can be found where CMake was 
+      installed. 
+      
+      Specify the source and build directories. Make the build and source 
+      directories different. For example on Windows, if the source is at 
+      c:\MyHDFstuff\hdf5, then use c:\MyHDFstuff\hdf5\build or 
+      c:\MyHDFstuff\build\hdf5 for the build directory. 
+      
+      OPTIONAL:
+        Users can perform the configuration step without using the visual 
+        cmake-gui program. The following is an example command line 
+        configuration step executed within the build directory:
+        
+        cmake -G "<generator>"  [-D<options>]  <sourcepath>
+        
+        Where <generator> is    
+            * Borland Makefiles
+            * MSYS Makefiles
+            * MinGW Makefiles
+            * NMake Makefiles
+            * Unix Makefiles
+            * Visual Studio 11
+            * Visual Studio 11 Win64
+            * Visual Studio 10
+            * Visual Studio 10 Win64
+            * Visual Studio 6
+            * Visual Studio 7
+            * Visual Studio 7 .NET 2003
+            * Visual Studio 8 2005
+            * Visual Studio 8 2005 Win64
+            * Visual Studio 9 2008
+            * Visual Studio 9 2008 Win64
+
+        <options> is:
+            * BUILD_TESTING:BOOL=ON
+            * USE_SHARED_LIBS:BOOL=[ON | OFF]
+
+   2. Configure the cache settings
+
+      2.1  Click the Configure button. If this is the first time you are 
+           running cmake-gui in this directory, you will be prompted for the 
+           generator you wish to use (for example on Windows, Visual Studio 9 2008). 
+           CMake will read in the CMakeLists.txt files from the source directory and 
+           display options for the HDF5 project. After the first configure you 
+           can adjust the cache settings and/or specify locations of other programs.
+      
+           Any conflicts or new values will be highlighted by the configure
+           process in red. Once you are happy with all the settings and there are no 
+           more values in red, click the Generate button to produce the appropriate 
+           build files. 
+      
+           On Windows, if you are using a Visual Studio generator, the solution and 
+           project files will be created in the build folder.
+      
+           On linux, if you are using the Unix Makefiles generator, the Makefiles will
+           be created in the build folder.
+
+      2.2  Alternative command line example on Windows in c:\MyHDFstuff\hdf5\build directory:
+      
+           cmake -G "Visual Studio 9 2008" -DBUILD_TESTING:BOOL=ON -DUSE_SHARED_LIBS:BOOL=ON ..
+
+   3. Build HDF5 Applications
+   
+      On Windows, you can build HDF5 applications using either the Visual Studio Environment 
+      or the command line. The command line is normally used on linux, Unix, and Mac.
+
+      To build from the command line, navigate to your build directory and
+      execute the following:
+          
+              cmake --build . --config {Debug | Release}     
+              
+      NOTE: "--config {Debug | Release}" may be optional on your platform. We
+            recommend choosing either Debug or Release on Windows. If you are
+            using the pre-built binaries from HDF, use Release.                                                                                     
+             
+      3.1  If you wish to use the Visual Studio environment, open the solution 
+           file in your build directory. Be sure to select either Debug or 
+           Release and build the solution.
+             
+   4. Test HDF5 Applications
+
+      To test the build, navigate to your build directory and execute:
+      
+              ctest . -C {Debug | Release}
+              
+      NOTE: "-C {Debug | Release}" may be optional on your platform. We
+            recommend choosing either Debug or Release to match the build
+            step on Windows.                                                                                      
+
+   5. The files that support building with CMake are all of the files in the 
+      config/cmake folder, the CMakeLists.txt files in each source folder, and 
+      CTestConfig.cmake. CTestConfig.cmake is specific to the internal testing 
+      performed by The HDF Group. It should be altered for the user's 
+      installation and needs. The cacheinit.cmake file settings are used by
+      The HDF Group for daily testing. It should be altered/ignored for the user's 
+      installation and needs. 
+
+
+
+========================================================================
+III. Minimum C Project Files for CMake
+========================================================================
+
+   6. Create a CMakeLists.txt file at the source root. Include the 
+      following text in the file:
+
+##########################################################
+cmake_minimum_required (VERSION 2.8.10)
+PROJECT (HDF5MyApp C CXX)
+
+FIND_PACKAGE (HDF5 NAMES hdf5)
+# FIND_PACKAGE (HDF5) # Find non-cmake built HDF5
+INCLUDE_DIRECTORIES (${HDF5_INCLUDE_DIR})
+SET (LINK_LIBS ${LINK_LIBS} ${HDF5_LIBRARIES})
+
+SET (example hdf_example)
+
+ADD_EXECUTABLE (${example} ${PROJECT_SOURCE_DIR}/${example}.c)
+TARGET_LINK_LIBRARIES (${example} ${LINK_LIBS})
+
+ENABLE_TESTING ()
+INCLUDE (CTest)
+
+ADD_TEST (NAME test_example COMMAND ${example})
+##########################################################
+
+
+
+========================================================================
+IV. APPENDIX
+========================================================================
+
+Below is an example of the ctest script used by The HDF Group. See the
+Appendix in the INSTALL_CMake.txt file for the CTestScript.cmake file used
+by this script. Adjust the values as necessary. Note that the source folder
+is entered on the command line and the build folder is created as a sub-folder.
+Windows should adjust the forward slash to double backslashes, except for
+the HDF_DIR environment variable.
+
+
+
+========================================================================
+ctest
+========================================================================
+
+############################################################################
+# Product specific script, HDF518Example.cmake, that uses the 
+# CTestScript.cmake file (see Appendix in the CMake.txt). Usage:
+# "ctest -S HDF518Example.cmake,hdf518Examples -C Release -O hdf518EX.log"
+# where hdf518Examples is the source folder relative to the location of these scripts
+############################################################################
+
+cmake_minimum_required(VERSION 2.8.10 FATAL_ERROR)
+
+set(CTEST_DASHBOARD_ROOT ${CTEST_SCRIPT_DIRECTORY})
+set(CTEST_SOURCE_NAME ${CTEST_SCRIPT_ARG})
+set(CTEST_BINARY_NAME ${CTEST_SOURCE_NAME}/build)
+set(CTEST_SOURCE_DIRECTORY "${CTEST_DASHBOARD_ROOT}/${CTEST_SOURCE_NAME}")
+set(CTEST_BINARY_DIRECTORY "${CTEST_DASHBOARD_ROOT}/${CTEST_BINARY_NAME}")
+set(CTEST_BUILD_CONFIGURATION "Release")
+set(MODEL "Experimental")
+
+# build generator name, see cmake generator list
+set(CTEST_CMAKE_GENERATOR "Unix Makefiles")
+
+# machine description, can be removed on linux
+set(CTEST_SITE "machine.domain")
+set(SITE_OS_NAME "os name")
+set(SITE_OS_VERSION "os version")
+set(SITE_OS_BITS "os size")
+set(SITE_COMPILER_NAME "compiler name")
+set(SITE_COMPILER_VERSION "compiler version")
+
+# skip submit to cdash
+set(LOCAL_NO_SUBMIT "True")
+# skip update source from repository
+set(LOCAL_SKIP_UPDATE "True")
+
+# needed for source updates, change as required
+set(REPOSITORY_URL "http://svn.hdfgroup.uiuc.edu/hdf5-examples/trunk/1_8")
+
+set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DCMAKE_INSTALL_PREFIX:PATH=/usr/local/hdf5Examples-1.8")
+
+# location of the installed hdf5 (cmake configuration folder)
+set(ENV{HDF5_DIR} "/usr/share/cmake/hdf5")
+
+include(${CTEST_SCRIPT_DIRECTORY}/CTestScript.cmake)
+
+message("DONE")
+#################################################################################
+
+
+
+========================================================================
+For further assistance, send email to help@hdfgroup.org
+========================================================================
+
+