Debian Codegraph @

doc/README

raw
1 Installing HDF-EOS5 using Autoconf/Automake
2 -------------------------------------------
3
4 Prerequisite
5 ------------
6 The HDF-EOS5 library requires HDF5 library version 1.8.19 or later. You can download HDF5
7 from the HDF Group:
8
9 https://www.hdfgroup.org/downloads/hdf5/
10
11 or, depending upon your system, you may be able to install it from a package. The HDF5
12 libary may depend upon other libraries, such as szip, z (compress). The HDF-EOS5
13 configure script will do its best to determine these dependencies and find the appropriate
14 libraries, but it may occasionally need help. Please refer to the troubleshooting section
15 at the bottom of this document.
16
17
18
19 Configuring
20 -----------
21 After downloading and unpacking the tar file, 'cd' into the hdfeos5 directory and type
22
23 ./configure
24
25 This will run a series of tests to determine the necessary library dependencies, and
26 configure the makefiles accordingly. The configure script will output a summary of the
27 configuration options at completion. These can be useful for troubleshooting.
28
29 By default, the HDF-EOS5 libraries and include headers will be installed in /usr/local. This
30 can be changed by using the --prefix option when running configure, e.g.
31
32 ./configure --prefix=/custom/install/location
33
34 A number of other options may be provided to the configure script. You can get details
35 of these options using the command:
36
37 ./configure --help
38
39
40
41
42 Building
43 --------
44
45 Once configured, you can build HDF-EOS5 by simply type
46
47 make
48
49 from the hdfeos5 directory.
50
51
52 Tests
53 -----
54 The HDF-EOS5 library comes with some tests. You can run these using the command
55
56 make check
57
58 from the hdfeos5 directory. These test may provide useful examples, but USE AT YOUR
59 OWN RISK.
60
61
62
63 Installing
64 --------
65
66 To install HDF-EOS5, simply type
67
68 make install
69
70 from the hdfeos5 directory. You need to make sure you have the necessary permissions to
71 install the files in the chosen location.
72
73
74
75
76
77 Troubleshooting
78 ---------------
79
80 General
81 -------
82 This section contains general troubleshooting tips. Additional sections below detail
83 known issues for specific platforms.
84
85 * Determining HDF5 Dependencies
86
87 It can be difficult to find out what additional libraries HDF5 depends upon. This is usually
88 just libz, but may also include libsz. You can get an idea of the dependencies
89 by using the h5cc tool (you may have to search for this):
90
91 h5cc -show
92
93 This will produce output similar to the following:
94
95 gcc -D_LARGEFILE_SOURCE -D_LARGEFILE64_SOURCE -D_BSD_SOURCE -O0 -g -pipe -Wall
96 -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector-strong --param=ssp-buffer-size=4
97 -grecord-gcc-switches -m64 -mtune=generic -L/usr/lib64 /usr/lib64/libhdf5_hl.a
98 /usr/lib64/libhdf5.a -Wl,-z,relro -lsz -lz -ldl -lm -Wl,-rpath -Wl,/usr/lib64
99
100 It lists the libraries that HDF5 (and hence HDF-EOS5) programs will need to link against.
101 In this case we can see both -lsz (libsz) and -lz (libz).
102
103
104 * Finding libraries
105
106 Most of the libraries need by HDF5 and HDF-EOS5 should be found automatically by
107 the configure script, but if it cannot find them, you will need to provide that
108 information to the configure script explicitly. If you need to find a library on
109 your system, you can do this with a simple command: e.g. To find the sz library:
110
111 find / -name 'libsz.*'
112
113 This might produce output as follows:
114
115 /usr/lib64/libsz.so
116 /usr/lib64/libsz.so.2
117 /usr/lib64/libsz.so.2.0.1
118
119 In this case, we have a dynamic (shared) sz library in /usr/lib64 We can tell configure
120 where to find it as follows:
121
122 ./configure --with-szlib=/usr/lib64
123
124 If you cannot find a particular library, you will need to install the appropriate
125 package.
126
127
128 * Installing missing packages
129
130 Linux distributions generally use a package manager to install software packages, though
131 the specific tool varies depending upon the distribution. For example, Centos may use
132 'yum' while Ubuntu may use 'apt'.
133
134 Max OSX systems, while 'Linux like', does not have an official package management tool like
135 the Linux systems. However, there are independently developed tools such as
136 MacPorts (https://www.macports.org/) and HomeBrew (https://brew.sh/) which are just
137 as capable, and can provide everything you need.
138
139 Packages often come in two different 'flavors' - regular, and 'devel'. The regular versions
140 contain the libraries needed to run programs that use them. The 'devel' packages are
141 developer oriented packages that include headers files needed to compile your own
142 programs using that use the libraries. The following is a list of the key packages
143 needed by HDF-EOS5:
144
145 hdf5 The main HDF5 package. A 'devel' version is needed since HDF-EOS5 compiles
146 against this library and needs the header files.
147
148 zlib Compression library. A regular version can be used since HDF-EOS5 does not
149 explicity invoke compression functions.
150
151 aec Adaptive Entropy Encoding library (szip). This may or may not be needed,
152 depending upon how HDF5 was built. If you have access to the h5cc commmand,
153 you can use 'h5cc -show' to determine whether or not it is needed. If
154 the output contains '-lsz', then you need aec. Most package versions of
155 HDF5 do not use aec. If required, a regular version can be used.
156
157 Examples of command to install packages on some of the common linux distributions are
158 given below.
159
160
161
162
163 Linux (Ubuntu/Debian)
164 ---------------------
165
166 * Finding/Installing packages
167
168 These distributions tend to use 'apt' as the package manager. You can search for packages
169 using apt as follows:
170
171 apt-cache search hdf
172
173 A package can be installed as follows:
174
175 apt-get install libhdf4-dev
176
177 One of the advantages of package managers is that if you install a package in this way, it
178 will also install all the dependencies required by the package. You can see which additional
179 packages a given package depends on as follows:
180
181 apt-cache depends libhdf4-dev
182
183 This is also a good way to determine whether or not aec is required.
184
185
186
187 Linux (Redhat/Centos)
188 ---------------------
189
190 * Finding/Installing packages
191
192 These distributions tend to use 'yum' as the package manager. You can search for packages
193 using yum as follows:
194
195 yum search hdf5
196
197 A package can be installed as follows:
198
199 yum install hdf5-devel
200
201 One of the advantages of package managers is that if you install a package in this way, it
202 will also install all the dependencies required by the package. You can see which additional
203 packages a given package depends on as follows:
204
205 yum deplist hdf5-devel
206
207 This is also a good way to determine whether or not aec is required.
208
209
210
211 Mac OSX
212 -------
213
214 * Finding/Installing packages using MacPorts
215
216 You can search for packages using MacPorts as follows:
217
218 port search --name "*hdf5*"
219
220 A package can be installed as follows (you may need to run this using sudo):
221
222 port install hdf5
223
224 As with Linux base package managers, MacPorts will also install all the depenencies required
225 by a package. You can see which additional packages a given package depends on as follows:
226
227 port info hdf5
228
229 Look for a line beginning 'Library Dependencies'. You can ignore any line beginning with
230 'Build Dependencies' since you will not be building HDF5.
231
232
233 * Missing library 'System'.
234
235 If your build fails with a message indicating it cannot find a library called 'System',
236 try adding the following configure option:
237
238 ./configure LDFLAGS=-L/usr/local
239
240 This gives the location of the library to the linker.
241
242
243
244