NetCDF  4.3.3.1
 All Data Structures Files Functions Variables Typedefs Macros Modules Pages
install.md
1 Getting and Building NetCDF-C {#getting_and_building_netcdf}
2 =============================
3 
4 [TOC]
5 
6 This document is for getting and building the netCDF C library and
7 utilities, version 4.3.0. Other libraries that depend on the netCDF C
8 library, such as the Fortran and C++ libraries, are available as
9 separate distributions that can be built and installed after the C
10 library is successfully installed. The netCDF-Java library is also a
11 separate distribution that is currently independent of the netCDF C
12 library.
13 
14 
15 Getting NetCDF {#getting}
16 =========================
17 
18 Getting pre-built NetCDF-C libraries. {#sec_get_pre_built}
19 -------------------------------------
20 
21 The easiest way to get netCDF is through a package management program,
22 such as rpm, yum, adept, and others. NetCDF is available from many
23 different repositories, including the default Red Hat and Ubuntu
24 repositories.
25 
26 When getting netCDF from a software repository, you will wish to get
27 the development version of the package ("netcdf-devel"). This includes
28 the netcdf.h header file.
29 
30 Pre-release libraries for Windows may be found here: \ref winbin.
31 
32 Getting the latest NetCDF-C Source Code {#sec_get_source}
33 ----------------------------------------
34 
35 Starting with netCDF-C version 4.3.1, the netCDF-C source code is hosted at the
36 Unidata GitHub repository, available at http://github.com/Unidata/netcdf-c.
37 
38 Two options are available for building from source:
39 
40 - The latest release.
41 - The developer snapshot.
42 
43 ### The latest release {#sec_latest_release}
44 
45 The latest release may be downloaded from github at the following location:
46 
47 - http://github.com/Unidata/netcdf-c/releases
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
60 features added since the last full release. It may also contain
61 portability bugs.***
62 
63 Once you have downloaded and unpacked the distribution, see the
64 following section on \ref building.
65 
66 Building NetCDF {#building}
67 ===========================
68 
69 The netCDF-C library and utilities require third-party libraries for
70 full functionality. (See \ref architecture).
71 - \ref build_default
72 - \ref build_classic
73 - \ref build_hdf4
74 - \ref build_parallel
75 - \ref building_netcdf_fortran
76 - \ref configure_options
77 
78 Requirements {#netcdf_requirements}
79 ----------------------------------
80 
81 * HDF5 1.8.9 (netcdf-4 support)
82 * zlib 1.2.5
83 * curl 7.18.0 (DAP support)
84 
85 
86 CMake and Windows support {#sub}
87 --------------------------------
88 
89 - \ref netCDF-CMake
90 - \ref winbin
91 
92 Building with NetCDF-4 and the Remote Data Client {#build_default}
93 --------------------------------
94 
95 The usual way of building netCDF requires the HDF5, zlib, and curl
96 libraries. (And, optionally, the szlib library). Versions required are
97 at least HDF5 1.8.9, zlib 1.2.5, and curl 7.18.0 or later.
98 (Optionally, if building with szlib, get szip 2.0 or later.)
99 
100 HDF5 1.8.9 and zlib 1.2.7 packages are available from the <a
101 href="ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4">netCDF-4 ftp
102 site</a>. If you wish to use the remote data client code, then you
103 will also need libcurl, which can be obtained from the <a
104 href="http://curl.haxx.se/download.html">curl website</a>.
105 
106 Make sure you run ``make check'' for the HDF5 and zlib
107 distributions. They are very well-behaved distributions, but sometimes
108 the build doesn't work (perhaps because of something subtly
109 misconfigured on the target machine). If one of these libraries is not
110 working, netCDF will have serious problems.
111 
112 Note that for building netCDF, it is not necessary to build the HDF5
113 Fortran, C++, or Java API's. Only the HDF5 C library is used.
114 
115 Optionally, you can also build netCDF-4 with the szip library
116 (a.k.a. szlib). NetCDF cannot create szipped data files, but can read
117 HDF5 data files that have used szip.
118 8
119 There are license restrictions on the use of szip, see the section on
120 licensing terms in the <a
121 href="http://www.hdfgroup.org/doc_resource/SZIP/">web page on szip
122 compression in HDF products</a>. These license restrictions seem to
123 apply to commercial users who are writing data. (Data readers are not
124 restricted.) But here at NetCDF World Headquarters, in Sunny Boulder,
125 Colorado, there are no lawyers, only programmers, so please read the
126 szip documents for the license agreement to see how it applies to your
127 situation.
128 
129 If ``make check'' fails for either zlib or HDF5, the problem must be
130 resolved before the netCDF-4 installation can continue. For HDF5
131 problems, see the <a
132 href="http://www.hdfgroup.org/services/support.html">HDF5 help
133 services</a>.
134 
135 Build zlib like this:
136 
137 ~~~
138 $ ./configure --prefix=/home/username/local
139 $ make check install
140 ~~~
141 
142 Then you build HDF5, specifying the location of the zlib library:
143 
144 ~~~
145 $ ./configure --with-zlib=/home/username/local --prefix=/home/username/local
146 $ make check install
147 ~~~
148 
149 In all cases, the installation location specified with the <CODE>--prefix</CODE>
150 option must be different from the source directory where the software
151 is being built.
152 
153 Note that for shared libraries, you may need to add the install
154 directory to the LD_LIBRARY_PATH environment variable. See
155 the <a href="http://www.unidata.ucar.edu/netcdf/docs/faq.html#Shared%20Libraries">netCDF
156 FAQ</a> for more details on using shared libraries.
157 
158 If you are building HDF5 with szip, then include the <CODE>--with-szlib=</CODE>
159 option, with the directory holding the szip library.
160 
161 After HDF5 is done, build netcdf, specifying the location of the
162 HDF5, zlib, and (if built into HDF5) the szip header files and
163 libraries in the CPPFLAGS and LDFLAGS environment variables. For example:
164 
165 ~~~
166 $ CPPFLAGS=-I/home/username/local/include LDFLAGS=-L/home/username/local/lib ./configure --prefix=/home/username/local
167 $ make check install
168 ~~~
169 
170 The configure script will try to find necessary tools in your
171 path. When you run configure you may optionally use the <CODE>--prefix</CODE>
172 argument to change the default installation directory. The above
173 examples install the zlib, HDF5, and netCDF-4 libraries in
174 /home/username/local/lib, the header file in /home/username/local/include, and the
175 utilities in /home/username/local/bin. If you don't provide a <CODE>--prefix</CODE>
176 option, installation will be in /usr/local/, in subdirectories lib/,
177 include/, and bin/. The installation location specified with the
178 <CODE>--prefix</CODE> option must be different from the source directory where the
179 software is being built.
180 
181 Building NetCDF with Classic Library Only {#build_classic}
182 ---------------------------------------
183 
184 It is possible to build the netCDF C libraries and utilities so that
185 only the netCDF classic and 64-bit offset formats are supported, or
186 the remote data access client is not built. (See \ref netcdf_format)
187 for more information about the netCDF format variants. See the <a
188 href="http://opendap.org/netCDF-DAP">netCDF-DAP site</a>
189 for more information about remote client access to data
190 on OPeNDAP servers.)
191 
192 To build without support for the netCDF-4 formats or the additional
193 netCDF-4 functions, but with remote access, use:
194 
195 ~~~
196 $ ./configure --prefix=/home/username/local --disable-netcdf-4
197 $ make check install
198 ~~~
199 
200 (Replace `/home/username/local` with the name of the directory where
201 netCDF is to be installed. The installation location specified with
202 the <CODE>--prefix</CODE> option must be different from the source directory where
203 the software is being built.)
204 
205 Starting with version 4.1.1 the netCDF C libraries and utilities have
206 supported remote data access, using the OPeNDAP protocols. To build
207 with full support for netCDF-4 APIs and format but without remote
208 client access, use:
209 
210 ~~~
211 $ ./configure --prefix=/home/username/local --disable-dap
212 $ make check install
213 ~~~
214 
215 To build without netCDF-4 support or remote client access, use:
216 
217 ~~~
218 $ ./configure --prefix=/home/username/local --disable-netcdf-4 --disable-dap
219 $ make check install
220 ~~~
221 
222 If you get the message that netCDF installed correctly, then you are
223 done!
224 
225 Building with HDF4 Support {#build_hdf4}
226 ---------------------
227 
228 The netCDF-4 library can (since version 4.1) read HDF4 data files, if
229 they were created with the SD (Scientific Data) API.
230 
231 For this to work, you must build the HDF4 library with the
232 configure option
233 ~~~
234  --disable-netcdf
235 ~~~
236 to prevent it from building an HDF4 version of the netCDF-2 library
237 that conflicts with the netCDF-2 functions that are built into the Unidata
238 netCDF library.
239 
240 Then, when building netCDF-4, use the
241 ~~~
242  --enable-hdf4
243 ~~~
244 option to configure. The location for the HDF4 header files and
245 library must be set in the CPPFLAGS and LDFLAGS options.
246 
247 For HDF4 access to work, the library must be build with netCDF-4
248 features.
249 
250 Here's an example, assuming the HDF5 library has been built and
251 installed in H5DIR and you will build and install the HDF4 library in
252 H4DIR (which could be the same as H5DIR):
253 
254 ~~~
255 # Build and install HDF4
256 $ cd ${HDF4_SOURCE_DIRECTORY}
257 $ ./configure --enable-shared --disable-netcdf --disable-fortran --prefix=${H4DIR}
258 $ make
259 $ make install
260 $ # Build and install netCDF with HDF4 access enabled
261 $ cd ${NETCDF_SOURCE_DIRECTORY}
262 $ CPPFLAGS="-I${H5DIR}/include -I${H4DIR}/include" \
263 $ LDFLAGS="-L${H5DIR}/lib -L${H4DIR}/lib" \
264 $ ./configure --enable-hdf4 --enable-hdf4-file-tests
265 $ make check
266 $ make install
267 ~~~
268 
269 Building with Parallel I/O Support {#build_parallel}
270 --------------
271 
272 For parallel I/O to work, HDF5 must be installed with
273 â€“enable-parallel, and an MPI library (and related libraries) must be
274 made available to the HDF5 configure. This can be accomplished with
275 the mpicc wrapper script, in the case of MPICH2.
276 
277 The following works to build HDF5 with parallel I/O on our netCDF
278 testing system:
279 
280 ~~~
281 CC=mpicc ./configure --enable-parallel
282 make check install
283 ~~~
284 
285 If the HDF5 used by netCDF has been built with parallel I/O, then
286 netCDF will also be built with support for parallel I/O. This allows
287 parallel I/O access to netCDF-4/HDF5 files. Note that shared libraries
288 are not supported for parallel HDF5, which makes linking more
289 difficult to get right. "LIBS=-ldl" is also sometimes needed to link
290 successfully with parallel HDF5 libraries.
291 (See /ref netcdf_formats for more information about the netCDF format
292 variants.)
293 
294 The following works to build netCDF-4 with parallel I/O on our netCDF
295 testing system:
296 
297 ~~~
298 $ H5DIR=/where/parallel/HDF5/was/installed
299 $ CPPFLAGS="-I${H5DIR}/include"
300 $ CC=mpicc
301 $ LDFLAGS=-L${H5DIR}/lib
302 $ LIBS=-ldl
303 $ ./configure --disable-shared --enable-parallel-tests
304 $ make check install
305 ~~~
306 
307 
308 If parallel I/O access to netCDF classic and 64-bit offset files is
309 also needed, the parallel-netcdf library should also be installed.
310 (Note: the previously recommended <a
311 href=ftp://ftp.unidata.ucar.edu/pub/netcdf/contrib/pnetcdf.h>replacement
312 pnetcdf.h</a> should no longer be used.) Then configure netCDF with the
313 "--enable-pnetcdf" option.
314 
315 Linking to NetCDF {#linking}
316 -------------------
317 
318 For static build, to use netCDF-4 you must link to all the libraries,
319 netCDF, HDF5, zlib, szip (if used with HDF5 build), and curl (if the
320 remote access client has not been disabled). This will mean -L options
321 to your build for the locations of the libraries, and -l (lower-case
322 L) for the names of the libraries.
323 
324 For example, one user reports that she can build other applications
325 with netCDF-4 by setting the LIBS environment variable:
326 
327 ~~~
328 LIBS='-L/X/netcdf-4.0/lib -lnetcdf -L/X/hdf5-1.8.9/lib -lhdf5_hl -lhdf5 -lz -lm -L/X/szip-2.1/lib -lsz'
329 ~~~
330 
331 For shared builds, only -lnetcdf is needed. All other libraries will
332 be found automatically.
333 
334 The ``nc-config --all'' command can be used to learn what options are
335 needed for the local netCDF installation.
336 
337 For example, this works for linking an application named myapp.c with
338 netCDF-4 libraries:
339 
340 ~~~
341 cc -o myapp myapp.c `nc-config --cflags --libs`
342 ~~~
343 
344 configure options {#configure_options}
345 -----------------------------
346 
347 These options are used for `autotools`-based builds. For `cmake` options, see
348 
349 Note: --disable prefix indicates that the option is normally enabled.
350 <table>
351 <tr><th>Option<th>Description<th>Dependencies
352 <tr><td>--disable-doxygen<td>Disable generation of documentation.<td>doxygen
353 <tr><td>--disable-fsync<td>disable fsync support<td>kernel fsync support
354 <tr><td>--enable-valgrind-tests <td>build with valgrind-tests; static builds only<td>valgrind
355 <tr><td>--enable-netcdf-4<td>build with netcdf-4<td>HDF5 and zlib
356 <tr><td>--enable-netcdf4<td>synonym for enable-netcdf-4
357 <tr><td>--enable-hdf4<td>build netcdf-4 with HDF4 read capability<td>HDF4, HDF5 and zlib
358 <tr><td>--enable-hdf4-file-tests<td>test ability to read HDF4 files<td>selected HDF4 files from Unidata ftp site
359 <tr><td>--enable-pnetcdf<td>build netcdf-4 with parallel I/O for classic and
360  64-bit offset files using parallel-netcdf
361 <tr><td>--enable-extra-example-tests<td>Run extra example tests<td>--enable-netcdf-4,GNU sed
362 <tr><td>--enable-parallel-tests <td>run extra parallel IO tests<td>--enable-netcdf-4, parallel IO support
363 <tr><td>--enable-logging<td>enable logging capability<td>--enable-netcdf-4
364 <tr><td>--disable-dap<td>build without DAP client support.<td>libcurl
365 <tr><td>--disable-dap-remote-tests<td>disable dap remote tests<td>--enable-dap
366 <tr><td>--enable-dap-long-tests<td>enable dap long tests<td>
367 <tr><td>--enable-extra-tests<td>run some extra tests that may not pass because of known issues<td>
368 <tr><td>--enable-ffio<td>use ffio instead of posixio (ex. on the Cray)<td>
369 <tr><td>--disable-examples<td>don't build the netCDF examples during make check
370  (examples are treated as extra tests by netCDF)<td>
371 <tr><td>--disable-v2<td>turn off the netCDF version 2 API<td>
372 <tr><td>--disable-utilities<td>don't build netCDF utilities ncgen, ncdump, and nccopy<td>
373 <tr><td>--disable-testsets<td>don't build or run netCDF tests<td>
374 <tr><td>--enable-large-file-tests <td>Run tests which create very large data
375  files<td>~13 GB disk space required, but recovered when
376  tests are complete). See option --with-temp-large to
377  specify temporary directory<td>
378 <tr><td>--enable-benchmarks<td>Run benchmarks. This is an experimental feature.
379  The benchmarks are a
380  bunch of extra tests, which are timed. We use these
381  tests to check netCDF performance.
382  <td>sample data files from the Unidata ftp site
383 <tr><td>--disable-extreme-numbers
384 <td>don't use extreme numbers during testing, such as MAX_INT - 1<td>
385 <tr><td>--enable-dll<td>build a win32 DLL<td>mingw compiler
386 <tr><td>--disable-shared<td>build shared libraries<td>
387 <tr><td>--disable-static<td>build static libraries<td>
388 <tr><td>--disable-largefile<td>omit support for large files<td>
389 <tr><td>--enable-mmap<td>Use mmap to implement NC_DISKLESS<td>
390 </table>
391 
392 Build Instructions for NetCDF-C using CMake {#netCDF-CMake}
393 ===========================================
394 
395 ## Overview {#cmake_overview}
396 
397 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.
398 
399 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.
400 
401 
402 ## Requirements {#cmake_requirements}
403 The following packages are required to build netCDF-C using CMake.
404 
405 * netCDF-C Source Code
406 * CMake version 2.8.12 or greater.
407 * Optional Requirements:
408  * HDF5 Libraries for netCDF4/HDF5 support.
409  * libcurl for DAP support.
410 
411 <center>
412 <img src="deptree.jpg" height="250px" />
413 </center>
414 
415 ## The CMake Build Process {#cmake_build}
416 
417 There are four steps in the Build Process when using CMake
418 
419 1. Configuration: Before compiling, the software is configured based on the desired options.
420 2. Building: Once configuration is complete, the libraries are compiled.
421 3. Testing: Post-build, it is possible to run tests to ensure the functionality of the netCDF-C libraries.
422 4. Installation: If all tests pass, the libraries can be installed in the location specified during configuration.
423 
424 For users who prefer pre-built binaries, installation packages are available at \ref winbin
425 
426 ### Configuration {#cmake_configuration}
427 
428 The output of the configuration step is a project file based on the appropriate configurator specified. Common configurators include:
429 
430 * Unix Makefiles
431 * Visual Studio
432 * CodeBlocks
433 * ... and others
434 
435 ### Common CMake Options {#cmake_common_options}
436 
437 | **Option** | **Autotools** | **CMake** |
438 | :------- | :---- | :----- |
439 Specify Install Location | --prefix=PREFIX | -D"CMAKE\_INSTALL\_PREFIX=PREFIX"
440 Enable/Disable netCDF-4 | --enable-netcdf-4<br>--disable-netcdf-4 | -D"ENABLE\_NETCDF\_4=ON" <br> -D"ENABLE\_NETCDF\_4=OFF"
441 Enable/Disable DAP | --enable-dap <br> --disable-dap | -D"ENABLE\_DAP=ON" <br> -D"ENABLE\_DAP=OFF"
442 Enable/Disable Utilities | --enable-utilities <br> --disable-utilities | -D"BUILD\_UTILITIES=ON" <br> -D"BUILD\_UTILITIES=OFF"
443 Specify shared/Static Libraries | --enable-shared <br> --enable-static | -D"BUILD\_SHARED\_LIBS=ON" <br> -D"BUILD\_SHARED\_LIBS=OFF"
444 Enable/Disable Tests | --enable-testsets <br> --disable-testsets | -D"ENABLE\_TESTS=ON" <br> -D"ENABLE\_TESTS=OFF"
445 Specify a custom library location | Use *CFLAGS* and *LDFLAGS* | -D"CMAKE\_PREFIX\_PATH=/usr/custom_libs/"
446 
447 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`.
448 
449 ### Configuring your build from the command line. {#cmake_command_line}
450 
451 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):
452 
453 > $ cmake [Source Directory]
454 
455 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:
456 
457 > $ cmake [Source Directory] -DCMAKE\_PREFIX\_PATH=/usr/custom_libraries/
458 
459 ## Building {#cmake_building}
460 
461 The compiler can be executed directly with 'make' or the appropriate command for the configurator which was used.
462 
463 > $ make
464 
465 Building can also be executed indirectly via cmake:
466 
467 > $ cmake --build [Build Directory]
468 
469 ## Testing {#cmake_testing}
470 
471 Testing can be executed several different ways:
472 
473 > $ make test
474 
475 or
476 
477 > $ ctest
478 
479 or
480 
481 > $ cmake --build [Build Directory] --target test
482 
483 ### Installation {#cmake_installation}
484 
485 Once netCDF has been built and tested, it may be installed using the following commands:
486 
487 > $ make install
488 
489 or
490 
491 > $ cmake --build [Build Directory] --target install
492 
493 ## See Also {#cmake_see_also}
494 
495 For further information regarding NetCDF and CMake, see \ref cmake_faq

Return to the Main Unidata NetCDF page.
Generated on Mon Jul 13 2015 07:53:10 for NetCDF. NetCDF is a Unidata library.