NetCDF  4.4.1.1
install.md
1 Getting and Building netCDF {#getting_and_building_netcdf}
2 =============================
3 
4 [TOC]
5 
6 This document is for getting and building the netCDF C library and utilities for the most recent released version. Other libraries that depend on the netCDF C library, such as the Fortran, Python, Java, and C++ libraries, are available as separate distributions that can be optionally built and installed after the C library is successfully installed. The netCDF-Java library is independent of the netCDF C library unless writing netCDF-4 files from Java is required.
7 
8 Getting netCDF-C {#getting}
9 =========================
10 
11 * For information regarding the netCDF-Fortran libraries, see \subpage building_netcdf_fortran.
12 * Functionality to make it easier to build netcdf-fortran as part of the netcdf-c build for *non-MSVC* builds may be enabled at configure time by using the following **Highly Experimental** options:
13 
14  * Autotools: `--enable-remote-fortran-bootstrap`
15  * CMake: `-DENABLE_REMOTE_FORTRAN_BOOTSTRAP=ON`
16 
17 For more details, see the <a href="https://github.com/Unidata/netcdf-c/blob/master/RELEASE_NOTES.md">draft instructions</a> in the Release Notes under the `4.3.3-rc3` section.
18 
19 Getting pre-built netCDF-C libraries. {#sec_get_pre_built}
20 -------------------------------------
21 
22 The easiest way to get netCDF is through a package management program,
23 such as rpm, yum, homebrew, macports, adept, and others. NetCDF is
24 available from many different repositories, including the default Red
25 Hat and Ubuntu repositories.
26 
27 When getting netCDF from a software repository, you should get a
28 development version that includes the netcdf.h header file. A
29 development version will typically have a name such as "netcdf-devel"
30 or "libnetcdf-dev".
31 
32 Instructions for installing and using pre-built libraries for Windows may be found here: \ref winbin.
33 
34 Getting the latest netCDF-C Source Code {#sec_get_source}
35 ----------------------------------------
36 
37 The netCDF-C source code is hosted from the <a href="http://github.com/Unidata/netcdf-c" >Unidata GitHub repository</a>.
38 
39 
40 Two options are available for building from source:
41 
42 * The latest release.
43 * The developer snapshot.
44 
45 ### The latest release {#sec_latest_release}
46 
47 The latest full release may be <a href="http://github.com/Unidata/netcdf-c/releases" >downloaded from GitHub</a>.
48 
49 Source files are available in `.tar.gz` and `.zip` formats.
50 
51 ### The developer snapshot {#sec_dev_snapshot}
52 
53 The developer snapshot may be cloned from GitHub directly by using the `git` command.
54 
55 > $ git clone http://github.com/Unidata/netcdf-c netcdf-c
56 
57 **Note:**
58 
59 *The developer snapshot release contains bug-fixes and new features added since the last full release, but may also contain new bugs, as it is not tested as extensively as the full release.*
60 
61 Building netCDF-C {#building}
62 ===========================
63 
64 The netCDF-C library and utilities require third-party libraries for
65 full functionality. (See \ref architecture).
66 * \ref build_default
67 * \ref build_classic
68 * \ref build_hdf4
69 * \ref build_parallel
70 * \ref building_netcdf_fortran
71 * \ref configure_options
72 
73 Requirements {#netcdf_requirements}
74 ----------------------------------
75 
76 * HDF5 1.8.9 or later (for netCDF-4 support)
77 * zlib 1.2.5 or later (for netCDF-4 compression)
78 * curl 7.18.0 or later (for DAP remote access client support)
79 
80 
81 CMake and Windows support {#sub}
82 --------------------------------
83 
84 * \ref netCDF-CMake
85 * \subpage winbin
86 
87 Building with netCDF-4 and the Remote Data Client {#build_default}
88 --------------------------------
89 
90 The usual way of building netCDF requires the HDF5, zlib, and curl libraries. Versions required are at least HDF5 1.8.9, zlib 1.2.5, and curl 7.18.0 or later.
91 
92 HDF5 and zlib packages are available from the <a href="http://www.hdfgroup.org/downloads/">HDF5 downloads site</a> and the <a href="http://www.zlib.net/">zlib home site</a>. If you wish to use the remote data client code, then you will also need libcurl, which can be obtained from the <a href="http://curl.haxx.se/download.html">curl website</a>.
93 
94 > Note that for building netCDF, it is not necessary to build the HDF5 Fortran, C++, or Java API's. Only the HDF5 C library is used, even for netCDF Fortran or C++ libraries.
95 
96 ### Optional: szip support {#op_szip_support}
97 
98 *Optionally*, you can also build netCDF-4 with the szip library (a.k.a. szlib). If building with szlib, get szip 2.0 or later. NetCDF cannot create szipped data files, but can read HDF5 data files that have used szip. To determine whether license restrictions on the use of szip apply to your situation, see the <a href="http://www.hdfgroup.org/doc_resource/SZIP/">web page on szip compression in HDF products</a>.
99 
100 If `make check` fails for either `zlib` or `HDF5`, the problem must be resolved before the netCDF-4 installation can continue. For HDF5 problems, see the <a href="http://www.hdfgroup.org/services/support.html">HDF5 help services</a>.
101 
102 ### Building zlib from source {#build_zlib_from_source}
103 
104 To build zlib from source, specify where you want to install zlib in a shell variable you will also use later (ZDIR, for example), and build it like this from the top-level zlib source directory
105 
106 ~~~~{.py}
107  $ # Build and install zlib
108  $ ZDIR=/usr/local
109  $ ./configure --prefix=${ZDIR}
110  $ make check
111  $ make install # or sudo make install, if root permissions required
112 ~~~~
113 
114 ### Building hdf5 from source {#build_hdf5_from_source}
115 
116 Next, specify where you want to install HDF5 in another shell variable, for example H5DIR, and build it from the HDF5 top-level source directory:
117 
118 ~~~~{.py}
119  $ # Build and install HDF5
120  $ H5DIR=/usr/local
121  $ ./configure --with-zlib=${ZDIR} --prefix=${H5DIR}
122  $ make check
123  $ make install # or sudo make install, if root permissions required
124 ~~~~
125 
126 If you are building HDF5 with the optional szip library, include the `--with-szlib=` option to specify where it was installed.
127 
128 In all cases, the installation location specified with the `--prefix` option *must be different* from the source directory where the software is being built.
129 
130 ### Building netCDF-4 and the Remote Data Client from source {#build_nc4_dap_from_source}
131 
132 Before building netCDF, you may need to add `${H5DIR}/lib` to the LD_LIBRARY_PATH environment variable if that lib directory is not searched by default. See the <a href="http://www.unidata.ucar.edu/netcdf/docs/faq.html#Shared%20Libraries">netCDF FAQ</a> for more details on using shared libraries.
133 
134 Indicate where you want to install netCDF in another shell variable, for example NCDIR. Then run the netCDF configure script, specifying where HDF5 was installed using the CPPFLAGS and LDFLAGS environment variables. For example, from the top-level netCDF source directory:
135 
136 ~~~~{.py}
137  $ # Build and install netCDF-4
138  $ NCDIR=/usr/local
139  $ CPPFLAGS=-I${H5DIR}/include LDFLAGS=-L${H5DIR}/lib ./configure --prefix=${NCDIR}
140  $ make check
141  $ make install # or sudo make install
142 ~~~~
143 
144 If you don't provide a `--prefix` option, installation will be in `/usr/local/`, in subdirectories lib/, include/, and bin/. The installation location specified with the `--prefix` option must be different from the source directory where the software is being built.
145 
146 > WARNING: you should be able to use parallel 'make all'. But 'make check' will probably fail if you use parallel make. This is because historically, there are inter-dependencies between test programs. It is unlikely that this will be fixed any time soon, if ever.
147 
148 Building netCDF with Classic Library Only {#build_classic}
149 ---------------------------------------
150 
151 It is possible to build the netCDF C libraries and utilities so that
152 only the netCDF classic and 64-bit offset formats are supported, or
153 the remote data access client is not built. (See \ref netcdf_format
154 for more information about the netCDF format variants. See the <a
155 href="http://www.opendap.org/documentation">DAP documentation and
156 support site</a> for more information about remote client access to
157 data on OPeNDAP servers.)
158 
159 If necessary, set the NCDIR shell variable to indicate where netCDF should be
160 installed. Then to build a netCDF-3 library without support for the
161 netCDF-4 formats or functions, but with remote client access, use:
162 
163 ~~~~{.py}
164  $ # Build and install netCDF-3 from netCDF-4 source
165  $ ./configure --prefix=${NCDIR} --disable-netcdf-4
166  $ make check install
167 ~~~~
168 
169 To build with full support for netCDF-4 API's and format but without
170 remote client access, use:
171 
172 ~~~~{.py}
173  $ # Build and install netCDF-4 without DAP client support
174  $ ./configure --prefix=${NCDIR} --disable-dap
175  $ make check install
176 ~~~~
177 
178 To build without netCDF-4 support or remote client access, use:
179 
180 ~~~~{.py}
181  $ # Build and install minimal netCDF-3 with no DAP client support
182  $ ./configure --prefix=${NCDIR} --disable-netcdf-4 --disable-dap
183  $ make check install
184 ~~~~
185 
186 If you get the message that netCDF installed correctly, then you are
187 done!
188 
189 Building with HDF4 Support {#build_hdf4}
190 ---------------------
191 
192 The netCDF-4 library can read HDF4 data files, if they were created
193 with the SD (Scientific Data) API.
194 
195 For this to work, you must build the HDF4 library with the
196 configure option `--disable-netcdf`
197 to prevent it from building an HDF4 version of the netCDF-2 library
198 that conflicts with the netCDF-2 functions that are built into the Unidata
199 netCDF library.
200 
201 Then, when building netCDF-4, use the `--enable-hdf4`.
202 option to configure. The location for the HDF4 header files and
203 library must be specified in the CPPFLAGS and LDFLAGS environment variables
204 or configure options.
205 
206 For HDF4 access to work, the library must be built with netCDF-4
207 features.
208 
209 Here's an example, assuming the HDF5 library has been built and
210 installed in H5DIR and you will build and install the HDF4 library in
211 H4DIR (which could be the same as H5DIR). From the top-level HDF4
212 source directory:
213 
214 ~~~~{.py}
215  $ # Build and install HDF4
216  $ ./configure --enable-shared --disable-netcdf --disable-fortran --prefix=${H4DIR}
217  $ make check
218  $ make install
219 ~~~~
220 
221 Then from the top-level netCDF directory:
222 
223 ~~~~{.py}
224  $ # Build and install netCDF-4 with HDF4 access enabled
225  $ CPPFLAGS="-I${H5DIR}/include -I${H4DIR}/include" \
226  LDFLAGS="-L${H5DIR}/lib -L${H4DIR}/lib" \
227  ./configure --enable-hdf4 --enable-hdf4-file-tests
228  $ make check
229  $ make install
230 ~~~~
231 
232 Building with Parallel I/O Support {#build_parallel}
233 --------------
234 
235 For parallel I/O to work, HDF5 must be installed with
236 â€“enable-parallel, and an MPI library (and related libraries) must be
237 made available to the HDF5 configure. This can be accomplished with
238 an mpicc wrapper script.
239 
240 The following works from the top-level HDF5 source directory to build
241 HDF5 with parallel I/O:
242 
243 ~~~~{.py}
244  $ # Build and install HDF5 with parallel support
245  $ CC=mpicc ./configure --enable-parallel --prefix=${H5DIR}
246  $ make check
247  $ make install
248 ~~~~
249 
250 If the HDF5 used by netCDF has been built with parallel I/O, then netCDF will also be built with inherited support for parallel I/O. This allows parallel I/O access to netCDF-4/HDF5 files. (See /ref netcdf_formats for more information about the netCDF format variants.)
251 
252 From the top-level netCDF-4 source directory, the following builds netCDF-4 with parallel I/O, assuming H5DIR specifies where parallel HDF5 was installed:
253 
254 ~~~~{.py}
255  $ # Build, test, and install netCDF-4 with HDF5 parallel support
256  $ CC=mpicc CPPFLAGS=-I${H5DIR}/include LDFLAGS=-L${H5DIR}/lib \
257  ./configure --disable-shared --enable-parallel-tests --prefix=${NCDIR}
258  $ make check
259  $ make install
260 ~~~~
261 
262 If parallel I/O access to netCDF classic and 64-bit offset files is
263 needed, an alternate
264 [parallel-netcdf library](https://trac.mcs.anl.gov/projects/parallel-netcdf/wiki/WikiStart),
265 referred to as "PnetCDF", must also be installed. Assume it was
266 installed in the directory named by the PNDIR shell variable.
267 Then, from the top-level netCDF-4 source directory, configure netCDF
268 with the "--enable-pnetcdf" option:
269 
270 ~~~~{.py}
271  $ # Build, test, and install netCDF-4 with pnetcdf support
272  $ CC=mpicc CPPFLAGS="-I${H5DIR}/include -I${PNDIR}/include" \
273  LDFLAGS="-L${H5DIR}/lib -L${PNDIR}/lib" ./configure \
274  --disable-shared --enable-pnetcdf --enable-parallel-tests \
275  --prefix=${NCDIR}
276  $ make check
277  $ make install
278 ~~~~
279 
280 Linking to netCDF-C {#linking}
281 -------------------
282 
283 For static builds of applications that use netCDF-4 you must link to all the libraries,
284 netCDF, HDF5, zlib, szip (if used with HDF5 build), and curl (if the
285 remote access client has not been disabled). This will require -L options
286 to your build for the locations of the libraries, and -l (lower-case
287 L) for the names of the libraries.
288 
289 For example, you might build other applications with netCDF-4 by
290 setting the LIBS environment variable, assuming NCDIR, H5DIR, and ZDIR
291 indicate where netCDF, HDF5, and zlib are installed:
292 
293 ~~~~{.py}
294  LIBS="-L${NCDIR}/lib -lnetcdf -L${H5DIR}/lib -lhdf5_hl -lhdf5 -L${ZDIR}/lib -lz -lm"
295 ~~~~
296 
297 For shared builds, only `-L${NCDIR}/lib -lnetcdf` is
298 needed. All other libraries will be found automatically.
299 
300 The `pkg-config` or `nc-config` utilities can be
301 used to specify build options for software that uses netCDF. For
302 example, to compile and link an application named myapp.c with a
303 netCDF-C libraries, whether shared or static, you can use
304 
305 ~~~~{.py}
306  $ cc -o myapp myapp.c `nc-config --cflags --libs`
307 ~~~~
308 
309 or
310 
311 ~~~~{.py}
312  $ PKG_CONFIG_PATH=${NCDIR}/lib/pkgconfig:$PKG_CONFIG_PATH
313  $ export PKG_CONFIG_PATH
314  $ cc -o myapp myapp.c `pkg-config --cflags --libs netcdf`
315 ~~~~
316 
317 configure options {#configure_options}
318 -----------------------------
319 
320 These options are used for `autotools`-based builds.yup
321 
322 Note: `--disable` prefix indicates that the option is normally enabled.
323 <table>
324 <tr><th>Option<th>Description<th>Dependencies
325 <tr><td>--disable-doxygen<td>Disable generation of documentation.<td>doxygen
326 <tr><td>--disable-fsync<td>disable fsync support<td>kernel fsync support
327 
328 <tr><td>--disable-netcdf-4<td>build netcdf-3 without HDF5 and zlib<td>
329 <tr><td>--disable-netcdf4<td>synonym for disable-netcdf-4
330 <tr><td>--enable-hdf4<td>build netcdf-4 with HDF4 read capability<td>HDF4, HDF5 and zlib
331 <tr><td>--enable-hdf4-file-tests<td>test ability to read HDF4 files<td>selected HDF4 files from Unidata ftp site
332 <tr><td>--enable-pnetcdf<td>build netcdf-4 with parallel I/O for classic and
333  64-bit offset files using parallel-netcdf
334 <tr><td>--enable-extra-example-tests<td>Run extra example tests<td>--enable-netcdf-4,GNU sed
335 <tr><td>--enable-parallel-tests <td>run extra parallel IO tests<td>--enable-netcdf-4, parallel IO support
336 <tr><td>--enable-logging<td>enable logging capability<td>--enable-netcdf-4
337 <tr><td>--disable-dap<td>build without DAP client support.<td>libcurl
338 <tr><td>--disable-dap-remote-tests<td>disable dap remote tests<td>--enable-dap
339 <tr><td>--enable-dap-long-tests<td>enable dap long tests<td>
340 <tr><td>--enable-extra-tests<td>run some extra tests that may not pass because of known issues<td>
341 <tr><td>--enable-ffio<td>use ffio instead of posixio (ex. on the Cray)<td>
342 <tr><td>--disable-examples<td>don't build the netCDF examples during make check
343  (examples are treated as extra tests by netCDF)<td>
344 <tr><td>--disable-v2<td>turn off the netCDF version 2 API<td>
345 <tr><td>--disable-utilities<td>don't build netCDF utilities ncgen, ncdump, and nccopy<td>
346 <tr><td>--disable-testsets<td>don't build or run netCDF tests<td>
347 <tr><td>--enable-large-file-tests <td>Run tests which create very large data
348  files<td>~13 GB disk space required, but recovered when
349  tests are complete). See option --with-temp-large to
350  specify temporary directory
351 <tr><td>--enable-benchmarks<td>Run benchmarks. This is an experimental feature.
352  The benchmarks are extra tests, used to check netCDF performance.
353  <td>sample data files from the Unidata ftp site
354 <tr><td>--disable-extreme-numbers
355 <td>don't use extreme numbers during testing, such as MAX_INT - 1<td>
356 <tr><td>--disable-shared<td>don't build shared libraries<td>
357 <tr><td>--disable-static<td>don't build static libraries<td>
358 <tr><td>--disable-largefile<td>omit support for files larger than 2GB<td>
359 <tr><td>--enable-mmap<td>Use mmap to implement NC_DISKLESS<td>System-provided `mmap` or `mremap` functions
360 <tr><td>--enable-valgrind-tests <td>build with valgrind-tests; static builds only<td>valgrind
361 </table>
362 
363 Build Instructions for netCDF-C using CMake {#netCDF-CMake}
364 ===========================================
365 
366 ## Overview {#cmake_overview}
367 
368 Starting with netCDF-C 4.3.0, we are happy to announce the inclusion of CMake support. CMake will allow for building netCDF on a wider range of platforms, include Microsoft Windows with Visual Studio. CMake support also provides robust unit and regression testing tools. We will also maintain the standard autotools-based build system in parallel.
369 
370 In addition to providing new build options for netCDF-C, we will also provide pre-built binary downloads for the shared versions of netCDF for use with Visual Studio.
371 
372 
373 ## Requirements {#cmake_requirements}
374 The following packages are required to build netCDF-C using CMake.
375 
376 * netCDF-C Source Code
377 * CMake version 2.8.12 or greater.
378 * Optional Requirements:
379  * HDF5 Libraries for netCDF4/HDF5 support.
380  * libcurl for DAP support.
381 
382 <center>
383 <img src="deptree.jpg" height="250px" />
384 </center>
385 
386 ## The CMake Build Process {#cmake_build}
387 
388 There are four steps in the Build Process when using CMake
389 
390 1. Configuration: Before compiling, the software is configured based on the desired options.
391 2. Building: Once configuration is complete, the libraries are compiled.
392 3. Testing: Post-build, it is possible to run tests to ensure the functionality of the netCDF-C libraries.
393 4. Installation: If all tests pass, the libraries can be installed in the location specified during configuration.
394 
395 For users who prefer pre-built binaries, installation packages are available at \ref winbin
396 
397 ### Configuration {#cmake_configuration}
398 
399 The output of the configuration step is a project file based on the appropriate configurator specified. Common configurators include:
400 
401 * Unix Makefiles
402 * Visual Studio
403 * CodeBlocks
404 * ... and others
405 
406 ### Common CMake Options {#cmake_common_options}
407 
408 | **Option** | **Autotools** | **CMake** |
409 | :------- | :---- | :----- |
410 Specify Install Location | --prefix=PREFIX | -D"CMAKE\_INSTALL\_PREFIX=PREFIX"
411 Enable/Disable netCDF-4 | --enable-netcdf-4<br>--disable-netcdf-4 | -D"ENABLE\_NETCDF\_4=ON" <br> -D"ENABLE\_NETCDF\_4=OFF"
412 Enable/Disable DAP | --enable-dap <br> --disable-dap | -D"ENABLE\_DAP=ON" <br> -D"ENABLE\_DAP=OFF"
413 Enable/Disable Utilities | --enable-utilities <br> --disable-utilities | -D"BUILD\_UTILITIES=ON" <br> -D"BUILD\_UTILITIES=OFF"
414 Specify shared/Static Libraries | --enable-shared <br> --enable-static | -D"BUILD\_SHARED\_LIBS=ON" <br> -D"BUILD\_SHARED\_LIBS=OFF"
415 Enable/Disable Tests | --enable-testsets <br> --disable-testsets | -D"ENABLE\_TESTS=ON" <br> -D"ENABLE\_TESTS=OFF"
416 Specify a custom library location | Use *CFLAGS* and *LDFLAGS* | -D"CMAKE\_PREFIX\_PATH=/usr/custom_libs/"
417 
418 A full list of *basic* options can be found by invoking `cmake [Source Directory] -L`. To enable a list of *basic* and *advanced* options, one would invoke `cmake [Source Directory] -LA`.
419 
420 ### Configuring your build from the command line. {#cmake_command_line}
421 
422 The easiest configuration case would be one in which all of the dependent libraries are installed on the system path (in either Unix/Linux or Windows) and all the default options are desired. From the build directory (often, but not required to be located within the source directory):
423 
424 > $ cmake [Source Directory]
425 
426 If you have libraries installed in a custom directory, you may need to specify the **CMAKE\_PREFIX_PATH** variable to tell cmake where the libraries are installed. For example:
427 
428 > $ cmake [Source Directory] -DCMAKE\_PREFIX\_PATH=/usr/custom_libraries/
429 
430 ## Building {#cmake_building}
431 
432 The compiler can be executed directly with 'make' or the appropriate command for the configurator which was used.
433 
434 > $ make
435 
436 Building can also be executed indirectly via cmake:
437 
438 > $ cmake --build [Build Directory]
439 
440 ## Testing {#cmake_testing}
441 
442 Testing can be executed several different ways:
443 
444 > $ make test
445 
446 or
447 
448 > $ ctest
449 
450 or
451 
452 > $ cmake --build [Build Directory] --target test
453 
454 ### Installation {#cmake_installation}
455 
456 Once netCDF has been built and tested, it may be installed using the following commands:
457 
458 > $ make install
459 
460 or
461 
462 > $ cmake --build [Build Directory] --target install
463 
464 ## See Also {#cmake_see_also}
465 
466 For further information regarding netCDF and CMake, see \ref cmake_faq

Return to the Main Unidata NetCDF page.
Generated on Tue Apr 4 2017 06:09:19 for NetCDF. NetCDF is a Unidata library.