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 Building netCDF with Classic Library Only {#build_classic}
181 ---------------------------------------
183 It is possible to build the netCDF C libraries and utilities so that
184 only the netCDF classic and 64-bit offset formats are supported, or
185 the remote data access client is not built. (See \ref netcdf_format
186 for more information about the netCDF format variants. See the <a
187 href="http://www.opendap.org/documentation">DAP documentation and
188 support site</a> for more information about remote client access to
189 data on OPeNDAP servers.)
191 If necessary, set the NCDIR shell variable to indicate where netCDF should be
192 installed. Then to build a netCDF-3 library without support for the
193 netCDF-4 formats or functions, but with remote client access, use:
195 $ # Build and install netCDF-3 from netCDF-4 source
196 $ ./configure --prefix=${NCDIR} --disable-netcdf-4
199 To build with full support for netCDF-4 API's and format but without
200 remote client access, use:
202 $ # Build and install netCDF-4 without DAP client support
203 $ ./configure --prefix=${NCDIR} --disable-dap
206 To build without netCDF-4 support or remote client access, use:
208 $ # Build and install minimal netCDF-3 with no DAP client support
209 $ ./configure --prefix=${NCDIR} --disable-netcdf-4 --disable-dap
212 If you get the message that netCDF installed correctly, then you are
215 Building with HDF4 Support {#build_hdf4}
216 ---------------------
218 The netCDF-4 library can read HDF4 data files, if they were created
219 with the SD (Scientific Data) API.
221 For this to work, you must build the HDF4 library with the
222 configure option <CODE>--disable-netcdf</CODE>
223 to prevent it from building an HDF4 version of the netCDF-2 library
224 that conflicts with the netCDF-2 functions that are built into the Unidata
227 Then, when building netCDF-4, use the <CODE>--enable-hdf4</CODE>.
228 option to configure. The location for the HDF4 header files and
229 library must be specified in the CPPFLAGS and LDFLAGS environment variables
230 or configure options.
232 For HDF4 access to work, the library must be built with netCDF-4
235 Here's an example, assuming the HDF5 library has been built and
236 installed in H5DIR and you will build and install the HDF4 library in
237 H4DIR (which could be the same as H5DIR). From the top-level HDF4
240 $ # Build and install HDF4
241 $ ./configure --enable-shared --disable-netcdf --disable-fortran --prefix=${H4DIR}
245 Then from the top-level netCDF directory:
247 $ # Build and install netCDF-4 with HDF4 access enabled
248 $ CPPFLAGS="-I${H5DIR}/include -I${H4DIR}/include" \
249 LDFLAGS="-L${H5DIR}/lib -L${H4DIR}/lib" \
250 ./configure --enable-hdf4 --enable-hdf4-file-tests
254 Building with Parallel I/O Support {#build_parallel}
257 For parallel I/O to work, HDF5 must be installed with
258 –enable-parallel, and an MPI library (and related libraries) must be
259 made available to the HDF5 configure. This can be accomplished with
260 an mpicc wrapper script.
262 The following works from the top-level HDF5 source directory to build
263 HDF5 with parallel I/O:
265 $ # Build and install HDF5 with parallel support
266 $ CC=mpicc ./configure --enable-parallel --prefix=${H5DIR}
270 If the HDF5 used by netCDF has been built with parallel I/O, then
271 netCDF will also be built with inherited support for parallel
272 I/O. This allows parallel I/O access to netCDF-4/HDF5 files. Note that
273 shared libraries are not supported for parallel HDF5, which makes
274 linking more difficult to get right. (See /ref netcdf_formats for
275 more information about the netCDF format variants.)
277 From the top-level netCDF-4 source directory, the following builds
278 netCDF-4 with parallel I/O, assuming H5DIR specifies where parallel
281 $ # Build, test, and install netCDF-4 with HDF5 parallel support
282 $ CC=mpicc CPPFLAGS=-I${H5DIR}/include LDFLAGS=-L${H5DIR}/lib \
283 ./configure --disable-shared --enable-parallel-tests --prefix=${NCDIR}
287 If parallel I/O access to netCDF classic and 64-bit offset files is
289 [parallel-netcdf library](https://trac.mcs.anl.gov/projects/parallel-netcdf/wiki/WikiStart),
290 referred to as "PnetCDF", must also be installed. Assume it was
291 installed in the directory named by the PNDIR shell variable.
292 Then, from the top-level netCDF-4 source directory, configure netCDF
293 with the "--enable-pnetcdf" option:
295 $ # Build, test, and install netCDF-4 with pnetcdf support
296 $ CC=mpicc CPPFLAGS="-I${H5DIR}/include -I${PNDIR}/include" \
297 LDFLAGS="-L${H5DIR}/lib -L${PNDIR}/lib" ./configure \
298 --disable-shared --enable-pnetcdf --enable-parallel-tests \
303 Linking to netCDF-C {#linking}
306 For static builds of applications that use netCDF-4 you must link to all the libraries,
307 netCDF, HDF5, zlib, szip (if used with HDF5 build), and curl (if the
308 remote access client has not been disabled). This will require -L options
309 to your build for the locations of the libraries, and -l (lower-case
310 L) for the names of the libraries.
312 For example, you might build other applications with netCDF-4 by
313 setting the LIBS environment variable, assuming NCDIR, H5DIR, and ZDIR
314 indicate where netCDF, HDF5, and zlib are installed:
316 LIBS="-L${NCDIR}/lib -lnetcdf -L${H5DIR}/lib -lhdf5_hl -lhdf5 -L${ZDIR}/lib -lz -lm"
318 For shared builds, only <CODE>-L${NCDIR}/lib -lnetcdf</CODE> is
319 needed. All other libraries will be found automatically.
321 The <CODE>pkg-config</CODE> or <CODE>nc-config</CODE> utilities can be
322 used to specify build options for software that uses netCDF. For
323 example, to compile and link an application named myapp.c with a
324 netCDF-C libraries, whether shared or static, you can use
326 $ cc -o myapp myapp.c `nc-config --cflags --libs`
330 $ PKG_CONFIG_PATH=${NCDIR}/lib/pkgconfig:$PKG_CONFIG_PATH
331 $ export PKG_CONFIG_PATH
332 $ cc -o myapp myapp.c `pkg-config --cflags --libs netcdf`
334 configure options {#configure_options}
335 -----------------------------
337 These options are used for `autotools`-based builds. For `cmake` options, see
339 Note: --disable prefix indicates that the option is normally enabled.
341 <tr><th>Option<th>Description<th>Dependencies
342 <tr><td>--disable-doxygen<td>Disable generation of documentation.<td>doxygen
343 <tr><td>--disable-fsync<td>disable fsync support<td>kernel fsync support
344 <tr><td>--enable-valgrind-tests <td>build with valgrind-tests; static builds only<td>valgrind
345 <tr><td>--disable-netcdf-4<td>build netcdf-3 without HDF5 and zlib<td>
346 <tr><td>--disable-netcdf4<td>synonym for disable-netcdf-4
347 <tr><td>--enable-hdf4<td>build netcdf-4 with HDF4 read capability<td>HDF4, HDF5 and zlib
348 <tr><td>--enable-hdf4-file-tests<td>test ability to read HDF4 files<td>selected HDF4 files from Unidata ftp site
349 <tr><td>--enable-pnetcdf<td>build netcdf-4 with parallel I/O for classic and
350 64-bit offset files using parallel-netcdf
351 <tr><td>--enable-extra-example-tests<td>Run extra example tests<td>--enable-netcdf-4,GNU sed
352 <tr><td>--enable-parallel-tests <td>run extra parallel IO tests<td>--enable-netcdf-4, parallel IO support
353 <tr><td>--enable-logging<td>enable logging capability<td>--enable-netcdf-4
354 <tr><td>--disable-dap<td>build without DAP client support.<td>libcurl
355 <tr><td>--disable-dap-remote-tests<td>disable dap remote tests<td>--enable-dap
356 <tr><td>--enable-dap-long-tests<td>enable dap long tests<td>
357 <tr><td>--enable-extra-tests<td>run some extra tests that may not pass because of known issues<td>
358 <tr><td>--enable-ffio<td>use ffio instead of posixio (ex. on the Cray)<td>
359 <tr><td>--disable-examples<td>don't build the netCDF examples during make check
360 (examples are treated as extra tests by netCDF)<td>
361 <tr><td>--disable-v2<td>turn off the netCDF version 2 API<td>
362 <tr><td>--disable-utilities<td>don't build netCDF utilities ncgen, ncdump, and nccopy<td>
363 <tr><td>--disable-testsets<td>don't build or run netCDF tests<td>
364 <tr><td>--enable-large-file-tests <td>Run tests which create very large data
365 files<td>~13 GB disk space required, but recovered when
366 tests are complete). See option --with-temp-large to
367 specify temporary directory<td>
368 <tr><td>--enable-benchmarks<td>Run benchmarks. This is an experimental feature.
369 The benchmarks are extra tests, used to check netCDF performance.
370 <td>sample data files from the Unidata ftp site
371 <tr><td>--disable-extreme-numbers
372 <td>don't use extreme numbers during testing, such as MAX_INT - 1<td>
373 <tr><td>--enable-dll<td>build a win32 DLL<td>mingw compiler
374 <tr><td>--disable-shared<td>don't build shared libraries<td>
375 <tr><td>--disable-static<td>don't build static libraries<td>
376 <tr><td>--disable-largefile<td>omit support for files larger than 2GB<td>
377 <tr><td>--enable-mmap<td>Use mmap to implement NC_DISKLESS<td>
380 Build Instructions for netCDF-C using CMake {#netCDF-CMake}
381 ===========================================
383 ## Overview {#cmake_overview}
385 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.
387 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.
390 ## Requirements {#cmake_requirements}
391 The following packages are required to build netCDF-C using CMake.
393 * netCDF-C Source Code
394 * CMake version 2.8.12 or greater.
395 * Optional Requirements:
396 * HDF5 Libraries for netCDF4/HDF5 support.
397 * libcurl for DAP support.
400 <img src="deptree.jpg" height="250px" />
403 ## The CMake Build Process {#cmake_build}
405 There are four steps in the Build Process when using CMake
407 1. Configuration: Before compiling, the software is configured based on the desired options.
408 2. Building: Once configuration is complete, the libraries are compiled.
409 3. Testing: Post-build, it is possible to run tests to ensure the functionality of the netCDF-C libraries.
410 4. Installation: If all tests pass, the libraries can be installed in the location specified during configuration.
412 For users who prefer pre-built binaries, installation packages are available at \ref winbin
414 ### Configuration {#cmake_configuration}
416 The output of the configuration step is a project file based on the appropriate configurator specified. Common configurators include:
423 ### Common CMake Options {#cmake_common_options}
425 | **Option** | **Autotools** | **CMake** |
426 | :------- | :---- | :----- |
427 Specify Install Location | --prefix=PREFIX | -D"CMAKE\_INSTALL\_PREFIX=PREFIX"
428 Enable/Disable netCDF-4 | --enable-netcdf-4<br>--disable-netcdf-4 | -D"ENABLE\_NETCDF\_4=ON" <br> -D"ENABLE\_NETCDF\_4=OFF"
429 Enable/Disable DAP | --enable-dap <br> --disable-dap | -D"ENABLE\_DAP=ON" <br> -D"ENABLE\_DAP=OFF"
430 Enable/Disable Utilities | --enable-utilities <br> --disable-utilities | -D"BUILD\_UTILITIES=ON" <br> -D"BUILD\_UTILITIES=OFF"
431 Specify shared/Static Libraries | --enable-shared <br> --enable-static | -D"BUILD\_SHARED\_LIBS=ON" <br> -D"BUILD\_SHARED\_LIBS=OFF"
432 Enable/Disable Tests | --enable-testsets <br> --disable-testsets | -D"ENABLE\_TESTS=ON" <br> -D"ENABLE\_TESTS=OFF"
433 Specify a custom library location | Use *CFLAGS* and *LDFLAGS* | -D"CMAKE\_PREFIX\_PATH=/usr/custom_libs/"
435 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`.
437 ### Configuring your build from the command line. {#cmake_command_line}
439 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):
441 > $ cmake [Source Directory]
443 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:
445 > $ cmake [Source Directory] -DCMAKE\_PREFIX\_PATH=/usr/custom_libraries/
447 ## Building {#cmake_building}
449 The compiler can be executed directly with 'make' or the appropriate command for the configurator which was used.
453 Building can also be executed indirectly via cmake:
455 > $ cmake --build [Build Directory]
457 ## Testing {#cmake_testing}
459 Testing can be executed several different ways:
469 > $ cmake --build [Build Directory] --target test
471 ### Installation {#cmake_installation}
473 Once netCDF has been built and tested, it may be installed using the following commands:
479 > $ cmake --build [Build Directory] --target install
481 ## See Also {#cmake_see_also}
483 For further information regarding netCDF and CMake, see \ref cmake_faq