NetCDF  4.4.0-rc2
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 Building netCDF with Classic Library Only {#build_classic}
181 ---------------------------------------
182 
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.)
190 
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:
194 
195  $ # Build and install netCDF-3 from netCDF-4 source
196  $ ./configure --prefix=${NCDIR} --disable-netcdf-4
197  $ make check install
198 
199 To build with full support for netCDF-4 API's and format but without
200 remote client access, use:
201 
202  $ # Build and install netCDF-4 without DAP client support
203  $ ./configure --prefix=${NCDIR} --disable-dap
204  $ make check install
205 
206 To build without netCDF-4 support or remote client access, use:
207 
208  $ # Build and install minimal netCDF-3 with no DAP client support
209  $ ./configure --prefix=${NCDIR} --disable-netcdf-4 --disable-dap
210  $ make check install
211 
212 If you get the message that netCDF installed correctly, then you are
213 done!
214 
215 Building with HDF4 Support {#build_hdf4}
216 ---------------------
217 
218 The netCDF-4 library can read HDF4 data files, if they were created
219 with the SD (Scientific Data) API.
220 
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
225 netCDF library.
226 
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.
231 
232 For HDF4 access to work, the library must be built with netCDF-4
233 features.
234 
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
238 source directory:
239 
240  $ # Build and install HDF4
241  $ ./configure --enable-shared --disable-netcdf --disable-fortran --prefix=${H4DIR}
242  $ make check
243  $ make install
244 
245 Then from the top-level netCDF directory:
246 
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
251  $ make check
252  $ make install
253 
254 Building with Parallel I/O Support {#build_parallel}
255 --------------
256 
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.
261 
262 The following works from the top-level HDF5 source directory to build
263 HDF5 with parallel I/O:
264 
265  $ # Build and install HDF5 with parallel support
266  $ CC=mpicc ./configure --enable-parallel --prefix=${H5DIR}
267  $ make check
268  $ make install
269 
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.)
276 
277 From the top-level netCDF-4 source directory, the following builds
278 netCDF-4 with parallel I/O, assuming H5DIR specifies where parallel
279 HDF5 was installed:
280 
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}
284  $ make check
285  $ make install
286 
287 If parallel I/O access to netCDF classic and 64-bit offset files is
288 needed, an alternate
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:
294 
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 \
299  --prefix=${NCDIR}
300  $ make check
301  $ make install
302 
303 Linking to netCDF-C {#linking}
304 -------------------
305 
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.
311 
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:
315 
316  LIBS="-L${NCDIR}/lib -lnetcdf -L${H5DIR}/lib -lhdf5_hl -lhdf5 -L${ZDIR}/lib -lz -lm"
317 
318 For shared builds, only <CODE>-L${NCDIR}/lib -lnetcdf</CODE> is
319 needed. All other libraries will be found automatically.
320 
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
325 
326  $ cc -o myapp myapp.c `nc-config --cflags --libs`
327 
328 or
329 
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`
333 
334 configure options {#configure_options}
335 -----------------------------
336 
337 These options are used for `autotools`-based builds. For `cmake` options, see
338 
339 Note: --disable prefix indicates that the option is normally enabled.
340 <table>
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>
378 </table>
379 
380 Build Instructions for netCDF-C using CMake {#netCDF-CMake}
381 ===========================================
382 
383 ## Overview {#cmake_overview}
384 
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.
386 
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.
388 
389 
390 ## Requirements {#cmake_requirements}
391 The following packages are required to build netCDF-C using CMake.
392 
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.
398 
399 <center>
400 <img src="deptree.jpg" height="250px" />
401 </center>
402 
403 ## The CMake Build Process {#cmake_build}
404 
405 There are four steps in the Build Process when using CMake
406 
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.
411 
412 For users who prefer pre-built binaries, installation packages are available at \ref winbin
413 
414 ### Configuration {#cmake_configuration}
415 
416 The output of the configuration step is a project file based on the appropriate configurator specified. Common configurators include:
417 
418 * Unix Makefiles
419 * Visual Studio
420 * CodeBlocks
421 * ... and others
422 
423 ### Common CMake Options {#cmake_common_options}
424 
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/"
434 
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`.
436 
437 ### Configuring your build from the command line. {#cmake_command_line}
438 
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):
440 
441 > $ cmake [Source Directory]
442 
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:
444 
445 > $ cmake [Source Directory] -DCMAKE\_PREFIX\_PATH=/usr/custom_libraries/
446 
447 ## Building {#cmake_building}
448 
449 The compiler can be executed directly with 'make' or the appropriate command for the configurator which was used.
450 
451 > $ make
452 
453 Building can also be executed indirectly via cmake:
454 
455 > $ cmake --build [Build Directory]
456 
457 ## Testing {#cmake_testing}
458 
459 Testing can be executed several different ways:
460 
461 > $ make test
462 
463 or
464 
465 > $ ctest
466 
467 or
468 
469 > $ cmake --build [Build Directory] --target test
470 
471 ### Installation {#cmake_installation}
472 
473 Once netCDF has been built and tested, it may be installed using the following commands:
474 
475 > $ make install
476 
477 or
478 
479 > $ cmake --build [Build Directory] --target install
480 
481 ## See Also {#cmake_see_also}
482 
483 For further information regarding netCDF and CMake, see \ref cmake_faq

Return to the Main Unidata NetCDF page.
Generated on Wed Aug 19 2015 17:25:41 for NetCDF. NetCDF is a Unidata library.