summaryrefslogtreecommitdiffstats
path: root/release_docs/USING_CMake.txt
diff options
context:
space:
mode:
authorAllen Byrne <byrn@hdfgroup.org>2012-09-17 16:00:07 (GMT)
committerAllen Byrne <byrn@hdfgroup.org>2012-09-17 16:00:07 (GMT)
commit8c870f14c100e57b39ea4995adc7a1d7cce63724 (patch)
treecf0ea2c02b308b0d3046cb019c3813edcba59290 /release_docs/USING_CMake.txt
parent786b220e46912e855f1274bf9f531fae7fa15e85 (diff)
downloadhdf5-8c870f14c100e57b39ea4995adc7a1d7cce63724.zip
hdf5-8c870f14c100e57b39ea4995adc7a1d7cce63724.tar.gz
hdf5-8c870f14c100e57b39ea4995adc7a1d7cce63724.tar.bz2
[svn-r22770] Update windows release docs to match 1.8
Diffstat (limited to 'release_docs/USING_CMake.txt')
-rw-r--r--release_docs/USING_CMake.txt202
1 files changed, 202 insertions, 0 deletions
diff --git a/release_docs/USING_CMake.txt b/release_docs/USING_CMake.txt
new file mode 100644
index 0000000..71f2fcf
--- /dev/null
+++ b/release_docs/USING_CMake.txt
@@ -0,0 +1,202 @@
+************************************************************************
+* Build and Install HDF5 Applications with CMake *
+************************************************************************
+
+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
+ "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
+ all 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 was originally introduced to support development on Windows,
+ however it 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. Visit the KitWare site for more information about CMake.
+
+ 3. HDF5 library 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.
+
+
+========================================================================
+ 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).
+
+ 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. On Windows with Visual Studio, if you have installed the static HDF5
+ library, you will need to add the HDF5\lib folder to the library
+ search list. See the "Using Static Libraries with Visual Studio" section.
+
+ 4. Set the environment variable HDF5_ROOT to the installed location of HDF5.
+ On Windows HDF5_ROOT=C:\Program Files\HDF Group\HDF5\hdf5-1.8.x
+ (Note there are no quote characters used on windows)
+
+========================================================================
+ Building HDF5 Applications with CMake
+========================================================================
+
+ 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. 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).
+
+ OPTIONAL:
+ Users can perform the configuration step without using the visual cmake-gui
+ program. Example 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 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.
+
+ 6. The files that support building with CMake are all 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 users
+ installation and needs.
+
+ 7. More information about using CMake can be found at the KitWare site,
+ www.cmake.org.
+
+
+========================================================================
+ Using HDF5 Libraries with Visual Studio 2008
+========================================================================
+
+ 8. Set up path for external libraries and headers
+
+ Invoke Microsoft Visual Studio and go to "Tools" and select "Options",
+ find "Projects", and then "VC++ Directories".
+
+ 8.1 If you are building on 64-bit Windows, find the "Platform" dropdown
+ 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)
+ 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)
+ to the library directories.
+
+ 8.4 If using Fortran libraries, you will also need to setup the path
+ for the Intel Fortran compiler.
+
+
+========================================================================
+ Minimum C Project Files for CMake
+========================================================================
+
+ 9. Create a CMakeLists.txt file at the source root.
+..........................................................................
+cmake_minimum_required (VERSION 2.8.6)
+PROJECT (HDF5MyApp C CXX)
+
+FIND_PACKAGE (HDF5 REQURIED)
+INCLUDE_DIRECTORIES (${HDF5_INCLUDE_DIRS})
+SET (LINK_LIBS ${LINK_LIBS} ${HDF5_LIBRARIES})
+
+ADD_EXECUTABLE (hdf_example ${PROJECT_SOURCE_DIR}/hdf_example.c)
+TARGET_LINK_LIBRARIES (hdf_example ${LINK_LIBS})
+..........................................................................
+
+************************************************************************
+
+Need further assistance, send email to help@hdfgroup.org
+