mirror of
https://github.com/Unidata/netcdf-c.git
synced 2024-11-27 07:30:33 +08:00
2001 lines
73 KiB
Plaintext
Executable File
2001 lines
73 KiB
Plaintext
Executable File
\input texinfo @c -*-texinfo-*-
|
|
@comment $Id: netcdf-install.texi,v 1.77 2010/05/13 19:20:09 russ Exp $
|
|
@c %**start of header
|
|
@setfilename netcdf-install.info
|
|
@settitle NetCDF Installation and Porting Guide
|
|
@setcontentsaftertitlepage
|
|
@c Combine the variable, concept, and function indices.
|
|
@synindex vr cp
|
|
@synindex fn cp
|
|
@c %**end of header
|
|
|
|
@c version-install.texi is automatically generated by automake and contains
|
|
@c defined variables VERSION, UPDATED, UPDATED-MONTH.
|
|
@include version-install.texi
|
|
|
|
@c This file contains shared definitions of some vars.
|
|
@include defines.texi
|
|
|
|
@ifinfo
|
|
@dircategory netCDF scientific data format
|
|
@direntry
|
|
* netcdf-install: (netcdf-install). @value{i-man}
|
|
@end direntry
|
|
@end ifinfo
|
|
|
|
@titlepage
|
|
@title @value{i-man}
|
|
@subtitle NetCDF Version @value{VERSION}
|
|
@subtitle Last Updated @value{UPDATED}
|
|
@author Ed Hartnett, Russ Rew, John Caron
|
|
@author Unidata Program Center
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@ifnottex
|
|
@node Top, Binaries, (dir), (dir)
|
|
@top NetCDF Installation and Porting Guide
|
|
|
|
This document describes how to build and install the netCDF library,
|
|
version @value{VERSION} on Unix and Windows systems. This document was
|
|
last updated on @value{UPDATED}.
|
|
|
|
The current stable release of netCDF, version 4.1.3, can be obtained
|
|
from the netCDF web page at @uref{@value{netcdf-url}}. Instructions
|
|
for installing the current stable release version of netCDF can be
|
|
found at @uref{@value{docs-url}}.
|
|
|
|
If netCDF does not build and pass all tests, and you don't find your
|
|
computing platform addressed in this document, then try
|
|
@uref{@value{netcdf-other-builds}} for reports of successful builds of
|
|
this package in environments to which we had no access.
|
|
|
|
For a brief introduction to the netCDF format and utilities see
|
|
@ref{Top, @value{tut-man},, netcdf-tutorial, @value{tut-man}}.
|
|
|
|
For a complete description of the netCDF format and utilities see
|
|
@ref{Top, @value{n-man},, netcdf, @value{n-man}}.
|
|
|
|
Programming guides are available for C (@pxref{Top, @value{c-man},,
|
|
netcdf-c, @value{c-man}}), C++ (@pxref{Top, @value{cxx-man},,
|
|
netcdf-cxx, @value{cxx-man}}), Fortran 77 (@pxref{Top,
|
|
@value{f77-man},, netcdf-f77, @value{f77-man}}), and Fortran 90
|
|
(@pxref{Top, @value{f90-man},, netcdf-f90, @value{f90-man}}). All of
|
|
these documents are available from the netCDF-4 documentation page
|
|
@uref{@value{docs4-url}}.
|
|
|
|
Separate documentation for the netCDF Java library can be found at the
|
|
netCDF-Java website, @uref{@value{netcdf-java-url}}.
|
|
|
|
To learn more about netCDF, see the netCDF website
|
|
@uref{@value{netcdf-url}}.
|
|
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* Binaries:: Getting NetCDF Binaries
|
|
* Quick Instructions:: How to Build, Quickly
|
|
* Building on Unix:: How to Build, with Details
|
|
* Using::
|
|
* Building on Windows:: Building on Windows
|
|
* Build Problems:: What if it Doesn't Work?
|
|
* Combined Index:: Index of Concepts
|
|
|
|
@detailmenu
|
|
--- The Detailed Node Listing ---
|
|
|
|
Building and Installing NetCDF on Unix Systems
|
|
|
|
* Requirements:: What's Needed to Build NetCDF
|
|
* Environment:: Setting the Build Environment
|
|
* 64 Bit:: Building on 64-bit Platforms
|
|
* parallel:: Building with Parallel I/O
|
|
* Configure:: Running configure
|
|
* Make:: Running make
|
|
* Testing:: Testing the Build
|
|
* Installation:: Installing Everything
|
|
* Platform Notes:: Specific Platform Notes
|
|
* Porting Notes:: Porting Notes for New Platforms
|
|
* Source:: Working with the Source Code
|
|
|
|
Using NetCDF on Unix Systems
|
|
|
|
* Linker Flags::
|
|
* Compiler Flags::
|
|
* nc-config::
|
|
|
|
Building and Installing NetCDF on Windows
|
|
|
|
* Prebuilt DLL:: Getting the Prebuilt DLLs
|
|
* Installing DLL:: Installing the DLLs
|
|
* Visual Cplusplus:: Building with VC++ 6.0
|
|
* Using DLL:: Using the DLLs with VC++ 6.0
|
|
* Building with NET:: Building with VC++ .NET
|
|
* Using with NET:: Using with VC++ .NET
|
|
|
|
If Something Goes Wrong
|
|
|
|
* Usual Problems:: Problems which Occur Often
|
|
* Troubleshooting:: Finding the Problem
|
|
* Finding Help:: Getting Support
|
|
* Reporting Problems:: What to Send to Support
|
|
|
|
@end detailmenu
|
|
@end menu
|
|
|
|
@node Binaries, Quick Instructions, Top, Top
|
|
@chapter Installing the NetCDF Binaries
|
|
@cindex binary install
|
|
@cindex installing binary distribution
|
|
@cindex shared libraries, using
|
|
|
|
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.
|
|
|
|
We no longer support pre-built binary distributions from Unidata.
|
|
|
|
After installing a binary distribution from one of the package
|
|
management systems, you will end up with files in 4 subdirectories,
|
|
lib, include, man, and bin.
|
|
|
|
The lib subdirectory holds the netCDF libraries (C, Fortran, and
|
|
C++). The include directory holds the necessary netcdf.h file (for C),
|
|
netcdf.inc (for Fortran), netcdfcpp.h (for C++), and the .mod files
|
|
(for Fortran 90). The bin directory holds the ncgen, ncdump, nccopy,
|
|
and nc-config utilities, and the man directory holds the netCDF
|
|
documentation.
|
|
|
|
When compiling a netCDF program, you will have to tell the linker
|
|
where to find the library (e.g. with the -L option of most C
|
|
compilers), and you will also have to tell the C pre-processor where
|
|
to find the include file (e.g. with the -I option). The nc-config
|
|
utility can be used to determine the right options to use.
|
|
|
|
If you are using shared libraries, you will also have to specify the
|
|
library location for run-time dynamic linking. See your compiler
|
|
documentation. For some general information see the netCDF FAQ ``How
|
|
do I use shared libraries'' at @uref{@value{netcdf-shared-faq-url}}.
|
|
|
|
@node Quick Instructions, Building on Unix, Binaries, Top
|
|
@chapter Quick Instructions for Installing NetCDF on Unix
|
|
@cindex quick unix instructions
|
|
@cindex shared libraries, building
|
|
|
|
Who has time to read long installation manuals these days?
|
|
|
|
When building netCDF-4, you must first decide whether to support the
|
|
use of HDF5 as a storage format.
|
|
|
|
@section Building NetCDF Without HDF5
|
|
|
|
If you don't want netCDF-4/HDF5, then build like this:
|
|
|
|
@example
|
|
./configure --prefix=/home/ed/local --disable-netcdf-4
|
|
make check install
|
|
@end example
|
|
|
|
(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!
|
|
|
|
@section Building NetCDF With HDF5
|
|
|
|
If you want to use the HDF5 storage format, you must have the HDF5
|
|
1.8.6 release. You must also have the zlib compression library,
|
|
version 1.2.5. Both of these packages are available from the netCDF-4
|
|
ftp site at @uref{@value{netcdf4-ftp-site}}.
|
|
|
|
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 HDF5 web
|
|
page: @uref{@value{hdf5-szip-license-url}}. 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 you wish to use szip, get it from the HDF5 download page:
|
|
@uref{@value{hdf5-download-url}}.
|
|
|
|
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:
|
|
@value{hdf5-support-email}.
|
|
|
|
Build zlib like this:
|
|
|
|
@example
|
|
./configure --prefix=/home/ed/local
|
|
make check install
|
|
@end example
|
|
|
|
Then you build HDF5, specifying the location of the zlib library:
|
|
|
|
@example
|
|
./configure --with-zlib=/home/ed/local --prefix=/home/ed/local
|
|
make check install
|
|
@end example
|
|
|
|
Note that for shared libraries, you may need to add the install
|
|
directory to the LD_LIBRARY_PATH environment variable. See the FAQ for
|
|
more details on using shared libraries: @uref{@value{netcdf-faq-url}}.
|
|
|
|
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.
|
|
|
|
@example
|
|
CPPFLAGS=-I/home/ed/local/include LDFLAGS=-L/home/ed/local/lib ./configure --prefix=/home/ed/local
|
|
make check install
|
|
@end example
|
|
|
|
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.
|
|
|
|
The default install root is /usr/local (so there's no need to use the
|
|
prefix argument if you want the software installed there).
|
|
|
|
If HDF5 and zlib are found on your system, they will be used by netCDF
|
|
in the build. To prevent this use the --disable-netcdf-4 argument to
|
|
configure.
|
|
|
|
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:
|
|
|
|
@example
|
|
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'
|
|
@end example
|
|
|
|
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.
|
|
|
|
@section 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.
|
|
|
|
@node Building on Unix, Using, Quick Instructions, Top
|
|
@chapter Building and Installing NetCDF on Unix Systems
|
|
@cindex documents, latest version
|
|
@cindex binary releases
|
|
@cindex earlier netCDF versions
|
|
|
|
The latest version of this document is available at
|
|
@uref{@value{netcdf-install-url}}.
|
|
|
|
This document contains instructions for building and installing the
|
|
netCDF package from source on various platforms. Prebuilt binary
|
|
releases are (or soon will be) available for various platforms from
|
|
@uref{@value{netcdf-binaries-url}}.
|
|
|
|
A good general tutorial on how software is built from source on Linux
|
|
platforms can me found at
|
|
@uref{http://www.tuxfiles.org/linuxhelp/softinstall.html}.
|
|
|
|
@menu
|
|
* Requirements:: What's Needed to Build NetCDF
|
|
* Environment:: Setting the Build Environment
|
|
* 64 Bit:: Building on 64-bit Platforms
|
|
* parallel:: Building with Parallel I/O
|
|
* Configure:: Running configure
|
|
* Make:: Running make
|
|
* Testing:: Testing the Build
|
|
* Installation:: Installing Everything
|
|
* Platform Notes:: Specific Platform Notes
|
|
* Porting Notes:: Porting Notes for New Platforms
|
|
* Source:: Working with the Source Code
|
|
@end menu
|
|
|
|
@node Requirements, Environment, Building on Unix, Building on Unix
|
|
@section Installation Requirements
|
|
@cindex installation requirements
|
|
@cindex large file tests requirements
|
|
@cindex extra_test requirements
|
|
@cindex extra_check requirements
|
|
@cindex enable-large-file-tests
|
|
|
|
If you wish to build from source on a Windows (Win32) platform,
|
|
different instructions apply. @xref{Building on Windows}.
|
|
|
|
Depending on the platform, you may need up to 25 Mbytes of free space
|
|
to unpack, build, and run the tests. You will also need a Standard C
|
|
compiler. If you have compilers for FORTRAN 77, FORTRAN 90, or C++,
|
|
the corresponding netCDF language interfaces may also be built and
|
|
tested. Compilers and associated tools will only be found if they are
|
|
in your path, or if you specify the path and compiler in the
|
|
appropriate environment variable. (Example for csh: setenv
|
|
CC /some/directory/cc).
|
|
|
|
If you want to run the large file tests, you will need about 13 GB of
|
|
free disk space, as some very large files are created. The created
|
|
files are immediately deleted after the tests complete. These large
|
|
file tests are not run unless the --enable-large-file-tests option is
|
|
used with configure. (The --with-temp-large option may also be used to
|
|
specify a directory to create the large files in).
|
|
|
|
Unlike the output from other netCDF test programs, each large test
|
|
program deletes its output before successfully exiting.
|
|
|
|
To use the netCDF-4 features you will also need to have a
|
|
HDF5-1.8.6 release installed. HDF5, in turn, must have been
|
|
built with zlib, version 1.2.5.
|
|
|
|
A tested version of HDF5 and zlib can be found at the netCDF-4 ftp
|
|
site at @uref{@value{netcdf4-ftp-site}}.
|
|
|
|
For more information about HDF5 see the HDF5 web site at
|
|
@uref{@value{hdf5-url}}. For more information about zlib see the zlib
|
|
web site at @uref{@value{zlib-url}}.
|
|
|
|
To use the DAP features you will also need to have a version of
|
|
libcurl (version 7.18.0 or later) installed. Depending on how this
|
|
library was built, you may also need zib (version 1.2.5 or later).
|
|
Information about libcurl may be obtained at @uref{@value{curl-url}}.
|
|
|
|
@node Environment, 64 Bit, Requirements, Building on Unix
|
|
@section Specifying the Environment for Building
|
|
|
|
The netCDF configure script searches your path to find the compilers
|
|
and tools it needed. To use compilers that can't be found in your
|
|
path, set their environment variables.
|
|
|
|
The configure script will use gcc and associated GNU tools if they are
|
|
found. Many users, especially those with performance concerns, will
|
|
wish to use a vendor supplied compiler.
|
|
|
|
For example, on an AIX system, users may wish to use xlc (the AIX
|
|
compiler) in one of its many flavors. Set environment variables
|
|
before the build to achieve this.
|
|
|
|
For example, to change the C compiler, set CC to xlc (in sh: export
|
|
CC=xlc). (But don't forget to also set CXX to xlC, or else configure
|
|
will try to use g++, the GNU C++ compiler to build the netCDF C++
|
|
API. Similarly set FC to xlf90 so that the Fortran APIs are built
|
|
properly.)
|
|
|
|
By default, the netCDF library is built with assertions turned on. If
|
|
you wish to turn off assertions, set CPPFLAGS to -DNDEBUG (csh ex:
|
|
setenv CPPFLAGS -DNDEBUG).
|
|
|
|
If GNU compilers are used, the configure script sets CPPFLAGS to ``-g
|
|
-O2''. If this is not desired, set CPPFLAGS to nothing, or to whatever
|
|
other value you wish to use, before running configure.
|
|
|
|
For cross-compiles, the following environment variables can be used to
|
|
override the default fortran/C type settings like this (in sh):
|
|
|
|
@example
|
|
export NCBYTE_T=''integer(selected_int_kind(2))''
|
|
export NCSHORT_T=''integer*2''
|
|
export NF_INT1_T=''integer(selected_int_kind(2))''
|
|
export NF_INT2_T=''integer*2''
|
|
export NF_INT1_IS_C_SHORT=1
|
|
export NF_INT2_IS_C_SHORT=1
|
|
export NF_INT_IS_C_INT=1
|
|
export NF_REAL_IS_C_FLOAT=1
|
|
export NF_DOUBLEPRECISION_IS_C_DOUBLE=1
|
|
@end example
|
|
|
|
In this case you will need to run configure with
|
|
--disable-fortran-compiler-check and --disable-fortran-type-check.
|
|
|
|
@subsection Variable Description Notes
|
|
|
|
@multitable @columnfractions .20 .20 .60
|
|
|
|
@item CC
|
|
@tab C compiler
|
|
@tab If you don't specify this, the configure script will try to
|
|
find a suitable C compiler. The default choice is gcc. If you wish to
|
|
use a vendor compiler you must set CC to that compiler, and set other
|
|
environment variables (as described below) to appropriate settings.
|
|
|
|
@item FC
|
|
@tab Fortran compiler (if any)
|
|
@tab If you don't specify this, the configure script will try to find a
|
|
suitable Fortran and Fortran 77 compiler. Set FC to "" explicitly, or
|
|
provide the --disable-f77 option to configure, if no Fortran interface
|
|
(neither F90 nor F77) is desired. Use --disable-f90 to disable the
|
|
netCDF Fortran 90 API, but build the netCDF Fortran 77 API.
|
|
|
|
@item F77
|
|
@tab Fortran 77 compiler (if any)
|
|
@tab Only specify this if your platform explicitly needs a different
|
|
Fortran 77 compiler. Otherwise use FC to specify the Fortran compiler.
|
|
If you don't specify this, the configure script will try to find a
|
|
suitable Fortran compiler. For vendor compilers, make sure you're
|
|
using the same vendor's Fortran 90 compiler. Using Fortran compilers
|
|
from different vendors, or mixing vendor compilers with g77, the GNU
|
|
F77 compiler, is not supported and may not work.
|
|
|
|
@item CXX
|
|
@tab C++ compiler
|
|
@tab If you don't specify this, the configure script will try to find a
|
|
suitable C++ compiler. Set CXX to "" explicitly, or use the
|
|
--disable-cxx configure option, if no C++ interface is desired. If
|
|
using a vendor C++ compiler, use that vendor's C compiler to compile
|
|
the C interface. Using different vendor compilers for C and C++ may
|
|
not work.
|
|
|
|
@item CFLAGS
|
|
@tab C compiler flags
|
|
@tab "-O" or "-g", for example.
|
|
|
|
@item CPPFLAGS
|
|
@tab C preprocessor options
|
|
@tab "-DNDEBUG" to omit assertion checks, for example.
|
|
|
|
@item FCFLAGS
|
|
@tab Fortran 90 compiler flags
|
|
@tab "-O" or "-g", for example. These flags will be used for FORTRAN
|
|
90. If setting these you may also need to set FFLAGS for the FORTRAN
|
|
77 test programs.
|
|
|
|
@item FFLAGS
|
|
@tab Fortran 77 compiler flags
|
|
@tab "-O" or "-g", for example. If you need to pass the same arguments
|
|
to the FORTRAN 90 build, also set FCFLAGS.
|
|
|
|
@item CXXFLAGS
|
|
@tab C++ compiler flags
|
|
@tab "-O" or "-g", for example.
|
|
|
|
@item ARFLAGS, NMFLAGS, FPP, M4FLAGS, LIBS, FLIBS, FLDFLAGS
|
|
@tab Miscellaneous
|
|
@tab One or more of these were needed for some platforms, as specified
|
|
below. Unless specified, you should not set these environment
|
|
variables, because that may interfere with the configure script.
|
|
|
|
@end multitable
|
|
|
|
The section marked Tested Systems below contains a list of systems on
|
|
which we have built this package, the environment variable settings we
|
|
used, and additional commentary.
|
|
|
|
@node 64 Bit, parallel, Environment, Building on Unix
|
|
@section Building on 64 Bit Platforms
|
|
@cindex 64-bit platforms
|
|
@cindex SunOS 64-bit build
|
|
@cindex AIX 64-bit build
|
|
|
|
The compiler options for SunOS, Irix, and AIX are listed below. The
|
|
zlib and HDF5 libraries must also be built with 64-bit options.
|
|
|
|
@table @code
|
|
|
|
@item AIX
|
|
Set -q64 option in all compilers, and set NMFLAGS to -X64, and AR_FLAGS
|
|
to '-X64 cru'. Alternatively, set environment variable OBJECT_MODE to
|
|
64 before running configure.
|
|
|
|
@item IRIX
|
|
Set the -64 option in all compilers.
|
|
|
|
@item SunOS
|
|
Use the -xarch=v9 or -m64 flag on all compilers for Sparc, or -m64 on
|
|
x86 platforms.
|
|
|
|
@end table
|
|
|
|
@node parallel, Configure, 64 Bit, Building on Unix
|
|
@section Building on Platforms with Parallel I/O
|
|
@cindex parallel platforms
|
|
@cindex MPICH2
|
|
@cindex --enable-parallel-tests
|
|
|
|
NetCDF makes available the parallel I/O features of HDF5 and the
|
|
parallel-netcdf libraries, allowing parallel I/O from netCDF-4 linked
|
|
programs.
|
|
|
|
@subsection Building HDF5 for Parallel I/O
|
|
|
|
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:
|
|
|
|
@example
|
|
CC=mpicc ./configure --enable-parallel --prefix=/shecky/local_par --with-zlib=/shecky/local_par --disable-shared && make check install
|
|
@end example
|
|
|
|
@subsection The parallel-netcdf Library
|
|
|
|
Optionally, the parallel-netcdf library should also be installed, and
|
|
the replacement for pnetcdf.h should be copied from
|
|
ftp://ftp.unidata.ucar.edu/pub/netcdf/contrib/pnetcdf.h.
|
|
|
|
@subsection Building NetCDF
|
|
|
|
To build netCDF with parallel I/O, build as usual, but point the
|
|
configure at a version of HDF5 that has been built for parallel I/O.
|
|
|
|
@example
|
|
CPPFLAGS=-I/shecky/local_par/include
|
|
CXXFLAGS=-I/shecky/local_par/include
|
|
FFFLAGS=-I/shecky/local_par/include
|
|
FCFLAGS=-I/shecky/local_par/include LDFLAGS=-L/shecky/local_par/lib
|
|
FC=mpif90 CXX=mpicxx CC=mpicc ./configure
|
|
make check install
|
|
@end example
|
|
|
|
To enable the parallel tests, specify --enable-parallel-tests as an
|
|
option to configure. These tests will be run as mpiexec calls. This
|
|
may not be appropriate on all systems, especially those which use some
|
|
queue for jobs.
|
|
|
|
To use parallel-netcdf to perform parallel I/O on classic and 64-bit
|
|
offset files, use the --enable-pnetcdf option.
|
|
|
|
For parallel builds the netCDF examples are not built. This is to
|
|
avoid cluttering them with MPI_Init/Finalize calls.
|
|
|
|
@node Configure, Make, parallel, Building on Unix
|
|
@section Running the configure Script
|
|
@cindex configure, running
|
|
@cindex running configure
|
|
@cindex install directory
|
|
@cindex prefix argument of configure
|
|
@cindex config.log
|
|
|
|
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:
|
|
|
|
@example
|
|
./configure --prefix=/whatever/you/decided
|
|
@end example
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
@vtable @code
|
|
|
|
@item --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.
|
|
|
|
@item --disable-netcdf-4
|
|
Turn off netCDF-4 features, even if HDF5 library is found.
|
|
|
|
@item --disable-shared
|
|
Build static libraries only.
|
|
|
|
@item --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''.
|
|
|
|
@item --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.
|
|
|
|
@item --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.
|
|
|
|
@item --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.
|
|
|
|
@item --enable-hdf4
|
|
Turns on the HDF4 read layer. This reads HDF4 files created with the
|
|
SD (Scientific Data) API of HDF4.
|
|
|
|
@item --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.
|
|
|
|
@item --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)
|
|
|
|
@item --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/
|
|
|
|
@item --disable-largefile
|
|
This omits OS support for large files (i.e. files larger than 2 GB).
|
|
|
|
@item --disable-fortran
|
|
Turns off Fortran 77 and Fortran 90 API. (Same as --disable-f77.)
|
|
|
|
@item --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.
|
|
|
|
@item --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.
|
|
|
|
@item --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.
|
|
|
|
@item --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.
|
|
|
|
@item --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.
|
|
|
|
@item --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).
|
|
|
|
@item --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.
|
|
|
|
@item --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).
|
|
|
|
@item --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.
|
|
|
|
@item --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 @pxref{Environment}).
|
|
|
|
@item --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.
|
|
|
|
@item --enable-extra-tests
|
|
This option may turn on tests which are known to fail (i.e. bugs that
|
|
we are currently working to fix).
|
|
|
|
@item --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.
|
|
|
|
@item --default-chunks-in-cache
|
|
Change the number of chunks that are accomodated in the per-variable
|
|
chunk caches that are used by default.
|
|
|
|
@item --max-default-cache-size
|
|
Change the maximum size of the per-variable chunk caches that are used
|
|
by default.
|
|
|
|
@item --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.
|
|
|
|
@item --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.
|
|
|
|
@item --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).
|
|
|
|
@end vtable
|
|
|
|
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.
|
|
|
|
@node Make, Testing, Configure, Building on Unix
|
|
@section Running make
|
|
@cindex make, running
|
|
@cindex running make
|
|
|
|
Run "make". This will build one or more netCDF libraries. It will
|
|
build the basic netCDF library libnetcdf.a. If you have Fortran 77 or
|
|
Fortran 90 compilers, then the Fortran library will also be built
|
|
(libnetcdff.a). If you have a C++ compiler, then the C++ interface
|
|
will be built (libnetcdf_c++.a.)
|
|
|
|
A ``make'' will also build the netCDF utilities ncgen(1) and
|
|
ncdump(1).
|
|
|
|
Run make like this:
|
|
@example
|
|
make
|
|
@end example
|
|
|
|
@node Testing, Installation, Make, Building on Unix
|
|
@section Testing the Build
|
|
@cindex tests, running
|
|
@cindex make test
|
|
@cindex make check
|
|
@cindex large file tests
|
|
@cindex enable-large-file-tests
|
|
@cindex testing large file features
|
|
@cindex TEMP_LARGE
|
|
@cindex make slow_check
|
|
@cindex make lfs_test
|
|
@cindex make all_large_tests
|
|
|
|
Run ``make check'' to verify that the netCDF library and executables
|
|
have been built properly (you can instead run ``make test'' which does
|
|
the same thing).
|
|
|
|
A make check will build and run various test programs that test the C,
|
|
Fortran, and C++ interfaces as well as the "ncdump" and "ncgen"
|
|
utility programs.
|
|
|
|
Lines in the output beginning with "***" report on success or failure
|
|
of the tests; any failures will be reported before halting the
|
|
test. Compiler and linker warnings during the testing may be ignored.
|
|
|
|
Run the tests like this:
|
|
|
|
@example
|
|
make check
|
|
@end example
|
|
|
|
If you plan to use the 64-bit offset format (introduced in version
|
|
3.6.0) or the netCDF-4/HDF5 format to create very large files
|
|
(i.e. with variables larger than 2 GB), you should probably specify the
|
|
--enable-large-file-tests to configure, which tests the large file
|
|
features. You must have 13 GB of free disk space for these tests to
|
|
successfully run.
|
|
|
|
If you are running the large file tests, you may wish to use the
|
|
--with-temp-large option to specify a temporary directory for the
|
|
large files. (You may also set the environment variable TEMP_LARGE
|
|
before running configure).
|
|
|
|
The default is to create the large files in the nc_test subdirectory
|
|
of the netCDF build.
|
|
|
|
Run the large file tests like this:
|
|
|
|
@example
|
|
./configure --enable-large-file-tests --with-temp-large=/home/ed/tmp
|
|
make check
|
|
@end example
|
|
|
|
All of the large files are removed on successful completion of
|
|
tests. If the test fails, you may wish to make sure that no large
|
|
files have been left around.
|
|
|
|
If any of the the large file tests test fail, check to ensure that
|
|
your file system can handle files larger than 2 GiB by running the
|
|
following command:
|
|
|
|
@example
|
|
dd if=/dev/zero bs=1000000 count=3000 of=$(TEMP_LARGE)/largefile
|
|
@end example
|
|
|
|
If your system does not have a /dev/zero, this test will fail. Then
|
|
you need to find some other way to create a file larger than 2 GiB to
|
|
ensure that your system can handle them.
|
|
|
|
@xref{Build Problems}.
|
|
|
|
@node Installation, Platform Notes, Testing, Building on Unix
|
|
@section Installing NetCDF
|
|
@cindex make install
|
|
@cindex installing netCDF
|
|
@cindex _LARGE_FILES, on AIX
|
|
@cindex OBJECT_MODE, on AIX
|
|
|
|
To install the libraries and executables, run "make install". This
|
|
will install to the directory specified in the configure step.
|
|
|
|
Run the installation like this:
|
|
|
|
@example
|
|
make install
|
|
@end example
|
|
|
|
The install will put files in the following subdirectories of the
|
|
directory you provided as a prefix, creating the subdirectories if
|
|
needed:
|
|
|
|
@table @code
|
|
|
|
@item lib
|
|
Libraries will be installed here. If static libraries are built,
|
|
without separate fortran libraries, then libnetcdf.a and libnetcdf.la
|
|
will be installed. If the C++ API is built, libnetcdf_c++.a and
|
|
libnetcdf_c++.la will be added. If separate fortran libraries are
|
|
built, libnetcdff.a and libnetcdff.la will also be added.
|
|
|
|
Static library users should ignore the .la files, and link to the .a
|
|
files.
|
|
|
|
Shared library builds will add some .so files to this directory, as
|
|
well.
|
|
|
|
@item include
|
|
Header files will be installed here. The C library header file is
|
|
netcdf.h. If the C++ library is built, ntcdfcpp.h, ncvalues.h and
|
|
netcdf.hh will be installed here. If the F77 API is built, netcdf.inc
|
|
will be copied here. If the F90 API is built, the netcdf.mod and
|
|
typesizes.mod files will be copied here as well.
|
|
|
|
@item bin
|
|
Utilities ncdump and ncgen will be installed here.
|
|
|
|
@item man
|
|
The ncdump/ncgen man pages will be installed in subdirectory man1, and
|
|
the three man pages netcdf.3, netcdf_f77.3, and netcdf_f90.3 will be
|
|
installed in the man3 subdirectory.
|
|
|
|
@item share
|
|
If the configure is called with the --enable-docs option, the netCDF
|
|
documentation set will be built, and will be installed under the share
|
|
directory, under the netcdf subdirectory. This will include
|
|
postscript, PDF, info and text versions of all netCDF manuals. These
|
|
manuals are also available at the netCDF web site.
|
|
|
|
@end table
|
|
|
|
Try linking your applications. Let us know if you have problems
|
|
(@pxref{Reporting Problems}).
|
|
|
|
@node Platform Notes, Porting Notes, Installation, Building on Unix
|
|
@section Platform Specific Notes
|
|
@cindex Cygwin, building with
|
|
@cindex AIX, building on
|
|
@cindex HPUX, building on
|
|
@cindex Irix, building on
|
|
@cindex Linux, building on
|
|
@cindex Macintosh, building on
|
|
@cindex OSF1, building on
|
|
@cindex SunOS, building on
|
|
@cindex Intel fortran
|
|
@cindex fortran, Intel
|
|
@cindex Portland Group fortran
|
|
@cindex fortran, Portland Group
|
|
|
|
The following platform-specific note may be helpful when building and
|
|
installing netCDF. Consult your vendor manuals for information about
|
|
the options listed here. Compilers can change from version to version;
|
|
the following information may not apply to your platform.
|
|
|
|
Full output from some of the platforms of the test platforms for
|
|
netCDF @value{VERSION} can be found at @uref{@value{netcdf-builds}}.
|
|
|
|
@subsection AIX
|
|
|
|
We found the vendor compilers in /usr/vac/bin, and included this
|
|
in our PATH. Compilers were xlc, xlf, xlf90, xlC.
|
|
|
|
The F90 compiler requires the qsuffix option to believe that F90 code
|
|
files can end with .f90. This is automatically turned on by configure
|
|
when needed:
|
|
|
|
@example
|
|
FCFLAGS=-qsuffix=f=f90
|
|
@end example
|
|
|
|
We had to use xlf for F77 code, and xlf90 for F90 code.
|
|
|
|
To compile 64-bit code, set the appropriate environment variables
|
|
(documented below).
|
|
|
|
The environment variable OBJECT_MODE can be set to 64, or use the -q64
|
|
option on all AIX compilers by setting CFLAGS, FFLAGS, and CXXFLAGS to
|
|
-q64.
|
|
|
|
The following is also necessary on an IBM AIX SP system for 64-bit
|
|
mode:
|
|
@example
|
|
AR_FLAGS='-X64 cru'
|
|
NMFLAGS='-X64'
|
|
@end example
|
|
|
|
There are thread-safe versions of the AIX compilers. For example,
|
|
xlc_r is the thread-safe C compiler. To use thread-safe compilers,
|
|
override the configure script by setting CC to xlc_r; similarly for FC
|
|
and CXX.
|
|
|
|
For large file support, AIX requires that the macro _LARGE_FILES be
|
|
defined. The configure script does this using
|
|
AC_SYS_LARGEFILES. Unfortunately, this misfires when OBJECT_MODE is
|
|
64, or the q64 option is used. The netCDF tries to fix this by turning
|
|
on _LARGE_FILES anyway in these cases.
|
|
|
|
The GNU C compiler does not mix successfully with the AIX fortran
|
|
compilers.
|
|
|
|
@subsection Cygwin
|
|
|
|
NetCDF builds under Cygwin tools on Windows just as with Linux.
|
|
|
|
@subsection HPUX
|
|
|
|
The HP Fortran compiler (f77, a.k.a. fort77, also f90) requires FLIBS
|
|
to include -lU77 for the fortran tests to work. The configure script
|
|
does this automatically.
|
|
|
|
For the c89 compiler to work, CPPFLAGS must include
|
|
-D_HPUX_SOURCE. This isn't required for the cc compiler. The configure
|
|
script adds this as necessary.
|
|
|
|
For large file support, HP-UX requires _FILE_OFFSET_BITS=64. The
|
|
configure script sets this automatically.
|
|
|
|
The HPUX C++ compiler doesn't work on netCDF code. It's too old for
|
|
that. So either use GNU to compile netCDF, or skip the C++ code by
|
|
setting CXX to '' (in csh: setenv CXX '').
|
|
|
|
Building a 64 bit version may be possible with the following settings:
|
|
@example
|
|
CC=/bin/cc
|
|
CPPFLAGS='-D_HPUX_SOURCE -D_FILE_OFFSET_BITS=64' # large file support
|
|
CFLAGS='-g +DD64' # 64-bit mode
|
|
FC=/opt/fortran90/bin/f90 # Fortran-90 compiler
|
|
FFLAGS='-w +noppu +DA2.0W' # 64-bit mode, no "_" suffixes
|
|
FLIBS=-lU77
|
|
CXX='' # no 64-bit mode C++ compiler
|
|
@end example
|
|
|
|
Sometimes quotas or configuration causes HPUX disks to be limited to 2
|
|
GiB files. In this cases, netCDF cannot create very large
|
|
files. Rather confusingly, HPUX returns a system error that indicates
|
|
that a value is too large to be stored in a type. This may cause
|
|
scientists to earnestly check for attempts to write floats or doubles
|
|
that are too large. In fact, the problem seems to be an internal
|
|
integer problem, when the netCDF library attempts to read beyond the 2
|
|
GiB boundary. To add to the confusion, the boundary for netCDF is
|
|
slightly less than 2 GiB, since netCDF uses buffered I/O to improve
|
|
performance.
|
|
|
|
@subsection Irix
|
|
|
|
A 64-bit version can be built by setting the appropriate environment
|
|
variables.
|
|
|
|
Build 64-bit by setting CFLAGS, FFLAGS, and CXXFLAGS to -64.
|
|
|
|
On our machine, there is a /bin/cc and a /usr/bin/cc, and the -64
|
|
option only works with the former.
|
|
|
|
@subsection Linux
|
|
|
|
The gFortran flag is required with GNU fortran:
|
|
@example
|
|
CPPFLAGS=-DgFortran
|
|
@end example
|
|
|
|
For Portland Group Fortran, set pgiFortran instead:
|
|
@example
|
|
CPPFLAGS=-DpgiFortran
|
|
@end example
|
|
|
|
Portland Group F90/F95 does not mix with GNU g77.
|
|
|
|
The netCDF configure script should notice which fortran compiler is
|
|
being used, and set these automatically.
|
|
|
|
For large file support, _FILE_OFFSET_BITS must be set to 64. The
|
|
netCDF configure script should set this automatically.
|
|
|
|
@subsection Macintosh
|
|
|
|
The gFortran flag is required with GNU fortran
|
|
(CPPFLAGS=-DgFortran). The NetCDF configure script should and set
|
|
this automatically.
|
|
|
|
For IBM compilers on the Mac, the following may work (we lack this
|
|
test environment):
|
|
@example
|
|
CC=/usr/bin/cc
|
|
CPPFLAGS=-DIBMR2Fortran
|
|
F77=xlf
|
|
FC=xlf90
|
|
FCFLAGS=-qsuffix=cpp=f90
|
|
@end example
|
|
|
|
@subsection OSF1
|
|
|
|
NetCDF builds out of the box on OSF1.
|
|
|
|
@subsection SunOS
|
|
|
|
PATH should contain /usr/ccs/bin to find make, nm, ar, etc.
|
|
|
|
For large file support, _FILE_OFFSET_BITS must be 64, also
|
|
_LARGEFILE64_SOURCE and _LARGEFILE_SOURCE must be set. Configure will
|
|
turn this on automatically for netCDF, but not for HDF5. So when
|
|
building HDF5, set these variables before running configure, or HDF5
|
|
will not be capable of producing large files.
|
|
|
|
To compile in 64-bit mode, set -m64 (formerly -xarch=v9, which works
|
|
on SPARC platforms only) on all compilers (i.e. in CFLAGS, FFLAGS,
|
|
FCFLAGS, and CXXFLAGS).
|
|
|
|
When compiling with GNU Fortran (g77), the -DgFortran flag is
|
|
required for the Fortran interface to work. The NetCDF configure
|
|
script turns this on automatically if needed.
|
|
|
|
@subsection Handling Fortran Compilers
|
|
|
|
Commercial fortran compilers will generally require at least one flag
|
|
in the CPPFLAGS variable. The netCDF configure script tries to set
|
|
this for you, but won't try if you have used --disable-flag-setting,
|
|
or if you have already set CPPFLAGS, CFLAGS, CXXFLAGS, FCFLAGS, or
|
|
FFLAGS yourself.
|
|
|
|
The first thing to try is to set nothing and see if the netCDF
|
|
configure script finds your fortran compiler, and sets the correct
|
|
flags automatically.
|
|
|
|
If it doesn't find the correct fortran compiler, you can next try
|
|
setting the FC environment variable to the compiler you wish to use,
|
|
and then see if the configure script can set the correct flags for
|
|
that compiler.
|
|
|
|
If all that fails, you must set the flags yourself.
|
|
|
|
The Intel compiler likes the pgiFortran flag, as does the Portland
|
|
Group compiler. (Automatically turned on if your fortran compiler is
|
|
named ``ifort'' or ``pgf90'').
|
|
|
|
Alternatively, Intel has provided a web page on ``Building netCDF with
|
|
the Intel compilers'' at
|
|
@uref{http://www.intel.com/support/performancetools/sb/CS-027812.htm},
|
|
providing instructions for building netCDF (without using the
|
|
pgiFortran flag).
|
|
|
|
The Portland Group also has a ``PGI Guide to NetCDF'' at
|
|
@uref{http://www.pgroup.com/resources/netcdf/netcdf362_pgi71.htm}.
|
|
|
|
@node Porting Notes, Source, Platform Notes, Building on Unix
|
|
@section Additional Porting Notes
|
|
@cindex GNU make
|
|
@cindex porting notes, additional
|
|
@cindex CRAY, porting to
|
|
@cindex ncconfig.h
|
|
@cindex ncconfig.in
|
|
@cindex ncconfig.inc
|
|
@cindex ncio
|
|
@cindex ncx.m4
|
|
@cindex ffio.c
|
|
@cindex posixio.c
|
|
@cindex big endian
|
|
@cindex little endian
|
|
|
|
The configure and build system should work on any system which has a
|
|
modern "sh" shell, "make", and so on. The configure and build system
|
|
is less portable than the "C" code itself, however. You may run into
|
|
problems with the "include" syntax in the Makefiles. You can use GNU
|
|
make to overcome this, or simply manually include the specified files
|
|
after running configure.
|
|
|
|
Instruction for building netCDF on other platforms can be found at
|
|
@uref{@value{netcdf-other-builds}}. If you build netCDF on a new
|
|
platform, please send your environment variables and any other
|
|
important notes to @value{netcdf-support-email} and we will add the
|
|
information to the other builds page, with a credit to you.
|
|
|
|
If you can't run the configure script, you will need to create
|
|
config.h and fortran/nfconfig.inc. Start with ncconfig.in and
|
|
fortran/nfconfig.in and set the defines as appropriate for your
|
|
system.
|
|
|
|
Operating system dependency is isolated in the "ncio" module. We
|
|
provide two versions. posixio.c uses POSIX system calls like "open()",
|
|
"read()" and "write(). ffio.c uses a special library available on
|
|
CRAY systems. You could create other versions for different operating
|
|
systems. The program "t_ncio.c" can be used as a simple test of this
|
|
layer.
|
|
|
|
Note that we have not had a Cray to test on for some time. In
|
|
particular, large file support is not tested with ffio.c.
|
|
|
|
Numerical representation dependency is isolated in the "ncx"
|
|
module. As supplied, ncx.m4 (ncx.c) supports IEEE floating point
|
|
representation, VAX floating point, and CRAY floating
|
|
point. BIG_ENDIAN vs LITTLE_ENDIAN is handled, as well as various
|
|
sizes of "int", "short", and "long". We assume, however, that a "char"
|
|
is eight bits.
|
|
|
|
There is a separate implementation of the ncx interface available as
|
|
ncx_cray.c which contains optimizations for CRAY vector
|
|
architectures. Move the generic ncx.c out of the way and rename
|
|
ncx_cray.c to ncx.c to use this module. By default, this module does
|
|
not use the IEG2CRAY and CRAY2IEG library calls. When compiled with
|
|
aggressive in-lining and optimization, it provides equivalent
|
|
functionality with comparable speed and clearer error semantics. If
|
|
you wish to use the IEG library functions, compile this module with
|
|
-DUSE_IEG.
|
|
|
|
@node Source, , Porting Notes, Building on Unix
|
|
@section Contributing to NetCDF Source Code Development
|
|
|
|
Most users will not be interested in working directly with the netCDF
|
|
source code. Rather, they will write programs which call netCDF
|
|
functions, and delve no further. However some intrepid users may wish
|
|
to dig into the netCDF code to study it, to try and spot bugs, or to
|
|
make modifications for their own purposes.
|
|
|
|
To work with the netCDF source code, several extra utilities are
|
|
required to fully build everything from source. If you are going to
|
|
modify the netCDF source code, you will need some or all of the
|
|
following Unix tools.
|
|
|
|
@ftable @code
|
|
|
|
@item m4
|
|
Macro processing language used heavily in libsrc, nc_test. Generates
|
|
(in these cases) C code from m4 source. Version 1.4 works fine with
|
|
release 3.5.1 through 3.6.2.
|
|
|
|
@item flex and yacc
|
|
Used in ncgen directory to parse CDL files. Generates C files from .y
|
|
and .l files. You only need to use this to modify ncgen's understanding of
|
|
CDL grammar.
|
|
|
|
@item makeinfo
|
|
Generates all documentation formats (except man pages) from texinfo
|
|
source. I'm using makeinfo version 4.8, as of release 3.6.2. If you
|
|
have trouble with makeinfo, upgrade to this version and try again. You
|
|
only need makeinfo if you want to modify the documentation.
|
|
|
|
@item tex
|
|
Knuth's venerable typesetting system. The version I am running (for
|
|
netCDF release 3.6.2) is TeX 3.141592 (Web2C 7.5.4). I have found that
|
|
some recent installations of TeX will not build the netCDF
|
|
documentation - it's not clear to me why.
|
|
|
|
The user generally will just want to download the latest version of
|
|
netCDF documents at the netCDF website. @uref{@value{docs-url}}.
|
|
|
|
@item autoconf
|
|
Generates the configure script. Version 2.59 or later is required.
|
|
|
|
@item automake
|
|
Since version 3.6.2 of netCDF, automake is used to generate the
|
|
Makefile.in files needed by the configure script to build the
|
|
Makefiles.
|
|
|
|
@item libtool
|
|
Since version 3.6.2 of netCDF, libtool is used to help generate shared
|
|
libraries platforms which support them. Version 2.1a of libtool is
|
|
required.
|
|
|
|
@item sed
|
|
This text processing tool is used to process some of the netCDF
|
|
examples before they are included in the tutorial. This is only needed
|
|
to build the documentation, which the user generally will not need to
|
|
do.
|
|
|
|
@end ftable
|
|
|
|
NetCDF has a large and enterprising user community, and a long history
|
|
of accepting user modifications into the netCDF code base. Examples
|
|
include the 64-bit offset format, and the F90 API.
|
|
|
|
All suggested changes and additions to netCDF code can be sent to
|
|
@value{netcdf-support-email}.
|
|
|
|
@node Using, Building on Windows, Building on Unix, Top
|
|
@chapter Using NetCDF on Unix Systems
|
|
@cindex link options
|
|
@cindex compiler flags
|
|
@cindex nc-config
|
|
|
|
To use netCDF you must link to the netCDF library, and, if using the
|
|
netCDF-4/HDF5 features, also two HDF5, at least one compression
|
|
library, and (on some systems) the math library.
|
|
|
|
@menu
|
|
* Linker Flags::
|
|
* Compiler Flags::
|
|
* nc-config::
|
|
@end menu
|
|
|
|
@node Linker Flags, Compiler Flags, Using, Using
|
|
@section Using Linker Flags with NetCDF
|
|
|
|
For this to work, you have to tell the linker which libraries to link
|
|
to (with the -l option), and where to find them (with the -L option).
|
|
|
|
Use the -L option to your linker to pass the directories in which
|
|
netCDF, HDF5, and zlib are installed.
|
|
|
|
Use the -l (lower-case L) option to list the libraries, which must be
|
|
listed in the correct order:
|
|
|
|
@example
|
|
-lnetcdf -lhdf5_hl -lhdf5 -lz -lm
|
|
@end example
|
|
|
|
If szip was used when building HDF5, you must also use -lsz.
|
|
|
|
On some systems you must also include -lm for the math library.
|
|
|
|
If HDF4 was used when building netCDF, you must also use -lmfhdf -ldf
|
|
-ljpeg.
|
|
|
|
Finally, if you use the parallel-netcdf library, you must use
|
|
-lpnetcdf.
|
|
|
|
The worst case scenario is, using all of the above libraries:
|
|
|
|
@example
|
|
-lnetcdf -lpnetcdf -lmfhdf -ldf -ljpeg -lhdf5_hl -lhdf5 -lz -lsz -lm
|
|
@end example
|
|
|
|
In such a case one also needs to provide the locations of the
|
|
libraries, with the -L flag. If libraries are installed in the same
|
|
directory, this is easier.
|
|
|
|
Use the nc-config to learn the exact flags needed on your system
|
|
(@pxref{nc-config}).
|
|
|
|
@node Compiler Flags, nc-config, Linker Flags, Using
|
|
@section Using Compiler Flags with NetCDF
|
|
|
|
Depending on how netCDF was built, you may need to use compiler flags
|
|
when building your code. For example, many systems build both 32-bit
|
|
and 64-bit binaries. The GNU C compiler, for example, uses -m32 and
|
|
-m64 as compiler flags for this purpose.
|
|
|
|
If netCDF is built with the default compiler flags (i.e. no special
|
|
flags are used), then no flags need to be used by the user.
|
|
|
|
If netCDF is built using flags that control architecture or other
|
|
important aspects of the binary output, then those flags may need to
|
|
be set by all users as well.
|
|
|
|
@node nc-config, , Compiler Flags, Using
|
|
@section Using the nc-config Utility to Find Compiler and Linker Flags
|
|
|
|
To assist with the setting of compiler and linker flags, the nc-config
|
|
utility is provided with netCDF. The nc-config utility is a very
|
|
simple script which contains the settings of the C and Fortran flags
|
|
used during the netCDF build.
|
|
|
|
For example, the nc-config command can be used to get the command line
|
|
options needed to link a C program to netCDF:
|
|
|
|
@example
|
|
nc-config --libs
|
|
-L/usr/local/lib -lnetcdf -L/shecky/local_post/lib -lhdf5_hl -lhdf5 -lz
|
|
@end example
|
|
|
|
The nc-config utility can also be used to learn about the features of
|
|
the current netCDF installation. For example, it can show whether
|
|
netCDF-4 is available:
|
|
|
|
@example
|
|
./nc-config --has-nc4
|
|
yes
|
|
@end example
|
|
|
|
Use the --help option to nc-config for a full list of available
|
|
information.
|
|
|
|
@node Building on Windows, Build Problems, Using, Top
|
|
@chapter Building and Installing NetCDF on Windows
|
|
@cindex windows, building on
|
|
@cindex VC++
|
|
@cindex NET
|
|
@cindex DLL
|
|
@cindex Microsoft
|
|
|
|
NetCDF can be built and used from a variety of development
|
|
environments on Windows. The netCDF library is implemented as a
|
|
Windows dynamic link library (DLL). The simplest way to get started
|
|
with netCDF under Windows is to download the pre-built DLL from the
|
|
Unidata web site.
|
|
|
|
Building under the Cygwin port of GNU tools is treated as a Unix
|
|
install. @xref{Platform Notes}.
|
|
|
|
Instructions are also given for building the netCDF DLL from the
|
|
source code.
|
|
|
|
VC++ documentation being so voluminous, finding the right information
|
|
can be a chore. There's a good discussion of using DLLs called ``About
|
|
Dynamic-Link Libraries'' at (perhaps)
|
|
@uref{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/dynamic_link_libraries.asp}.
|
|
|
|
From the .NET point of view, the netCDF dll is unmanaged code. As a
|
|
starting point, see the help topic ``Consuming Unmanaged DLL
|
|
Functions'' which may be found at
|
|
@uref{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconConsumingUnmanagedDLLFunctions.asp},
|
|
unless the page has been moved.
|
|
|
|
@menu
|
|
* Prebuilt DLL:: Getting the Prebuilt DLLs
|
|
* Installing DLL:: Installing the DLLs
|
|
* Visual Cplusplus:: Building with VC++ 6.0
|
|
* Using DLL:: Using the DLLs with VC++ 6.0
|
|
* Building with NET:: Building with VC++ .NET
|
|
* Using with NET:: Using with VC++ .NET
|
|
@end menu
|
|
|
|
@node Prebuilt DLL, Installing DLL, Building on Windows, Building on Windows
|
|
@section Getting Prebuilt netcdf.dll
|
|
@cindex binaries, windows
|
|
@cindex dll, getting
|
|
|
|
We have pre-built Win32 binary versions of the netcdf dll and static
|
|
library, as well as ncgen.exe and ncdump.exe (dll and static
|
|
versions). You can get them from
|
|
@uref{@value{windows-ftp-site}/netcdf-3.6.1-beta1-win32dll.zip}.
|
|
(Note: we don't have a C++ interface here).
|
|
|
|
@node Installing DLL, Visual Cplusplus, Prebuilt DLL, Building on Windows
|
|
@section Installing the DLL
|
|
@cindex netcdf.dll, location
|
|
@cindex netcdf.lib
|
|
@cindex ncgen, windows location
|
|
@cindex ncdump, windows location
|
|
|
|
Whether you get the pre-built DLL or build your own, you'll then have
|
|
to install it somewhere so that your other programs can find it and
|
|
use it.
|
|
|
|
To install a DLL, you just have to leave it in some directory, and
|
|
(possibly) tell your compiler in which directory to look for it.
|
|
|
|
A DLL is a library, and functions just like libraries under the Unix
|
|
operating system. As with any library, the point of the netCDF DLL is
|
|
to provide functions that you can call from your own code. When you
|
|
compile that code, the linker needs to be able to find the library,
|
|
and then it pulls out the functions that it needs. In the Unix world,
|
|
the -L option tells the compiler where to look for a library. In
|
|
Windows, library search directories can be added to the project's
|
|
property dialog.
|
|
|
|
Similarly, you will need to put the header file, netcdf.h, somewhere
|
|
that you compiler can find it. In the Unix world, the -I option tells
|
|
the compiler to look in a certain directory to find header files. In
|
|
the Windows world, you set this in the project properties dialog box
|
|
of your integrated development environment.
|
|
|
|
Therefore, installing the library means nothing more than copying the
|
|
DLL somewhere that your compiler can find it, and telling the compiler
|
|
where to look for them.
|
|
|
|
The standard place to put DLLs is Windows\System32 folder (for
|
|
Windows2000/XP) or the Windows\System folder (for Windows 98/ME). If
|
|
you put the DLL there, along with the ncgen and ncdump executables,
|
|
you will be able to use the DLL and utilities without further work,
|
|
because compilers already look there for DLLs and EXEs.
|
|
|
|
Instead of putting the DLL and EXEs into the system directory, you can
|
|
leave them wherever you want, and every development project that uses
|
|
the dll will have to be told to search the netCDF directory when it's
|
|
linking, or, the chosen directory can be added to your path.
|
|
|
|
On the .NET platform, you can also try to use the global assembly
|
|
cache. (To learn how, see MSDN topic ``Global Assembly Cache'', at
|
|
@uref{www.msdn.microsoft.com}).
|
|
|
|
Following Windows conventions, the netCDF files belong in the
|
|
following places:
|
|
|
|
@multitable @columnfractions .25 .50 .25
|
|
|
|
@item File(s) @tab Description @tab Location
|
|
|
|
@item netcdf.dll @tab C and Fortran function in DLL
|
|
@tab Windows\System (98/ME) or Windows\System32 (2000/XP)
|
|
|
|
@item netcdf.lib @tab Library file
|
|
@tab Windows\System (98/ME) or Windows\System32 (2000/XP)
|
|
|
|
@item ncgen.exe, ncdump.exe @tab NetCDF utilities
|
|
@tab Windows\System (98/ME) or Windows\System32 (2000/XP)
|
|
|
|
@item netcdf-3 @tab netCDF source code
|
|
@tab Program Files\Unidata
|
|
|
|
@end multitable
|
|
|
|
@node Visual Cplusplus, Using DLL, Installing DLL, Building on Windows
|
|
@section Building netcdf.dll with VC++ 6.0
|
|
@cindex VC++ 6.0, building with
|
|
|
|
The most recent releases of netCDF aren't tested under VC++ 6.0. (They
|
|
are tested with VC++.NET). Older versions of the library, notably
|
|
3.5.0, did compile with VC++ 6.0, and the instructions for doing so
|
|
are presented below.
|
|
|
|
Note that the introduction of better large file support (for files
|
|
larger than 2 GiB) in version 3.6.0 and greater requires an off_t type
|
|
of 8 bytes, and it's not clear how, or if, this can be found in VC++
|
|
6.0.
|
|
|
|
To build the library yourself, get the file
|
|
@value{windows-ftp-site}/netcdf-3.5.0.win32make.VC6.zip
|
|
|
|
The makefiles there describe how to build netcdf-3.5
|
|
using the using Microsoft Visual C++ 6.x and (optionally)
|
|
Digital Visual Fortran 6.x. Because of difficulties in getting
|
|
Microsoft Visual Studio to fall in line with our existing
|
|
source directory scheme, we chose _not_ to build the system
|
|
"inside" Visual Studio. Instead, we provide a simple group
|
|
of "msoft.mak" files which can be used. If you
|
|
wish to work in Visual Studio, go ahead. Read the
|
|
section called "Macros" at the end of this discussion.
|
|
|
|
As of this writing, we have not tried compiling the
|
|
C++ interface in this environment.
|
|
|
|
nmake is a Microsoft version of make, which comes with VC 6.0 (and VC
|
|
7.0) in directory C:\Program Files\Microsoft Visual Studio\VC98\Bin
|
|
(or, for VC 7.0, C:\Program Files\Microsoft Visual Studio .NET
|
|
2003\Vc7\bin).
|
|
|
|
To build netcdf, proceed as follows:
|
|
|
|
@table @code
|
|
|
|
@item unpack source distribution.
|
|
|
|
@item copy netcdf-3.5.0.win32make.VC6.zip
|
|
copy netcdf-3.5.0.win32make.VC6.zip into the netcdf-3.5.0/src
|
|
directory, and unzip it from there.
|
|
|
|
@item cd src\libsrc; nmake /f msoft.mak
|
|
Run this command in src\libsrc. This will build netcdf.lib and
|
|
netcdf.dll Note: This makefiles make DLLs. To make static libraries
|
|
see section on static libraries.
|
|
|
|
@item nmake /f msoft.mak test
|
|
Optionally, in src\libsrc, make and run the simple test.
|
|
|
|
@item cd ..\fortran; nmake /f msoft.mak
|
|
Optionally build the fortran interface and rebuild dll in ..\libsrc to
|
|
include the fortran interface. Note Bene: We don't provide a .DEF
|
|
file, so this step changes the "ordinals" by which entry points in the
|
|
DLL found. Some sites may wish to modify the msoft.mak file(s) to
|
|
produce a separate library for the fortran interface.
|
|
|
|
@item nmake /f msoft.mak test
|
|
(necessary if you want to use fortran code) While you are in
|
|
src\fortran; nmake /f msoft.mak test This tests the netcdf-2 fortran
|
|
interface.
|
|
|
|
@item cd ..\nctest; nmake /f msoft.mak test
|
|
(optional, but recommended) In src\nctest; nmake /f msoft.mak test
|
|
This tests the netcdf-2 C interface.
|
|
|
|
@item cd ..\nc_test; nmake /f msoft.mak test
|
|
(optional, but highly recommended) In src\nc_test; nmake /f msoft.mak
|
|
test This tortures the netcdf-3 C interface.
|
|
|
|
@item cd ..\nf_test; nmake /f msoft.mak test
|
|
(optional, but highly recommended if you built the fortran interface)
|
|
In src\nf_test; nmake /f msoft.mak test This tortures the netcdf-3
|
|
fortran interface.
|
|
|
|
@item ..\ncdump; nmake /f msoft.mak
|
|
In src\ncdump; nmake /f msoft.mak This makes ncdump.exe.
|
|
|
|
@item ..\ncgen; nmake /f msoft.mak
|
|
In src\ncgen; nmake /f msoft.mak This makes ncgen.exe.
|
|
|
|
@item ..\ncdump; nmake /f msoft.mak test
|
|
(optional) In src\ncdump; nmake /f msoft.mak test This tests
|
|
ncdump. Both ncgen and ncdump need to be built prior to this
|
|
test. Note the makefile sets the path so that ..\libsrc\netcdf.dll can
|
|
be located.
|
|
|
|
@item ..\ncgen; nmake /f msoft.mak test
|
|
(optional) In src\ncgen; nmake /f msoft.mak test This tests
|
|
ncgen. Both ncgen and ncdump need to be built prior to this test. Note
|
|
the makefile sets the path so that ..\libsrc\netcdf.dll can be
|
|
located.
|
|
|
|
@item To Install
|
|
Copy libsrc\netcdf.lib to a LIBRARY directory.
|
|
Copy libsrc\netcdf.h and fortran/netcdf.inc to an INCLUDE directory.
|
|
Copy libsrc\netcdf.dll, ncdump/ncdump.exe, and ncgen/ncgen.exe to
|
|
a BIN directory (someplace in your PATH).
|
|
|
|
@end table
|
|
|
|
@node Using DLL, Building with NET, Visual Cplusplus, Building on Windows
|
|
@section Using netcdf.dll with VC++ 6.0
|
|
@cindex VC++ 6.0, using netcdf with
|
|
|
|
To use the netcdf.dll:
|
|
|
|
1. Place these in your include directory:
|
|
netcdf.h C include file
|
|
netcdf.inc Fortran include file
|
|
|
|
2a. To use the Dynamic Library (shared) version of the netcdf library:
|
|
Place these in a directory that's in your PATH:
|
|
netcdf.dll library dll
|
|
ncgen.exe uses the dll
|
|
ncdump.exe uses the dll
|
|
|
|
Place this in a library directory to link against:
|
|
netcdf.lib library
|
|
|
|
2b. Alternatively, to use a static version of the library
|
|
|
|
Place this in a library directory to link against:
|
|
netcdfs.lib library
|
|
|
|
Place these in a directory that's in your PATH:
|
|
ncgens.exe statically linked (no DLL needed)
|
|
ncdumps.exe statically linked (no DLL needed)
|
|
|
|
@node Building with NET, Using with NET, Using DLL, Building on Windows
|
|
@section Building netcdf.dll with VC++.NET
|
|
@cindex VC++.NET, building with
|
|
@cindex release directory, windows
|
|
@cindex debug directory, windows
|
|
@cindex testing, for windows
|
|
@cindex windows testing
|
|
@cindex windows large file tests
|
|
@cindex large file tests, for windows
|
|
@cindex quick_large_files, in VC++.NET
|
|
|
|
To build the netCDF dll with VC++.NET open the win32/NET/netcdf.sln
|
|
file with Visual Studio. Both Debug and Release configurations are
|
|
available - select one and build.
|
|
|
|
The resulting netcdf.dll file will be in subdirectory Release or
|
|
Debug.
|
|
|
|
The netCDF tests will be built and run as part of the build
|
|
process. The Fortran 77 interface will be built, but not the Fortran
|
|
90 or C++ interfaces.
|
|
|
|
Unfortunately, different fortran compilers require different flag
|
|
settings in the netCDF configuration files. (In UNIX builds, this is
|
|
handled by the configure script.)
|
|
|
|
The quick_large_files test program is provided as an extra project,
|
|
however it is not run during the build process, but can be run from
|
|
the command line or the IDE. Note that, despite its name, it is not
|
|
quick. On Unix systems, this program runs in a few seconds, because of
|
|
some features of the Unix file system apparently not present in
|
|
Windows. Nonetheless, the program does run, and creates (then deletes)
|
|
some very large files. (So make sure you have at least 15 GiB of space
|
|
available). It takes about 45 minutes to run this program on our
|
|
Windows machines, so please be patient.
|
|
|
|
@node Using with NET, , Building with NET, Building on Windows
|
|
@section Using netcdf.dll with VC++.NET
|
|
@cindex VC++.NET, using netcdf with
|
|
@cindex visual studio 2003 properties
|
|
|
|
Load-time linking to the DLL is the most straightforward from
|
|
C++. This means the netcdf.lib file has to end up on the compile
|
|
command line. This being Windows, that's hidden by a GUI.
|
|
|
|
In Visual Studio 2003 this can be done by modifying three of the
|
|
project's properties.
|
|
|
|
Open the project properties window from the project menu. Go to the
|
|
linker folder and look at the general properties. Modify the property
|
|
``Additional Library Directories'' by adding the directory which
|
|
contains the netcdf.dll and netcdf.lib files. Now go to the linker
|
|
input properties and set the property ``Additional Dependencies'' to
|
|
netcdf.lib.
|
|
|
|
Finally, still within the project properties window, go to the C/C++
|
|
folder, and look at the general properties. Modify ``Additional
|
|
Include Directories'' to add the directory with the netcdf.h file.
|
|
|
|
Now use the netCDF functions in your C++ code. Of course any C or C++
|
|
file that wants to use the functions will need:
|
|
|
|
@example
|
|
#include <netcdf.h>
|
|
@end example
|
|
|
|
@node Build Problems, Combined Index, Building on Windows, Top
|
|
@chapter If Something Goes Wrong
|
|
|
|
The netCDF package is designed to build and install on a wide variety
|
|
of platforms, but doesn't always. It's a crazy old world out there,
|
|
after all.
|
|
|
|
@menu
|
|
* Usual Problems:: Problems which Occur Often
|
|
* Troubleshooting:: Finding the Problem
|
|
* Finding Help:: Getting Support
|
|
* Reporting Problems:: What to Send to Support
|
|
@end menu
|
|
|
|
@node Usual Problems, Troubleshooting, Build Problems, Build Problems
|
|
@section The Usual Build Problems
|
|
|
|
@subsection Taking the Easy Way Out
|
|
|
|
Why not take the easy way out if you can?
|
|
|
|
Many Linux systems contain package management programs which allow
|
|
netCDF to be installed easily. This is the prefered installation
|
|
method for netCDF.
|
|
|
|
Precompiled binaries for some platforms can be found at
|
|
@url{@value{netcdf-binaries-url}}. Click on your platform, and copy
|
|
the files from the bin, include, lib, and man directories into your
|
|
own local equivalents (Perhaps /usr/local/bin, /usr/local/include,
|
|
etc.).
|
|
|
|
@subsection How to Clean Up the Mess from a Failed Build
|
|
|
|
If you are trying to get the configure or build to work, make sure you
|
|
start with a clean distribution for each attempt. If netCDF failed in
|
|
the ``make'' you must clean up the mess before trying again. To clean
|
|
up the distribution:
|
|
|
|
@example
|
|
make distclean
|
|
@end example
|
|
|
|
@subsection Platforms On Which NetCDF is Known to Work
|
|
|
|
At NetCDF World Headquarters (in sunny Boulder, Colorado), as part of
|
|
the wonderful Unidata organization, we have a wide variety of
|
|
computers, operating systems, and compilers. At night, house elves
|
|
test netCDF on all these systems.
|
|
|
|
Output for the netCDF test platforms can be found at
|
|
@url{@value{netcdf-builds}}.
|
|
|
|
Compare the output of your build attempt with ours. Are you using the
|
|
same compiler? The same flags? Look for the configure output that
|
|
lists the settings of CC, FC, CXX, CFLAGS, etc.
|
|
|
|
On some systems you have to set environment variables to get the
|
|
configure and build to work.
|
|
|
|
For example, for a 64-bit IRIX install of the netCDF-3.6.2 release,
|
|
the variables are set before netCDF is configured or built. In this
|
|
case we set CFLAGS, CXXFLAGS, FCFLAGS, and FFLAGS.
|
|
|
|
@example
|
|
flip% uname -a
|
|
IRIX64 flip 6.5 07080050 IP30 mips
|
|
flip% setenv CFLAGS -64
|
|
flip% setenv CXXFLAGS -64
|
|
flip% setenv FFLAGS -64
|
|
flip% setenv FCFLAGS -64
|
|
flip% make distclean;./configure;make check
|
|
@end example
|
|
|
|
@subsection Platforms On Which NetCDF is Reported to Work
|
|
|
|
If your platform isn't listed on the successful build page, see if
|
|
another friendly netCDF user has sent in values for environment
|
|
variables that are reported to work:
|
|
(@uref{@value{netcdf-other-builds}}).
|
|
|
|
If you build on a system that we don't have at Unidata (particularly
|
|
if it's something interesting and exotic), please send us the settings
|
|
that work (and the entire build output would be nice too). Send them
|
|
to @value{netcdf-support-email}.
|
|
|
|
@subsection If You Have a Broken Compiler
|
|
|
|
For netCDF to build correctly, you must be able to compile C from your
|
|
environment, and, optionally, Fortran 77, Fortran 90, and C++. If
|
|
C doesn't work, netCDF can't compile.
|
|
|
|
What breaks a C compiler? Installation or upgrade mistakes when the C
|
|
compiler was installed, or multiple versions or compilers installed on
|
|
top of each other. Commercial compilers frequently require some
|
|
environment variables to be set, and some directories to appear ahead
|
|
of others in your path. Finally, if you have an expired or broken
|
|
license, your C compiler won't work.
|
|
|
|
If you have a broken C compiler and a working C compiler in your PATH,
|
|
netCDF might only find the broken one. You can fix this by explicitly
|
|
setting the CC environmental variable to a working C compiler, and
|
|
then trying to build netCDF again. (Don't forget to do a ``make
|
|
distclean'' first!)
|
|
|
|
If you can't build a C program, you can't build netCDF. Sorry, but
|
|
that's just the way it goes. (You can get the GNU C compiler - search
|
|
the web for ``gcc'').
|
|
|
|
If netCDF finds a broken Fortran 90, Fortran 77, or C++ compiler, it
|
|
will report the problem during the configure, and then drop the
|
|
associated API. For example, if the C++ compiler can't compile a very
|
|
simple test program, it will drop the C++ interface. If you really
|
|
want the C++ API, set the CXX environment variable to a working C++
|
|
compiler.
|
|
|
|
@subsection What to Do If NetCDF Still Won't Build
|
|
|
|
If none of the above help, try our troubleshooting section:
|
|
@xref{Troubleshooting}.
|
|
|
|
Also check to see of your problem has already been solved by someone
|
|
else (@pxref{Finding Help}).
|
|
|
|
If you still can't get netCDF to build, report your problem to
|
|
Unidata, but please make sure you submit all the information we need
|
|
to help (@pxref{Reporting Problems}).
|
|
|
|
@node Troubleshooting, Finding Help, Usual Problems, Build Problems
|
|
@section Troubleshooting
|
|
@cindex troubleshooting
|
|
@cindex turning off C++, Fortran interface
|
|
|
|
@subsection Problems During Configuration
|
|
|
|
If the ./configure; make check fails, it's a good idea to turn off the
|
|
C++ and Fortran interfaces, and try to build the C interface
|
|
alone. All other interfaces depend on the C interface, so nothing else
|
|
will work until the C interface works. To turn off C++ and Fortran,
|
|
set environment variables CXX and FC to NULL before running the netCDF
|
|
configure script (with csh: setenv FC '';setenv CXX '').
|
|
|
|
Turning off the Fortran and C++ interfaces results in a much shorter
|
|
build and test cycle, which is useful for debugging problems.
|
|
|
|
If the netCDF configure fails, most likely the problem is with your
|
|
development environment. The configure script looks through your path to
|
|
find all the tools it needs to build netCDF, including C compiler and
|
|
linker, the ar, ranlib, and others. The configure script will tell
|
|
you what tools it found, and where they are on your system. Here's
|
|
part of configure's output on a Linux machine:
|
|
|
|
@example
|
|
checking CPPFLAGS...
|
|
checking CC CFLAGS... cc -g -O2
|
|
checking type cc... cc is /usr/bin/cc
|
|
checking CXX... c++
|
|
checking CXXFLAGS... -g -O2
|
|
checking type c++... c++ is /usr/bin/c++
|
|
checking FC... gfortran
|
|
checking FFLAGS... -g -O2
|
|
checking type gfortran... gfortran is /usr/bin/gfortran
|
|
checking F90... gfortran
|
|
checking FCFLAGS... -g -O2
|
|
checking type gfortran... gfortran is /usr/bin/gfortran
|
|
checking AR... ar
|
|
checking AR_FLAGS... cru
|
|
checking type ar... ar is /usr/bin/ar
|
|
checking NM... /usr/bin/nm -B
|
|
checking NMFLAGS...
|
|
checking for /usr/bin/nm... /usr/bin/nm -B
|
|
checking nm flags...
|
|
@end example
|
|
|
|
Make sure that the tools, directories, and flags are set to reasonable
|
|
values, and compatible tools. For example the GNU tools may not
|
|
inter-operate well with vendor tools. If you're using a vendor
|
|
compiler, you may need to use the ar, nm, and ranlib that the vendor
|
|
supplied.
|
|
|
|
As configure runs, it creates a config.log file. If configure crashes,
|
|
do a text search of config.log for thing it was checking before
|
|
crashing. If you have a licensing or tool compatibility problem, it
|
|
will be obvious in config.log.
|
|
|
|
@subsection Problems During Compilation
|
|
|
|
If the configure script runs, but the compile step doesn't work, or
|
|
the tests don't complete successfully, the problem is probably in your
|
|
CFLAGS or CPPFLAGS.
|
|
|
|
Frequently shared libraries are a rich source of problems. If your
|
|
build is not working, and you are using the --enable-shared option to
|
|
generate shared libraries, then try to build without --enable-shared,
|
|
and see if the static library build works.
|
|
|
|
@subsection Problems During Testing
|
|
|
|
If you are planning on using large files (i.e. > 2 GiB), then you may
|
|
wish to rerun configure with --enable-large-file-tests to ensure that
|
|
large files work on your system.
|
|
|
|
Some DAP tests (in the directory ncdap_test) attempt to access an
|
|
external server at opendap.org. It is possible that the DAP server
|
|
may not be running at test time, or the network access may be
|
|
faulty or that the output of the test server has changed.
|
|
In this case, the DAP tests may fail. Because of this,
|
|
the use of these tests is controlled by the --enable-dap-remote-tests
|
|
option.
|
|
|
|
@node Finding Help, Reporting Problems, Troubleshooting, Build Problems
|
|
@section Finding Help On-line
|
|
@cindex mailing lists
|
|
@cindex documentation
|
|
@cindex FAQ for netCDF
|
|
@cindex other builds document
|
|
@cindex successful build output, on web
|
|
@cindex known problems
|
|
|
|
The latest netCDF documentation (including this manual) can be found
|
|
at @uref{@value{docs-url}}.
|
|
|
|
The output of successful build and test runs for recent versions of
|
|
netCDF can be found at @uref{@value{netcdf-builds}}.
|
|
|
|
A list of known problems with netCDF builds, and suggested fixes, can
|
|
be found at @uref{@value{known-problems-url}}.
|
|
|
|
Reportedly successful settings for platforms unavailable for netCDF
|
|
testing can be found at @uref{@value{netcdf-other-builds}}. If you
|
|
build netCDF on a system that is not listed, please send your
|
|
environment settings, and the full output of your configure, compile,
|
|
and testing, to @value{netcdf-support-email}. We will add the
|
|
information to the other-builds page, with a credit to you.
|
|
|
|
The replies to all netCDF support emails are on-line and can be
|
|
searched. Before reporting a problem to Unidata, please search this
|
|
on-line database to see if your problem has already been addressed in
|
|
a support email. If you are having build problems it's usually useful
|
|
to search on your system host name. On Unix systems, use the uname
|
|
command to find it.
|
|
|
|
The netCDF Frequently Asked Questions (FAQ) list can be found at
|
|
@uref{@value{netcdf-faq-url}}.
|
|
|
|
To search the support database, see @uref{@value{netcdf-support-search-url}}.
|
|
|
|
The netCDF mailing list also can be searched; see
|
|
@uref{@value{netcdf-list-search-url}}.
|
|
|
|
@node Reporting Problems, , Finding Help, Build Problems
|
|
@section Reporting Problems
|
|
@cindex bugs, reporting
|
|
@cindex problems, reporting
|
|
@cindex reporting problems
|
|
@cindex support email
|
|
|
|
To help us solve your problem, please include the following
|
|
information in your email to @uref{@value{netcdf-support-email}}.
|
|
|
|
Unfortunately, we can't solve build questions without this
|
|
information; if you ask for help without providing it, we're just
|
|
going to have to ask for it.
|
|
|
|
So why not send it immediately, and save us both the extra trouble?
|
|
|
|
@enumerate
|
|
|
|
@item the exact version of netCDF - see the VERSION file.
|
|
|
|
@item the *complete* output of ``./configure'', ``make'', and ``make check. Yes,
|
|
it's long, but it's all important.
|
|
|
|
@item if the configure failed, the contents of config.log.
|
|
|
|
@item if you are having problems with very large files (larger than
|
|
2GiB), send the output of "make check" after first running "make
|
|
distclean" and invoking the configure script with the
|
|
--enable-large-file-tests option included.
|
|
|
|
@end enumerate
|
|
|
|
Although responses to your email will be available in our support
|
|
database, your email address is not included, to provide spammers with
|
|
one less place to harvest it from.
|
|
|
|
@node Combined Index, , Build Problems, Top
|
|
@unnumbered Index
|
|
|
|
@printindex cp
|
|
|
|
@bye
|
|
End:
|