[svn-r23333] Update CMake documentation, remove obsolete info for windows.

1 files changed, 4 insertions, 639 deletions

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: