mirror of
https://github.com/Unidata/netcdf-c.git
synced 2025-01-18 15:55:12 +08:00
190 lines
7.0 KiB
Plaintext
190 lines
7.0 KiB
Plaintext
/*! \file
|
||
Documentation for getting and building netCDF
|
||
|
||
\page getting Getting NetCDF
|
||
|
||
The easiest way to get netCDF is through a package management program,
|
||
such as rpm, yum, adept, and others. NetCDF is available from many
|
||
different repositories, including the default Red Hat and Ubuntu
|
||
repositories.
|
||
|
||
When getting netCDF from a software repository, you will wish to get
|
||
the development version of the package ("netcdf-devel"). This includes
|
||
the netcdf.h header file.
|
||
|
||
Unfortunately, you may not be able to get a recent version of netCDF
|
||
from a package management system, in which case you must build from
|
||
source code. Get the <a
|
||
href=ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf.tar.gz>source
|
||
distribution for the latest full release</a>. It is the latest,
|
||
fully-tested release.
|
||
|
||
Alternatively, you may wish to try the <a
|
||
href=ftp://ftp.unidata.ucar.edu/pub/netcdf/snapshot/netcdf-4-daily.tar.gz>daily
|
||
snapshot</a>. It is generated nightly at the Unidata Program
|
||
Center. It has passed all tests on our (Linux) test machine, but not
|
||
necessarily all platform compatibility tests.
|
||
|
||
\warning The daily snapshot release contains bug-fixes and new features
|
||
added since the last full release. It may also contain portability
|
||
bugs.
|
||
|
||
Once you have downloaded and unpacked the distribution, see \ref
|
||
building.
|
||
|
||
\page building Building NetCDF
|
||
|
||
The netCDF-C library and utilities requires 3rd party libraries for
|
||
full functionality. (See \ref architecture).
|
||
- \ref build_default
|
||
- \ref build_classic
|
||
- \ref build_hdf4
|
||
- \ref build_parallel
|
||
|
||
\page build_default Building with NetCDF-4 and the Remote Data Client
|
||
|
||
The usual way of building netCDF requires the HDF5, zlib, and curl
|
||
libraries. (And, optionally, the szlib library).
|
||
|
||
Get the HDF5 1.8.7 release. You must also have the zlib compression
|
||
library, version 1.2.5. Both of these packages are available from the
|
||
<a href="ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4">netCDF-4 ftp
|
||
site</a>.
|
||
|
||
Make sure you run ``make check'' for the HDF5 and zlib
|
||
distributions. They are very well-behaved distributions, but sometimes
|
||
the build doesn't work (perhaps because of something subtly
|
||
misconfigured on the target machine). If one of these libraries is not
|
||
working, netCDF will have serious problems.
|
||
|
||
Optionally, you can also build netCDF-4 with the szip 2.0 library
|
||
(a.k.a. szlib). NetCDF cannot create szipped data files, but can read
|
||
HDF5 data files that have used szip.
|
||
|
||
There are license restrictions on the use of szip, see
|
||
the <a href="http://www.hdfgroup.org/HDF5/">HDF5 web page</a>. These
|
||
license restrictions seem to apply to commercial users who are writing
|
||
data. (Data readers are not restricted.) But here at NetCDF World
|
||
Headquarters, in Sunny Boulder, Colorado, there are no lawyers, only
|
||
programmers, so please read the szip documents for the license
|
||
agreement to see how it applies to your situation.
|
||
|
||
If ``make check'' fails for either zlib or HDF5, the problem must be
|
||
resolved before the netCDF-4 installation can continue. For HDF5
|
||
problems, send email to the HDF5 help desk:
|
||
help@hdfgroup.org.
|
||
|
||
Build zlib like this:
|
||
|
||
<code>
|
||
./configure --prefix=/home/ed/local
|
||
make check install
|
||
</code>
|
||
|
||
Then you build HDF5, specifying the location of the zlib library:
|
||
|
||
<code>
|
||
./configure --with-zlib=/home/ed/local --prefix=/home/ed/local
|
||
make check install
|
||
</code>
|
||
|
||
Note that for shared libraries, you may need to add the install
|
||
directory to the LD_LIBRARY_PATH environment variable. See
|
||
the <a href="http://www.unidata.ucar.edu/software/netcdf/docs/faq.html#Shared%20Libraries">netCDF
|
||
FAQ</a> for more details on using shared libraries.
|
||
|
||
If you are building HDF5 with szip, then include the --with-szlib=
|
||
option, with the directory holding the szip library.
|
||
|
||
After HDF5 is done, build netcdf, specifying the location of the
|
||
HDF5, zlib, and (if built into HDF5) the szip header files and
|
||
libraries in the CPPFLAGS and LDFLAGS environment variables.
|
||
|
||
<code>
|
||
CPPFLAGS=-I/home/ed/local/include LDFLAGS=-L/home/ed/local/lib ./configure --prefix=/home/ed/local
|
||
make check install
|
||
</code>
|
||
|
||
The configure script will try to find necessary tools in your
|
||
path. When you run configure you may optionally use the --prefix
|
||
argument to change the default installation directory. The above
|
||
examples install the zlib, HDF5, and netCDF-4 libraries in
|
||
/home/ed/local/lib, the header file in /home/ed/local/include, and the
|
||
utilities in /home/ed/local/bin.
|
||
|
||
\page build_classic Building NetCDF with Classic Library Only
|
||
|
||
It is possible to build the netCDF C libraries and utilities so that
|
||
only the netCDF classic and 64-bit offset formats are support (see
|
||
\ref netcdf_format), and the remote data access client is not built
|
||
(see \ref remote_client).
|
||
|
||
<code>
|
||
./configure --prefix=/home/ed/local --disable-netcdf-4 --disable-dap
|
||
make check install
|
||
</code>
|
||
|
||
(Replace ``/home/ed/local'' with the name of the directory where
|
||
netCDF is to be installed.)
|
||
|
||
If you get the message that netCDF installed correctly, then you are
|
||
done!
|
||
|
||
\page build_hdf4 Building with HDF4 Support
|
||
|
||
The netCDF-4 library can (since version 4.1) read HDF4 data files, if
|
||
they were created with the SD (Scientific Data) API. To enable this
|
||
feature, use the --enable-hdf4 option. The location for the HDF4
|
||
header files and library must be set in the CPPFLAGS and LDFLAGS
|
||
options.
|
||
|
||
For HDF4 access to work, the library must be build with netCDF-4
|
||
features.
|
||
|
||
\page build_parallel Building with Parallel I/O Support
|
||
|
||
For parallel I/O to work, HDF5 must be installed with
|
||
–enable-parallel, and an MPI library (and related libraries) must be
|
||
made available to the HDF5 configure. This can be accomplished with
|
||
the mpicc wrapper script, in the case of MPICH2.
|
||
|
||
The following works to build HDF5 with parallel I/O on our netCDF
|
||
testing system:
|
||
|
||
<code>
|
||
CC=mpicc ./configure --enable-parallel --prefix=/shecky/local_par --with-zlib=/shecky/local_par && make check install
|
||
</code>
|
||
|
||
If the HDF5 used by netCDF has been built with parallel I/O, then
|
||
netCDF will also be built with support for parallel I/O. This allows
|
||
parallel I/O access to netCDF-4/HDF5 files (see /ref netcdf_formats).
|
||
|
||
If parallel I/O access to netCDF classic and 64-bit offset files is
|
||
also needed, the parallel-netcdf library should also be installed,
|
||
(and the <a
|
||
href=ftp://ftp.unidata.ucar.edu/pub/netcdf/contrib/pnetcdf.h>replacement
|
||
pnetcdf.h</a> must be used). Then configure netCDF with the
|
||
--enable-pnetcdf flag.
|
||
|
||
\page linking Linking to NetCDF
|
||
|
||
For static build, to use netCDF-4 you must link to all the libraries,
|
||
netCDF, HDF5, zlib, and (if used with HDF5 build) szip. This will mean
|
||
-L options to your build for the locations of the libraries, and -l
|
||
(lower-case L) for the names of the libraries.
|
||
|
||
For example, one user reports that she can build other applications
|
||
with netCDF-4 by setting the LIBS envoronment variable:
|
||
|
||
<code>
|
||
LIBS='-L/X/netcdf-4.0/lib -lnetcdf -L/X/hdf5-1.8.6/lib -lhdf5_hl -lhdf5 -lz -lm -L/X/szip-2.1/lib -lsz'
|
||
</code>
|
||
|
||
For shared builds, only -lnetcdf is needed. All other libraries will
|
||
be found automatically.
|
||
|
||
The nc-config command can be used to learn what options are needed for
|
||
the local netCDF installation.
|
||
|
||
*/
|