diff options
Diffstat (limited to 'INSTALL_Windows.txt')
| -rw-r--r-- | INSTALL_Windows.txt | 814 |
1 files changed, 814 insertions, 0 deletions
diff --git a/INSTALL_Windows.txt b/INSTALL_Windows.txt new file mode 100644 index 0000000..d75e045 --- /dev/null +++ b/INSTALL_Windows.txt @@ -0,0 +1,814 @@ +HDF5 Build and Install Instructions for Windows 2000/NT/98. +------------------------------------------------------------------------- + +The instructions which follow assume that you will be using the the source +code release 'zip' file (hdf5-1_4_0.zip). + +***************************WARNINGS********************************* +Please read CAREFULLY about Preconditions before you go to the following sections + +Preconditions + + 1. Installed MicroSoft Developer Studio,Visual C++ 6.0 and WinZip. + + 2. Set up a directory structure to unpack the library. For example: + + c:\ (any drive) + MyHDFstuff\ (any folder name) + + 3. Copied the source distribution archive to that directory and + unpacked it using the appropriate archiver options to create a + directory hierarchy. + + Run WinZip on hdf5-1_4_0.zip (the entire source tree). This + creates a directory called 'hdf5' which contains several files and + directories. + + 4. HDF5 uses zlib for compression and zlib is distributed with + hdf5 lib. If you have your own version read section VI about the + zlib library. + + 5. You do need hdf4 (hdf and mfhdf) static and dll libraries to generate + hdf4-related tools. + + 6. Currently you can build and test either hdf5 libraries and non-hdf4 + related tools or hdf5 libraries and hdf4 related tools; but not BOTH. + In other words,you may either follow Section II or Section III but + NOT both Sections to build HDF5 libraries and related tools. + +--------------------------------------------------------------------------- + +The following sections discuss installation procedures in detail: + + Section I: What do we build and install + Section II: Building and testing hdf5 libraries and non-hdf4 related hdf5 tools + Section III: Building and testing hdf5 libraries and all hdf5 tools + Section IV: Building an application using the HDF5 library or DLL + Section V: Some more helpful pointers + Section VI: ZLIB library - removing or changing the path + +************************************************************************ + +Section I: + +What do we build and install? + + HDF5 static library: + debug and release version + + HDF5 Dynamic Link Library(DLL): + debug and release version as well as export libraries for DLL + + HDF5 tool library: + debug and release version + + HDF5 tool export library for DLL: + debug and release version + + HDF5 tools: + non-hdf4 related tools and hdf4 related tools + + HDF5 library testing programs: + hdf5 library related comprehensive tests + + HDF5 related tools testing programs: + hdf5 tools testing programs + + HDF5 examples: + simple HDF5 examples + +************************************************************** + +Section II: + + Building and testing hdf5 libraries and non-hdf4 related tools + + ================================================== + +STEP 1: Building hdf5 libraries and non-hdf4 related tools + + + 1. Unpack all.zip in 'hdf5' and move the zlib.dll from + c:\myHDFstuff\hdf5\src\zlib\dll to the Windows system directory. + + The system directory can usually be found under the path + C:\WINNT\system or C:\WINDOWS\system + + 2. Invoke Microsoft Visual C++, go to "File" and select the "Open + Workspace" option. + + Then open the c:\myHDFstuff\hdf5\proj\all\all.dsw workspace. + + 3. Select "Build", then Select "Set Active Configuration". + + On Windows platform select as the active configuration + + "all -- Win32 Debug" to build debug versions of + single-threaded static libraries, and + tests. + or + + "all -- Win32 Release" to build release versions of + single-threaded static libraries, and + tests. + + + NOTE : "all" is a dummy target. You will get a link error when + "all.exe." is built: + + LINK: error LNK2001: unresolved external symbol + _mainCRTStartup..... + all.exe - 2 error(s), .... + + Warning messages can be ignored. The "all.exe" is never created, + so it is OK. + + When the debug or release build is done the directories listed + below will contain the following files : + + c:\MyHDFstuff\hdf5\proj\hdf5\debug - + c:\MyHDFstuff\hdf5\proj\hdf5\release - + + hdf5.lib- the hdf5 library + + c:\MyHDFstuff\hdf5\proj\hdf5dll\debug - + + hdf5d.dll- the hdf5 library + hdf5d.lib- the dll export library + + c:\MyHDFstuff\hdf5\proj\hdf5dll\release - + + hdf5.dll- the hdf5 library + hdf5.lib- the dll export library + + c:\MyHDFstuff\hdf5\test\"test directory"- + + where test directory is one of the following: + + big + + bittests + + chunk + + cmpd_dset + + dsets + + dtypes + + enum + + extend + + external + + fillval + + flush1 + + flush2 + + gheap + + hyperslab + + iopipe + + istore + + links + + mount + + mtime + + ohdr + + overhead + + + + stab + + testhdf5 + + unlink + + + c:\MyHDFstuff\hdf5\tools\toolslib\debug + c:\MyHDFstuff\hdf5\tools\toolslib\release + + toolslib.lib- the tools library + + c:\MyHDFstuff\hdf5\tools\toolslibD\debug + c:\MyHDFstuff\hdf5\tools\toolslibD\release + + toolslibD.lib- the dll export library + + c:\MyHDFstuff\hdf5\tools\"tools directory"- + where non-hdf4 related tools directory is one of the following: + + h5dump + + h5ls + + h5debug + + h5import + + + Test and tool directory contains debug and release +subdirectories with the corresponding tests and tools. + + +STEP 2: testing hdf5 libraries and non-hdf4 related tools + +In a command prompt window run the test batch file which resides in the +hdf5\test directory to make sure that the library was built correctly. + +You can possibily test four versions of hdf5 library and tools. They are: + + release + release dll + debug + debug dll + +NOTE: The appropriate dll should be placed into the C:\WINNT\system or + C:\WINDOWS\system directory before using the dlls. + +We strongly suggest you to redirect your testing results into an output file +and you can easily check the testing results. You may use either NotePad or +NoteTab Light or whatever other tools to check the results. + + 1. hdf5 static libraries and DLLs testing + + cd into the hdf5\test directory. + + (1) basic tests + + Go to a) b) c) or d) to test your chosen version + + a) release static version + type: + hdf5test release >"Your output filename" + + b) release dll version + type: + hdf5test release dll > "Your output filename" + + c) debug static version + type: + hdf5test debug >"Your output filename" + + d) debug dll version + type: + hdf5test debug dll >"Your output filename" + + (2) timing tests + + Go to a) b) c) or d) to test your chosen version + + a) release static version + type: + hdf5timingtest release >"Your output filename" + + b) release dll version + type: + hdf5timingtest release dll > "Your output filename" + + c) debug static version + type: + hdf5timingtest debug >"Your output filename" + + d) debug dll version + type: + hdf5timingtest debug dll >"Your output filename" + + + Use notepad or notetab light to check results. You should not find any + FAILED marks in your output files. + + Note: big test is currently not working for windows, we are still + investigating this. + + 2. hdf5 tools testing + + Currently we are only supporting h5dump test. We are investigating + h5ls test now. + + 1) h5dump test + + cd back into hdf5 directory and then go to tools directory + + Go to a) b) c) or d) to test your chosen version + + a) release static version + type: + dumptest release >"Your output filename" + + b) release dll version + type: + dumptest release dll > "Your output filename" + + c) debug static version + type: + dumptest debug >"Your output filename" + + d) debug dll version + type: + dumptest debug dll >"Your output filename" + + + We are using "fc" command to compare whether dumper generates correct + results. Supposedly you should find "FC: no differences encountered" in + your output file. However, since we are comparing the actual dumper output + with the expected dumper output under different directory, you may see + something like: + +" +***** ..\TESTFILES\tall-1.ddl +############################# +Expected output for 'h5dump tall.h5' +############################# +HDF5 "tall.h5" { +GROUP "/" { +***** TALL-1.RESULTS +HDF5 "..\..\testfiles\tall.h5" { +GROUP "/" { +***** +" + + The actual dumper output is correct. The difference showing here + is the different representations of filename of the same file. + +STEP 3: BUILDING THE EXAMPLES + + 1. Invoke Microsoft Visual C++, go to "File" and select + the "Open Workspace" option. + Then open the c:\myHDFstuff\hdf5\examples\allexamples\allexamples.dsw + workspace. + + 2. Select "Build", then Select "Set Active Configuration". + + On Windows platform select as the active configuration + + "allexamples -- Win32 Debug" to build debug versions of the + examples. + + or + + "allexamples -- Win32 Release" to build release versions the + examples. + + When the debug build or release build is done there should be + the following subdirectories in C:\myHDFstuff\hdf5\examples\ + + attributetest + + chunkread + + compoundtest + + extendwritetest + + grouptest + + readtest + + selecttest + + writetest + + + + 3. Run the batch file "InstallExamples.bat" which resides in the + top level directory. This file creates 2 new directories, + examplesREL and examplesDBG, in the examples directory and places + all the executables in it. Both the release and debug versions of + the examples should be built before this step is done. The + examples should be tested in these 2 new directories due to some + dependencies between the examples. + +********************************************************************** + +Section III: BUILDING AND TESTING HDF5 LIBRARIES AND ALL HDF5 TOOLS + +--------------------------WARNINGS------------------------------------ + +1. This section is specifically for building HDF5 tools that needs to +call HDF4 library. + +Currently we are supporting two such kinds of tools: H4toh5 converter +and H5toh4 converter. If you are not using these tools, please go back +to Section II for building and installing information. + +2. This section builds and tests all versions of hdf5 libraries,testing +programs and tools covered in section II. Additionally, it also builds +and tests hdf4-related tools. We may refer some duplicated parts of this +section to section II. + +3. In case + a) you don't install hdf libraries and related tools in your machine, + b) or if the top directory of your hdf4 libraries and tools are not + under C:\hdf41r4 and you are not familar on how to change settings of + VC++ projects. + + you may get binary distribution from +ftp://ftp.ncsa.uiuc.edu/HDF/HDF/HDF4.1r4/windows_precompiled_code/HDF41r4.zip +and use Winzip to unpack HDF41r4.zip into C:\hdf41r4. + +4. We assume that you've installed hdf4(mfhdf and hdf) libraries into drive C. +The top level path should be C:\HDF41r4. Under C:\HDF41r4 it should at least +include the following six directories: + +C:\HDF41r4\bin where hdf4 utilities are stored +C:\HDF41r4\dlllib where release dll versions of hdf and mfhdf libraries and +export libraries of dlls are stored +C:\HDF41r4\dlllibdbg where debug dll versions of hdf and mfhdf libraries and +export libraries of dlls are stored +C:\HDF41r4\lib where release versions of hdf and mfhdf libraries are stored +C:\HDF41r4\libdbg where debug versions of hdf and mfhdf libraries are stored +C:\HDF41r4\include where header files are included + +Make sure that you copy all *.dll files under C:\HDF41r4 into Windows system +directory before the next step. + +If your path of hdf libraries and mfhdf libraries is different from the +default assumption, please DO follow No.3 of Step 1 on the following: + + +Step 1. + + 1. Unpack all_withhdf4.zip in 'hdf5' and move the zlib.dll from + c:\myHDFstuff\hdf5\src\zlib\dll to the Windows system directory. + + The system directory can usually be found under the path + C:\WINNT\system or C:\WIN98\system + + 2. Invoke Microsoft Visual C++, go to "File" and select the "Open + Workspace" option. + + Then open the c:\myHDFstuff\hdf5\proj\all\all.dsw workspace. + + 3. This part is for users who are familar with handling settings of + VC++ project and store their hdf4 libraries not under C:\hdf41r4. + Other users can skip this part. + + 3.1 Change the path where hdf4 library header files are located + a) On the View menu, click Workspace, you may see a pop-up window + with names of projects in all.dsw. + b) click FileView on the bottom of this window if you are not + seeing "all files big files ......." + c) You need to modify settings of four projects: h4toh5, + h4toh5dll,h5toh4 and h5toh4dll. + You also need to modify both debug and release versions. + + You may do as follows: + c1)Right click the selected project and then click "Settings" + c2)A dialog box called "Project Settings" will be poped up + c3)On the upper-left part of the "Project Settings" box, you + may find a small window "Settings for". Make sure inside + this "Settings for" box is either "Win32 Debug" or + "Win32 Release". Change contents into "Win32 Debug" or + "Win32 Release" otherwise. + Remember the version(Win32 Release or Debug) you choose. + c4)On the upper-right menu of the "Project Settings" box, + find C/C++ and click it + c5)Just below the upper-right menu, find a small window + called category, make sure that "Preprocessor" appear + in this window. + c6)In the middle of "Project Settings" box, you may find a + box called "Additional include directories:" you may find + "C:\hdf41r4\include" inside this box. This is the path + where the default hdf4 header files is included. Replace + only this path(C:\hdf41r4\include) with your own path that + includes your hdf4 header files.Don't touch any other paths. + c7)After you've done this, click OK at the bottom of + "Project Settings" window. + c8)Repeat c1)-c7)but change contents of "settings for" in C3) + from "Win32 Release" to "Win32 Debug" or vice versa. + d) repeat step c) for the other three projects. + + 3.2 Replace the user's hdf and mfhdf libraries, export libraries + of hdf and mfhdf DLLs + + You also need to modify four projects: h4toh5, h4toh5dll, h5toh4 + and h5toh4dll. + a) select project h4toh5 following instruction 3.1 a) and b). + b) click h4toh5, you may find four libraries: hm414d.lib, + hd414d.lib and hm414.lib,hd414.lib attached under the project + h4toh5. hm414d.lib and hd414d.lib are debug versions of mfhdf + and hdf libraries. hm414.lib and hd414.lib are release versions + of mfhdf and hdf libraries. + c) select these four libraries; go back to Edit menu and choose + "delete" option to delete template of these libraries. + d) select project h4toh5 and right click the mouse, find + "Add Files to Projects", follow the instructions on the pop-up + box, to insert your own hm414d.lib, hd414d.lib,hm414.lib and + hd414.lib. You must know their paths at first. + e) select project h4toh5dll following instruction 3.1 a) and b). + f) click h4toh5dll, you may also find four libraries: hd414m.lib, + hd414md.lib and hm414m.lib,hd414m.lib attached under the + project h4toh5dll. These libraries are debug and release + versions of Export libraries of mfhdf and hdf DLLs. + g) select these four libraries; go back to Edit menu and choose + "delete" option to delete template of these libraries. + h) select project h4toh5 and right click the mouse, find + "Add Files to Projects", follow the instructions on the pop-up + box, to insert your own hd414m.lib, hd414md.lib,hm414m.lib and + hd414m.lib. You must know their paths at first. + i) repeat a)-h) for h5toh4 and h5toh4dll. + + 4. Select "Build", then Select "Set Active Configuration". + + On Windows platform select as the active configuration + + "all -- Win32 Debug" to build debug versions of + single-threaded static libraries, and + tests. + or + + "all -- Win32 Release" to build release versions of + single-threaded static libraries, and + tests. + + + NOTE : "all" is a dummy target. You will get a link error when + "all.exe." is built: + + LINK: error LNK2001: unresolved external symbol + _mainCRTStartup..... + all.exe - 2 error(s), .... + + Warning messages can be ignored. The "all.exe" is never created, + so it is OK. + + You should see hdf5 libraries, tests and tools under section II + Step 1. + In addtion, under c:\MyHDFstuff\hdf5\tools\"tools directory"- + + You may also find: + h4toh5 + h5toh4 + for both the debug and release versions. + +STEP 2: testing hdf5 libraries and all hdf5 tools + + 1. hdf5 static libraries and DLLs testing + Follow all instructions of the same part in Section II STEP 2 + + 2. non-hdf4 related tools testing + Follow all instructions of the same part in Section II STEP 2 + + 3. hdf4-related tools testing + + 1) h4toh5 converter tool testing + + First cd into hdf5\tools + + Go to a) b) c) or d) to test your chosen version + + a) release static version + type: + h4toh5testrun release >"Your output filename" + + b) release dll version + type: + h4toh5testrun release dll > "Your output filename" + + c) debug static version + type: + h4toh5testrun debug >"Your output filename" + + d) debug dll version + type: + h4toh5testrun debug dll >"Your output filename" + + We are using "fc" command to compare whether h4toh5 converter + converts the hdf4 file into the correct hdf5 file.In your output + files, Please only pay attention to those lines which start with + "FC:",you should find "FC: no differences encountered" for all + tested hdf4 files in your output. + + 2) h5toh4 converter tool testing + + To test the h5toh4 utility, you need to use hdf4 dumper utility + "hdp" in your system. + + Before the testing, you need to find + + a) The TOP directory path(including the drive name) where + hdf5 library and tools is located,for example: C:/h5_1.4 + (You may find the path by selecting folder "hdf5" where + your hdf5 library and tools are stored, right click and + choose "property"; you should find the path from property + window.) + + b) The full path where hdp is located, for example C:/H414/bin + (using property function to find the path of hdp). + + + 1) cd into hdf5\tools. + + Four parameters should be input for h5toh4 test + + 2) For windows NT 4.0 and 5.0 + type h5toh4testrun [para 1] [para 2] [para 3] [para 4] + + 3) For Windows 98 + type h5toh4testwin98 [para 1] [para 2] [para 3] [para 4] + + para 1: [Debug] or [Release] version you are testing. + para 2: The top directory path(including the drive name) where hdf5 + tools is located,for example: C:\h5_1.4 + para 3: The full path where hdp is located, for example: + C:\HDF41r4\bin + para 4: If no dll version,leave this parameter empty or type DLL + + Again, we are using "fc" command to compare whether h5toh4 + converter converts the hdf5 file into the correct hdf4 file. + In your output files, Please only pay attention to those lines + which start with + "FC:",you should find "FC: no differences encountered" for all + tested hdf5 files in your output. + + + ***** Warnings:******* + Do make sure that you type the correct parameters according to the + correct orders. Para 2 and Para 3 should be correctly input. + Otherwise, the result may be unpredictable. + +STEP 3: BUILDING THE EXAMPLES + + Follow all instructions of SECTION II STEP 3. + +Section IV: +BUILDING AN APPLICATION USING THE HDF5 LIBRARY OR DLL- SOME HELPFUL POINTERS +============================================================================ + +If you are building an application that uses the HDF5 library the +following locations will need to be specified for locating header files +and linking in the HDF libraries: + + <top-level HDF5 directory>\src + +where <top-level HDF5 directory> may be + + C:\MyHDFstuff\hdf5\ + + +To specify this location in the settings for your VC++ project: + + 1. Open your VC project in Microsoft Visual C++ and make sure it is + the active project. + + 2. Go to the Project menu and chose the 'Settings' option. + + 3. Chose the build configuration you would like to modify in the + drop down menu labeled with 'Settings For:' + + 4. Chose the C/C++ tab + + 5. At the bottom of the window, there should be a text-area labeled + with 'Project Options:'. In this text-area, scroll until you + reach the end and type /I "<top-level HDF5 directory>\src" and + then click OK. + +To link the HDF5 library with your application: + + 1. Open your VC project in Microsoft Visual C++ and make sure it is + the active project. + + 2. Go to the Project menu and chose the 'Add to Project' option and + then 'Files' option. + + 3. Change the 'Files of type:' to 'Library Files (.lib)' + + 4. Navigate through the directories until you find the location of the + hdf5.lib. + + 5. Select hdf5.lib and click OK. + + +To use the DLL: + + 1. Follow the steps for specifing the location of the header files + as shown above. + + 2. Follow the steps for linking the HDF5 library as shown above + except now link the export library that is created with the DLL. + The export library is called hdf5dll.lib. + + 3. Place the DLL in a location that Windows will be able to locate it. + The search 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 V: +MORE HELPFUL POINTERS +===================== + + +Here are some notes that may be of help if you are not familiar with +using the Visual C++ Development Environment. + +Project name and location issues: + + The files in all.zip must end up in the hdf5\ directory installed by + hdf5-1_4_0.zip + + If you must install all.dsw and all.dsp in another directory, + relative to hdf5\ , you will be asked to locate the sub-project + files, when you open the project all.dsw. + + If you want to rename all (the entire project), you will need to + modify two files all.dsw and all.dsp as text (contrary to the + explicit warnings in the files). + + You can also modify all.dsw and all.dsp as text, to allow these 2 + files to be installed in another directory. + + +Settings... details: + + If you create your own project, the necessary settings can be read + from the all.dsp file(as text), or from the Project Settings in the + Developer Studio project settings dialog. + + Project + Settings + C/C++ + Category + PreProcessor + Code Generation + Use run-time Library + These are all set to use + Single-Threaded + +DLL... hints: + + If you want to use DLL versions of hdf5 library in your application, + you should + 1) put hdf5 DLL into windows system directory + 2) add hdf5 DLL export library into your project + 3) Follow "Settings... details" into the last line: + change Single-Threaded into Multithreaded DLL or + Debug Multithreaded DLL + 4) Follow "Settings.. details" into PreProcessor: + Project + Settings + C/C++ + Category + PreProcessor + + Find PreProcessor definations and Add _HDF5USEDLL_ at the + end of the PreProcessor definations + + + + +Section VI: +ZLIB LIBRARY- REMOVING OR CHANGING THE PATH +============================================ + +If you would like to remove the zlib library from the hdf5 library or use +your own version of the zlib library then follow the steps below. + +Removing the zlib library completely: + + Open the all.dsw workspace file in Microsoft Visual C++. Go to the + hdf5 project. Select the zlib.lib file from this project and + delete(press the 'delete' key) it. Next open the H5config.h file + from the src directory. Remove the the following two lines: + + #define HAVE_LIBZ 1 + #define HAVE_COMPRESS2 + + then save the file. + + Next go to the hdf5dll project. Remove the zlib.lib from this project + too. Open the project settings for the hdf5dll project. Go to the + C/C++ settings tab and under the preprocessor definitions remove the + ZLIB_DLL in both the debug and the release settings. Recompile the + all project and then save the workspace. + + +Replacing the zlib library: + + Open the all.dsw workspace and go to the hdf5 project. Delete the + zlib.lib file from the file listing. Then select the hdf5 project + and richt click to get a menu. Pick the "add files to project..." + option and find the version of the zlib that you would like to use. + Then click OK in the file chooser dialog. Repeat the steps for the + hdf5dll project. You may also want to replace the zlib.h and zconf.h + files which are in the src directory with your own versions of these + files. Then recompile the all project. |