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

Return to the Main Unidata NetCDF page.
Generated on Thu Aug 4 2016 17:55:22 for NetCDF. NetCDF is a Unidata library.