1 Getting and Building netCDF {#getting_and_building_netcdf}
2 =============================
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.
15 Getting netCDF-C {#getting}
16 =========================
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:
23 * Autotools: `--enable-remote-fortran-bootstrap`
24 * CMake: `-DENABLE_REMOTE_FORTRAN_BOOTSTRAP=ON`
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.
28 Getting pre-built netCDF-C libraries. {#sec_get_pre_built}
29 -------------------------------------
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.
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"
41 Instructions for installing and using pre-built libraries for Windows may be found here: \ref winbin.
43 Getting the latest netCDF-C Source Code {#sec_get_source}
44 ----------------------------------------
46 The netCDF-C source code is hosted from the <a href="http://github.com/Unidata/netcdf-c" >Unidata GitHub repository</a>.
49 Two options are available for building from source:
52 * The developer snapshot.
54 ### The latest release {#sec_latest_release}
56 The latest full release may be <a href="http://github.com/Unidata/netcdf-c/releases" >downloaded from GitHub</a>.
58 Source files are available in `.tar.gz` and `.zip` formats.
60 ### The developer snapshot {#sec_dev_snapshot}
62 The developer snapshot may be cloned from GitHub directly by using the `git` command.
64 > $ git clone http://github.com/Unidata/netcdf-c netcdf-c
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.*
70 Building netCDF-C {#building}
71 ===========================
73 The netCDF-C library and utilities require third-party libraries for
74 full functionality. (See \ref architecture).
79 * \ref building_netcdf_fortran
80 * \ref configure_options
82 Requirements {#netcdf_requirements}
83 ----------------------------------
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)
90 CMake and Windows support {#sub}
91 --------------------------------
96 Building with netCDF-4 and the Remote Data Client {#build_default}
97 --------------------------------
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.
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>.
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.
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>.
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
126 href="http://www.hdfgroup.org/services/support.html">HDF5 help
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
133 $ # Build and install zlib
135 $ ./configure --prefix=${ZDIR}
137 $ make install # or sudo make install, if root permissions required
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
143 $ # Build and install HDF5
145 $ ./configure --with-zlib=${ZDIR} --prefix=${H5DIR}
147 $ make install # or sudo make install, if root permissions required
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.
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
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.
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
168 $ # Build and install netCDF-4
170 $ CPPFLAGS=-I${H5DIR}/include LDFLAGS=-L${H5DIR}/lib ./configure --prefix=${NCDIR}
172 $ make install # or sudo make install
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
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.
185 Building netCDF with Classic Library Only {#build_classic}
186 ---------------------------------------
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.)
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:
200 $ # Build and install netCDF-3 from netCDF-4 source
201 $ ./configure --prefix=${NCDIR} --disable-netcdf-4
204 To build with full support for netCDF-4 API's and format but without
205 remote client access, use:
207 $ # Build and install netCDF-4 without DAP client support
208 $ ./configure --prefix=${NCDIR} --disable-dap
211 To build without netCDF-4 support or remote client access, use:
213 $ # Build and install minimal netCDF-3 with no DAP client support
214 $ ./configure --prefix=${NCDIR} --disable-netcdf-4 --disable-dap
217 If you get the message that netCDF installed correctly, then you are
220 Building with HDF4 Support {#build_hdf4}
221 ---------------------
223 The netCDF-4 library can read HDF4 data files, if they were created
224 with the SD (Scientific Data) API.
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
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.
237 For HDF4 access to work, the library must be built with netCDF-4
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
245 $ # Build and install HDF4
246 $ ./configure --enable-shared --disable-netcdf --disable-fortran --prefix=${H4DIR}
250 Then from the top-level netCDF directory:
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
259 Building with Parallel I/O Support {#build_parallel}
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.
267 The following works from the top-level HDF5 source directory to build
268 HDF5 with parallel I/O:
270 $ # Build and install HDF5 with parallel support
271 $ CC=mpicc ./configure --enable-parallel --prefix=${H5DIR}
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.)
282 From the top-level netCDF-4 source directory, the following builds
283 netCDF-4 with parallel I/O, assuming H5DIR specifies where parallel
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}
292 If parallel I/O access to netCDF classic and 64-bit offset files is
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:
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 \
308 Linking to netCDF-C {#linking}
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.
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:
321 LIBS="-L${NCDIR}/lib -lnetcdf -L${H5DIR}/lib -lhdf5_hl -lhdf5 -L${ZDIR}/lib -lz -lm"
323 For shared builds, only <CODE>-L${NCDIR}/lib -lnetcdf</CODE> is
324 needed. All other libraries will be found automatically.
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
331 $ cc -o myapp myapp.c `nc-config --cflags --libs`
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`
339 configure options {#configure_options}
340 -----------------------------
342 These options are used for `autotools`-based builds. For `cmake` options, see
344 Note: --disable prefix indicates that the option is normally enabled.
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>
385 Build Instructions for netCDF-C using CMake {#netCDF-CMake}
386 ===========================================
388 ## Overview {#cmake_overview}
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.
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.
395 ## Requirements {#cmake_requirements}
396 The following packages are required to build netCDF-C using CMake.
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.
405 <img src="deptree.jpg" height="250px" />
408 ## The CMake Build Process {#cmake_build}
410 There are four steps in the Build Process when using CMake
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.
417 For users who prefer pre-built binaries, installation packages are available at \ref winbin
419 ### Configuration {#cmake_configuration}
421 The output of the configuration step is a project file based on the appropriate configurator specified. Common configurators include:
428 ### Common CMake Options {#cmake_common_options}
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/"
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`.
442 ### Configuring your build from the command line. {#cmake_command_line}
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):
446 > $ cmake [Source Directory]
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:
450 > $ cmake [Source Directory] -DCMAKE\_PREFIX\_PATH=/usr/custom_libraries/
452 ## Building {#cmake_building}
454 The compiler can be executed directly with 'make' or the appropriate command for the configurator which was used.
458 Building can also be executed indirectly via cmake:
460 > $ cmake --build [Build Directory]
462 ## Testing {#cmake_testing}
464 Testing can be executed several different ways:
474 > $ cmake --build [Build Directory] --target test
476 ### Installation {#cmake_installation}
478 Once netCDF has been built and tested, it may be installed using the following commands:
484 > $ cmake --build [Build Directory] --target install
486 ## See Also {#cmake_see_also}
488 For further information regarding netCDF and CMake, see \ref cmake_faq