3.5 Running the configure Script
To create the Makefiles needed to build netCDF, you must run the
provided configure script. Go to the top-level netCDF directory.
Decide where you want to install this package. Use this for the
"–prefix=" argument to the configure script below. The default
installation prefix is “/usr/local,” which will install the
package's files in usr/local/bin, usr/local/lib, and
usr/local/man. The default can be overridden with the –prefix
argument to configure.
Here's how to execute the configure script with a different
installation directory:
./configure --prefix=/whatever/you/decided --with-hdf5=/home/ed/local
The above would cause the netCDF libraries to be installed in
/whatever/you/decided/lib, the header files in
/whatever/you/decided/include, the utilities (ncdump/ncgen) in
/whatever/you/decided/bin, and the man pages in
/whatever/you/decided/man.
The –with-hdf5 option tells configure the location of the HDF5 and
zlib libraries. HDF5 must be version 1.8.4-patch1 or better, and the
HDF5 library must have been built with zlib, version 1.2.3 or better.
If the configure script finds HDF5 in the system directories, it will
(attempt to) build the netCDF-4 enhanced features. To turn this off
use the –disable-netcdf-4 option.
There are other options for the configure script. The most useful ones
are listed below. Use the –help option to get the full list.
--prefix
- Specify the directory under which netCDF will be
installed. Subdirectories lib, bin, include, and man will be created
there, if they don't already exist.
--disable-netcdf-4
- Turn off netCDF-4 features, even if HDF5 library is found.
--with-hdf5=/location
- Specify the location of the HDF5 library.
--with-zlib=/location
- Specify the location of the zlib library. NetCDF-4 requires that HDF5
be built with zlib, for variable compression.
--with-szlib=/location
- Optionally specify the location of the szlib (a.k.a. szip)
library. (HDF5 must have been built with szlib support.)
--enable-shared
- Build shared libraries (as well as static) on platforms which support
them.
--enable-dap
- Enable DAP support. This flag is set by default
if the configure script can locate a usable
instance of the curl-config program.
The curl-config program can be specified explicitly
using –with-curl-config=/some/path/curl-config,
or configure will attempt some heuristics to locate
the curl-config program; typically by checking
the PATH environment variable.
If the flag –enable-dap flag is not set to either –enable-dap or
–disable-dap, and a usable curl library can be found,
then DAP support will be enabled by default.
Note that when DAP is enabled, this can be tested for
in a configure script by looking for the function
“nc__opendap”.
--with-curl-config
- This flag may be used to specify the curl-config program
so that DAP support can be enabled.
Note that it should specify the actual program
using something like –with-curl-config=/some/path/curl-config.
--enable-dap-remote-tests
- If DAP support is enabled, then remote tests are
run that utilize the test server at opendap.org.
This option is enabled by default.
Since that server may be inaccessible
for a variety of reasons, these tests may fail,
in which case this flag should be disabled.
--enable-dap-long-tests
- If –enable-dap-remote-tests is enabled, then this
flag can also be enabled to add extra tests that may
take signficant time to execute.
This flag is off by default.
--enable-hdf4
- Turns on the HDF4 read layer. This reads HDF4 files created with the
SD (Scientific Data) API of HDF4. If the HDF4 library is in a
different directory, use the –with-hdf4= option to specify its
location.
--with-hdf4=/your/hdf4/location
- Use the –with-hdf4 option to specify a location for the HDF4
directory, if it is not in any of the system directories, nor in the
same directory as HDF5.
--enable-hdf4-file-tests
- Causes make check to use wget to fetch some HDF4 data files from the
Unidata FTP server, and check that they are properly understood. This
is done as part of automatic netCDF testing, and should not be done by
users.
--enable-pnetcdf
- Allows parallel I/O with classic and 64-bit offset format files, using
the parallel-netcdf (formerly pnetcdf) library from
Argonne/Northwestern. The parallel-netcdf library must be installed,
and a specially modified pnetcdf.h must be used. (Get it at
ftp://ftp.unidata.ucar.edu/pub/netcdf/user/contrib/pnetcdf.h)
--with-udunits
- Builds UDUNITS2 as well as netCDF. The UDUNITS2 package supports units
of physical quantities (e.g., meters, seconds). Specifically, it
supports conversion between string and binary representations of
units, arithmetic manipulation of units, and conversion of numeric
values between compatible units. For more information about UDUNITS,
see: http://www.unidata.ucar.edu/software/udunits/
--disable-largefile
- This omits OS support for large files (i.e. files larger than 2 GB).
--disable-fortran
- Turns off Fortran 77 and Fortran 90 API. (Same as –disable-f77.)
--disable-f77
- This turns off building of the F77 and F90 APIs. (The F90 API cannot
be built without the F77 API). This also disables some of the
configure tests that relate to fortran, including the test of the F90
compiler. Setting the environment variables FC or F77 to NULL will
have the same effect as –disable-f77.
--disable-f90
- This turns off the building of the F90 API. Setting the environment
variable F90 to null for configure will have the same effect.
--disable-cxx
- This turns off the building of the C++ API. Setting the environment
variable CXX to null for configure will have the same effect.
--disable-v2
- This turns of the V2 API. The V2 API is completely replaced with the
V3 API, but is usually built with netCDF for backwards compatibility,
and also because the C++ API depends on the V2 API. Setting this has
the effect of automatically turning off the CXX API, as if
–disable-cxx had also been specified.
--enable-cxx4
- Turns on the new C++ API, which is currently under development, and
will expose the full expanded model in the C++ API. The cxx4 API is
experiemental, unfinished, and untested. It is provided for
experiemental purposes only.
--enable-large-file-tests
- Turn on tests for large files. These tests create files over 2 GB in
size, and need about 13 GB of free disk space to run. These files are
deleted after the test successfully completes. They will be created in
the netCDF nc_test directory, unless the –with-temp-large option is
used to specify another location (see below).
--with-temp-large
- Normally large files are not created during the netCDF build, but they
will be if –enable-large-file-tests is specified (see above). In that
case, this configure parameter can be used to specify a location to
create these large files, for example: –with-large-files=/tmp/ed.
--enable-benchmarks
- Turn on tests of the speed of various netCDF operations. Some of these
operations take a long time to run (minutes, on a reasonable
workstation).
--enable-valgrind-tests
- Causes some tests to be re-run under valgrind, the memory testing
tool. Valgrind must be present for this to work. Also HDF5 must be
built with –enable-using-memchecker, and netCDF must be compiled
without optimization (at least on the Unidata test platform where this
is tested). The valgrind tests are run by shell script
libsrc4/run_valgrind_tests.sh. It simply reruns the test programs in
that directory, using valgrind, and with settings such that any error
reported by valgrind will cause the “make check” to fail.
--disable-fortran-compiler-check
- Normally the netCDF configure checks the F77 and F90 compilers with
small test programs to see if they work. This is very helpful in
supporting netCDF installations on different machines, but won't work
with cross-compilation. Use the –disable-fortran-compiler-check to
turn off the fortran compiler tests, and just assume that the
compilers will work.
--disable-fortran-type-check
- The netCDF configure compiles and runs some programs to test fortran
vs. C type sizes. Setting this option turns off those test, and uses a
set of default values (which can be overridden by environment
variables see Environment).
--disable-compiler-recover
- Normally, if the netCDF configure finds a F90 compiler, and it fails
to build the test program described in –disable-f90-check, it will
print a warning, and then continue to build without the F90 API, as if
the user has specified –disable-f90. With the
–disable-compiler-recover option set, it will not continue, but will
just stop if the fortran 90 compiler doesn't work. This is useful for
automatic testing, where we want the tests to fail if something causes
the fortran compiler to break.
--disable-examples
- Starting with version 3.6.2, netCDF comes with some examples in the
“examples” directory. By default, the examples are all built during
a “make check” unless the –disable-examples option is provided.
--enable-separate-fortran
- This will cause the Fortran 77 and Fortran 90 APIs to be built into
their own separate library, instead of being included in the C
library. This is useful for supporting more than one fortran compiler
with the same netCDF C library. This is turned on by default for
shared library builds.
--enable-extra-tests
- This option may turn on tests which are known to fail (i.e. bugs that
we are currently working to fix).
--with-default-chunk-size
- Change the size (in bytes) that will be used as a target size when
computing default chunksizes for netCDF-4/HDF5 chunked variables.
--default-chunks-in-cache
- Change the number of chunks that are accomodated in the per-variable
chunk caches that are used by default.
--max-default-cache-size
- Change the maximum size of the per-variable chunk caches that are used
by default.
--with-chunk-cache-size
- Change the size of the default file-level chunk cache size that will
be used when opening netCDF-4/HDF5 files.
--with-chunk-cache-nelems
- Change the size of the default file-level chunk cache number of
elements that will be used when opening netCDF-4/HDF5 files. Should be
a prime number.
--with-chunk-cache-preemption
- Change the default preemption of the file-level chunk cache that will
be used when opening netCDF-4/HDF5 files. Must be a number between 0
and 1 (inclusive).
The configure script will examine your computer system – checking for
attributes that are relevant to building the netCDF package. It will
print to standard output the checks that it makes and the results that
it finds.
The configure script will also create the file "config.log", which
will contain error messages from the utilities that the configure
script uses in examining the attributes of your system. Because such
an examination can result in errors, it is expected that "config.log"
will contain error messages. Therefore, such messages do not
necessarily indicate a problem (a better indicator would be failure of
the subsequent "make"). One exception, however, is an error message in
"config.log" that indicates that a compiler could not be started. This
indicates a severe problem in your compilation environment – one that
you must fix. If this occurs, configure will not complete and will
exit with an error message telling you about the problem.