1 Getting and Building NetCDF-C {#getting_and_building_netcdf}
2 =============================
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
15 Getting NetCDF {#getting}
16 =========================
18 Getting pre-built NetCDF-C libraries. {#sec_get_pre_built}
19 -------------------------------------
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
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.
30 Pre-release libraries for Windows may be found here: \ref winbin.
32 Getting the latest NetCDF-C Source Code {#sec_get_source}
33 ----------------------------------------
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.
38 Two options are available for building from source:
41 - The developer snapshot.
43 ### The latest release {#sec_latest_release}
45 The latest release may be downloaded from github at the following location:
47 - http://github.com/Unidata/netcdf-c/releases
49 Source files are available in `.tar.gz` and `.zip` formats.
51 ### The developer snapshot {#sec_dev_snapshot}
53 The developer snapshot may be cloned from github directly by using the `git` command.
55 > $ git clone http://github.com/Unidata/netcdf-c netcdf-c
59 > ***The developer snapshot release contains bug-fixes and new
60 features added since the last full release. It may also contain
63 Once you have downloaded and unpacked the distribution, see the
64 following section on \ref building.
66 Building NetCDF {#building}
67 ===========================
69 The netCDF-C library and utilities require third-party libraries for
70 full functionality. (See \ref architecture).
75 - \ref building_netcdf_fortran
76 - \ref configure_options
78 Requirements {#netcdf_requirements}
79 ----------------------------------
81 * HDF5 1.8.9 (netcdf-4 support)
83 * curl 7.18.0 (DAP support)
86 CMake and Windows support {#sub}
87 --------------------------------
92 Building with NetCDF-4 and the Remote Data Client {#build_default}
93 --------------------------------
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.)
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>.
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.
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.
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.
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
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
132 href="http://www.hdfgroup.org/services/support.html">HDF5 help
135 Build zlib like this:
138 $ ./configure --prefix=/home/username/local
142 Then you build HDF5, specifying the location of the zlib library:
145 $ ./configure --with-zlib=/home/username/local --prefix=/home/username/local
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
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.
158 If you are building HDF5 with szip, then include the <CODE>--with-szlib=</CODE>
159 option, with the directory holding the szip library.
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:
166 $ CPPFLAGS=-I/home/username/local/include LDFLAGS=-L/home/username/local/lib ./configure --prefix=/home/username/local
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.
181 Building NetCDF with Classic Library Only {#build_classic}
182 ---------------------------------------
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
192 To build without support for the netCDF-4 formats or the additional
193 netCDF-4 functions, but with remote access, use:
196 $ ./configure --prefix=/home/username/local --disable-netcdf-4
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.)
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
211 $ ./configure --prefix=/home/username/local --disable-dap
215 To build without netCDF-4 support or remote client access, use:
218 $ ./configure --prefix=/home/username/local --disable-netcdf-4 --disable-dap
222 If you get the message that netCDF installed correctly, then you are
225 Building with HDF4 Support {#build_hdf4}
226 ---------------------
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.
231 For this to work, you must build the HDF4 library with the
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
240 Then, when building netCDF-4, use the
244 option to configure. The location for the HDF4 header files and
245 library must be set in the CPPFLAGS and LDFLAGS options.
247 For HDF4 access to work, the library must be build with netCDF-4
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):
255 # Build and install HDF4
256 $ cd ${HDF4_SOURCE_DIRECTORY}
257 $ ./configure --enable-shared --disable-netcdf --disable-fortran --prefix=${H4DIR}
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
269 Building with Parallel I/O Support {#build_parallel}
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.
277 The following works to build HDF5 with parallel I/O on our netCDF
281 CC=mpicc ./configure --enable-parallel
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
294 The following works to build netCDF-4 with parallel I/O on our netCDF
298 $ H5DIR=/where/parallel/HDF5/was/installed
299 $ CPPFLAGS="-I${H5DIR}/include"
301 $ LDFLAGS=-L${H5DIR}/lib
303 $ ./configure --disable-shared --enable-parallel-tests
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.
315 Linking to NetCDF {#linking}
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.
324 For example, one user reports that she can build other applications
325 with netCDF-4 by setting the LIBS environment variable:
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'
331 For shared builds, only -lnetcdf is needed. All other libraries will
332 be found automatically.
334 The ``nc-config --all'' command can be used to learn what options are
335 needed for the local netCDF installation.
337 For example, this works for linking an application named myapp.c with
341 cc -o myapp myapp.c `nc-config --cflags --libs`
344 configure options {#configure_options}
345 -----------------------------
347 These options are used for `autotools`-based builds. For `cmake` options, see
349 Note: --disable prefix indicates that the option is normally enabled.
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.
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>
392 Build Instructions for NetCDF-C using CMake {#netCDF-CMake}
393 ===========================================
395 ## Overview {#cmake_overview}
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.
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.
402 ## Requirements {#cmake_requirements}
403 The following packages are required to build netCDF-C using CMake.
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.
412 <img src="deptree.jpg" height="250px" />
415 ## The CMake Build Process {#cmake_build}
417 There are four steps in the Build Process when using CMake
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.
424 For users who prefer pre-built binaries, installation packages are available at \ref winbin
426 ### Configuration {#cmake_configuration}
428 The output of the configuration step is a project file based on the appropriate configurator specified. Common configurators include:
435 ### Common CMake Options {#cmake_common_options}
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/"
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`.
449 ### Configuring your build from the command line. {#cmake_command_line}
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):
453 > $ cmake [Source Directory]
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:
457 > $ cmake [Source Directory] -DCMAKE\_PREFIX\_PATH=/usr/custom_libraries/
459 ## Building {#cmake_building}
461 The compiler can be executed directly with 'make' or the appropriate command for the configurator which was used.
465 Building can also be executed indirectly via cmake:
467 > $ cmake --build [Build Directory]
469 ## Testing {#cmake_testing}
471 Testing can be executed several different ways:
481 > $ cmake --build [Build Directory] --target test
483 ### Installation {#cmake_installation}
485 Once netCDF has been built and tested, it may be installed using the following commands:
491 > $ cmake --build [Build Directory] --target install
493 ## See Also {#cmake_see_also}
495 For further information regarding NetCDF and CMake, see \ref cmake_faq