The NetCDF Installation and Porting Guide

NetCDF Version 3.6.3 Last Updated 18 May 2008

Ed Hartnett, Russ Rew Unidata Program Center

Copyright \begin{matrix}c \\ ◯ \end{matrix} 2005-2006 University Corporation for Atmospheric Research

Permission is granted to make and distribute verbatim copies of this manual provided that the copyright notice and these paragraphs are preserved on all copies. The software and any accompanying written materials are provided “as is” without warranty of any kind. UCAR expressly disclaims all warranties of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. The Unidata Program Center is managed by the University Corporation for Atmospheric Research and sponsored by the National Science Foundation. Any opinions, findings, conclusions, or recommendations expressed in this publication are those of the author(s) and do not necessarily reflect the views of the National Science Foundation. Mention of any commercial company or product in this document does not constitute an endorsement by the Unidata Program Center. Unidata does not authorize any use of information from this publication for advertising or publicity purposes.

Table of Contents

1 Installing the NetCDF Binaries . . . . . . . . . . . . . . . 1

2 Quick Instructions for Installing NetCDF on Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Building and Installing NetCDF on Unix

Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.1 Installation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2 Specifying the Environment for Building . . . . . . . . . . . . . . . . . . . . . . . . 5

3.2.1 Variable Description Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.3 Building on 64 Bit Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.4 Running the configure Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.5 Running make . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.6 Testing the Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.7 Installing NetCDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.8 Platform Specific Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.8.1 AIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.8.2 Cygwin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.8.3 MinGW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.8.4 HPUX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.8.5 Irix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.8.6 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.8.7 Macintosh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.8.8 OSF1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.8.9 SunOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.8.10 Handling Fortran Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.8.10.1 Intel Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.8.10.2 Portland Group Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.8.10.3 GNU Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.8.10.4 g95 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.8.10.5 g++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.9 Additional Porting Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.10 Contributing to NetCDF Source Code Development . . . . . . . . . . 17

4 Building and Installing NetCDF on Windows

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.1 Getting Prebuilt netcdf.dll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.2 Installing the DLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.3 Using netcdf.dll with VC++ 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.4 Building netcdf.dll with VC++.NET . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.5 Using netcdf.dll with VC++.NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5 If Something Goes Wrong . . . . . . . . . . . . . . . . . . . . 23

5.1 The Usual Build Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.1.1 Taking the Easy Way Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.1.2 How to Clean Up the Mess from a Failed Build . . . . . . . . . . . 23 5.1.3 Platforms On Which NetCDF is Known to Work . . . . . . . . . 23 5.1.4 Platforms On Which NetCDF is Reported to Work . . . . . . . 23 5.1.5 If You Have a Broken Compiler. . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.1.6 What to Do If NetCDF Still Won’t Build . . . . . . . . . . . . . . . . . 24

5.2 Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.2.1 Problems During Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.2.2 Problems During Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.2.3 Problems During Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

5.3 Finding Help On-line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.4 Reporting Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

1 Installing the NetCDF Binaries

Perhaps the easiest way to get netCDF is to get a pre-built binary distribution. To get

them, see http://www.unidata.ucar.edu/software/netcdf/binaries.html.

To install the binary distribution, uncompress and unpack the tar file. You will end up with 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 and ncdump utilities, and the man directory holds the netCDF documentation.

You can have these directories anywhere you like, and use netCDF. But 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).

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

http://www.unidata.ucar.edu/software/netcdf/faq.html#using_shared_p.

2 NetCDF Installation and Porting Guide

2 Quick Instructions for Installing NetCDF on Unix

Who has time to read long installation manuals these days?

To install netCDF, uncompress and unpack the tar file, then change to the distribution directory:

     gunzip netcdf-3.6.2.tar.gz
     tar -xf netcdf-3.6.2.tar
     cd netcdf-3.6.2

Now run the usual configure, make check, make install cycle:

     ./configure
     make check
     make install

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. For example, the following will install the library in /usr/local/lib, the header file in /usr/local/include, and the utilities in /usr/local/bin.

     ./configure --prefix=/usr/local

The default install root is /usr/local (so there’s no need to use the prefix argument if you want the software installed there).

By default the netCDF configuration will build static libraries only. For shared libraries as well, use the –enable-shared option to configure.

If all this doesn’t work, then you might have to read the next chapter. Better luck next time!

4 NetCDF Installation and Porting Guide

3 Building and Installing NetCDF on Unix Systems

The latest version of this document is available at http://www.unidata.ucar.edu/software/netcdf/docs/netcdf-install.

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 var-

ious platforms from http://www.unidata.ucar.edu/software/netcdf/binaries.html.

3.1 Installation Requirements

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 as part of the normal “make check” step; they are only run if you use the –enable-large-file-tests option with configure.

If you wish to build from source on a Windows (Win32) platform, different instructions apply. See Chapter 4 [Windows], page 19.

3.2 Specifying the Environment for Building

The netCDF configure script searches your path to find the compilers, tools, and settings it needs to build netCDF. If you wish to change the default choices of the configure script, you may do so by setting environment variables.

Environment variables are a feature of Unix shells, and each shell may handle them in a slightly different manner. (To see which shell you are using, type: echo $SHELL).

For users of the C-shell (csh) and derived shells, use the setenv command to set environment variables. For the Bourne shell (sh), use the export command to set an environment variable.

For example, to use compilers that can’t be found in your path, set the appropriate CC, CXX, F77, or F90 environment variables. In the Bourne shell:

     export CC=/some/strange/place/cc
     export F77=/some/strange/place/f77
     ./configure
     make check

To accomplish the same thing from the C-shell:

     setenv CC /some/strange/place/cc
     setenv F77 /some/strange/place/f77
     ./configure
     make check

When searching for compilers the configure script will prefer vendor compilers to GNU compilers. Its not because we don’t like GNU, but because we assume if you purchased a compiler, you want to use it. Setting CC allows you to over-ride this preference. (Alternatively, you could temporarily remove the compiler’s directories from your PATH.)

For example, on an AIX system, configure will first search for xlc, the AIX compiler. If not found, it will try gcc, the GNU compiler. To override this behavior, set CC to gcc (in sh: export CC=gcc). (But don’t forget to also set CXX to g++, or else configure will try and use xlC, the AIX C++ compiler to build the netCDF C++ API.)

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.

3.2.1 Variable Description Notes

CC C compiler If you don’t specify this, the configure script will try to find a suitable C compiler such as cc, c89, xlc, or gcc.

FC Fortran compiler (if any)

If you don’t specify this, the configure script will try to find a suitable Fortran 90 or Fortran 77 compiler. Set FC to "" explicitly, or provide the –disable-f77 option to configure, if no Fortran interface is desired.

F90 Fortran 90 compiler (if any)

If you don’t specify this, the configure script will try to find a suitable Fortran 90 compiler. Not needed if FC specifies a Fortran 90 compiler. Set F90 to "" explicitly, or use the –disable-f90 option to configure, if no Fortran 90 interface is desired. For a vendor F90 compiler, make sure you’re using the same vendor’s F77 compiler. Using Fortran compilers from different vendors, or mixing vendor compilers with g77, the GNU F77 compiler, is not supported and may not work.

CXX C++ compiler 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.

CFLAGS C compiler flags "-O" or "-g", for example. If you don’t set this, configure may set it based on your platform’s needs (unless you have used the –disable-flag-setting option is used with configure).

CPPFLAGS C preprocessor options "-DNDEBUG" to omit assertion checks, for example. If you don’t set this, configure may set it based on your platform’s needs (unless you have used the –disable-flag-setting option is used with configure).

FFLAGS Fortran compiler flags "-O" or "-g", for example. If you don’t set this, configure may set it based on your platform’s needs (unless you have used the –disable-flag-setting option is used with configure).

F90FLAGS Fortran 90 compiler flags "-O" or "-g", for example. If you don’t specify this, the value of FFLAGS will be used. Configure may set it based on your platform’s needs (unless you have used the –disable-flag-setting option is used with configure).

CXXFLAGS C++ compiler flags "-O" or "-g", for example. If you don’t set this, configure may set it based on your platform’s needs (unless you have used the –disable-flag-setting option is used with configure).

ARFLAGS, NMFLAGS, FPP, M4FLAGS, LIBS, FLIBS, FLDFLAGS Miscellaneous 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.

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.

3.3 Building on 64 Bit Platforms

Some platforms support special options to build in 64-bit mode.

NetCDF 3.6.3 has been tested as 64-bit builds on SunOS, Irix, and AIX. The options needed to build in 64-bit mode on these platforms are described below.

AIX Set -q64 option in all compilers, and set NMFLAGS to -X64, and ARFLAGS to ’-X64 cru’. Alternatively, set environment variable OBJECT MODE to 64 before running configure.

IRIX Set the -64 option in all compilers.

SunOS Use the -xarch=v9 flag on all compilers. This is not supported on the x86 platform.

3.4 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.

(Note that this is a new default location for version 3.6.2 of netCDF. Previous versions used the directory in which netCDF was built as the default install directory).

Here’s how to execute the configure script with a different installation directory:

./configure --prefix=/whatever/you/decided

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.

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.

--enable-shared

Build shared libraries (as well as static) on platforms which support them.

--enable-docs-install

If this option is used, the netCDF distribution will install all documentation. NetCDF documents are provided in PDF, HTML, postscript, info, and ASCII text. You can change the directory that documents are installed to. Run ./configure –help for more information. The this option does not affect the netCDF man pages, which are always installed. This option applies only to the texinfo documentation files in the man directory (netcdf.texi, netcdf-c.texi, and so on). The latest documentation is also available on-line at the the netCDF website.

http://www.unidata.ucar.edu/software/netcdf.

Installing the documentation does not cause the documentation to be built from source; it causes the documentation which was shipped with the distribution to be installed. Users who wish to contribute to the documentation development are urged to make any suggested changes to the documentation source files, which have the .texi filename extension (netcdf.text, netcdf-c.texi, etc.). Building the netCDF documentation from source requires recent versions of the open-source tools sed, m4, texinfo, and tex.

--disable-flag-setting

By default the configure script may change some compiler flags to allow netCDF to build on your platform. If you wish to specify compiler flags which conflict with the ones added by the configure script, then use this option to instruct configure not to attempt to set any compiler flags. It is then the responsibility of the user to correctly set CPPFLAGS, CFLAGS, etc. (Note that this flag does not affect some setting of flags by configure for GNU platforms; it just turns off any special netCDF flags).

--disable-largefile

This omits OS support for large files (i.e. files larger than 2 GB).

--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 of the CXX API, as if –disable-cxx had also been specified.

--disable-utilities

This turns off the building (and testing) of the netCDF utilities ncgen and ncdump. This option is helpful when debugging library build problems, but probably not of much use to the average user.

--enable-c-only

This turns off the building (and testing) of everything except the core netCDF-3 C library. This option is helpful when debugging library build problems, but probably not of much use to the average user.

--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.

--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

Normally configure checks the size of fortran types. This option turns off those tests, and uses default values.

--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 –disablef90. 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. Note that the examples are not built for “make install”, just for “make check”. As far as netCDF is concerned, the examples are extra tests.

--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.

--disable-extreme-numbers

In some netCDF test programs (nc test.c and nf test.F) there are tests which use numbers at or just beyond the extreme number that can be used for a type. (For example, using MAX INT + 1 as an int type). This causes problems on Solaris 386 systems. For that reason, the extreme numbers are not used, by default, on Solaris 386 systems. This option gives the user control to override the default. This affects only netCDF test programs, not the netCDF library itself.

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.

3.5 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:

     make

3.6 Testing the Build

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:

     make check

If you plan to use the 64-bit offset format (introduced in version 3.6.0) to create very large files (i.e. 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:

     ./configure --enable-large-file-tests --with-temp-large=/home/ed/tmp
     make check

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:

     dd if=/dev/zero bs=1000000 count=3000 of=$(TEMP_LARGE)/largefile

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.

See Chapter 5 [If Something Goes Wrong], page 23.

3.7 Installing NetCDF

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:

     make install

The install will put files in the following subdirectories of the directory you provided as a prefix, creating the subdirectories if needed:

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.

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.

bin Utilities ncdump and ncgen will be installed here.

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.

share If the configure is called with the –enable-install-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.

Try linking your applications. Let us know if you have problems (see Section 5.4 [Reporting Problems], page 26).

3.8 Platform Specific Notes

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 3.6.3 can be

found at http://www.unidata.ucar.edu/software/netcdf/builds.

3.8.1 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 (we hope):

         F90FLAGS=-qsuffix=f=f90

We had to use xlf for F77 code, and xlf90 for F90 code.

To compile 64-bit code, set the correct environment variables for your platform (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:

         ARFLAGS='-X64 cru'
         NMFLAGS='-X64'

There are thread-safe versions of the AIX compilers. For example, xlc r is the threadsafe C compiler. The NetCDF configure script ignores these compilers. 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.

3.8.2 Cygwin

Cygwin is a Linux-like environment for Windows. NetCDF builds under Cygwin tools on Windows just as with Linux. For more information see the Cygwin web site:

http://www.cygwin.com.

Building under Cygwin will yield a DLL on windows (as long as –enable-shared is used with configure). However this DLL will not work without the Cygwin POSIX emulation DLL as well. For a stand-alone DLL, use MinGW (below).

3.8.3 MinGW

MinGW, or Minimalist GNU for Windows, is a set of GNU Unix tools ported to Windows. The NetCDF C and Fortran APIs builds under MinGW tools on Windows just as with Linux.

Those diving into netCDF and MinGW should be familiar with the information at the web page “Different Ways of Building Woe32 DLLs”

at:  http://www.haible.de/bruno/woe32dll.html, the MinGW FAQ at:

http://www.mingw.org/mingwfaq.shtml, and the peculiarities of the win32 environment

as explained by this helpful Red Hat document at: http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/gnu-linker/win32.html.

The netCDF C++ API does not (yet) build DLLs cleanly under MinGW. Any knowledgeable user who can make this work should send results to the netCDF support email address: support@unidata.ucar.edu.

Using MinGW it is possible to produce stand-alone windows DLLs. First build netCDF in the usual way, with –enable-shared and –enable-dll as configure options.

This builds the DLL for compatibility with g77. Set FC to the command line invocation of your fortran compiler. To build for other fortran compilers (i.e. ones you don’t have), change the config.h file to select another fortran and recompile (without rerunning configure).

The fortran tests will not, of course, work for these other fortrans, because you don’t have the compiler to compile the test program!

     FC=g77 ./configure --enable-dll --disable-cxx --enable-shared
     make check

Due to the magic of libtool, the output files are found in the libsrc/.libs directory.

To get a MS compatible export library, open an MS DOS window, change directory to libsrc/.libs and run the following command:

     lib /machine:i386 /def:libnetcdf.def

The above command uses the Microsoft LIB tool, which comes with Visual C++.NET, and perhaps other Microsoft development tools. (To get this in my path, I open the “Visual Studio 2003 Command Prompt” in my Windows program menu.)

This command creates the .lib file, the import library, needed (or at least used) by MicroSoft (and other) build environments on Windows.

For more information about MinGW, see the MinGW web site: http://www.mingw.org. For more information about producing stand-alone windows DLLs with MinGW, see the

MinGW FAQ: http://www.mingw.org/mingwfaq.shtml.

3.8.4 HPUX

For the c89 compiler to work, CPPFLAGS must include -D HPUX SOURCE. This isn’t required for the cc compiler.

Our HPUX machine has two C compilers. Only the one in /opt/ansic/bin/ works for netCDF.

For large file support, HP-UX requires FILE OFFSET BITS=64. The configure script sets this automatically.

The HPUX C++ compiler (on our machine) 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 ”), or using the –disable-cxx option.

Building a 64 bit version may be possible with the following settings:

         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

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.

3.8.5 Irix

A 64-bit version can be built by settin the appropriate environment variables. Set CFLAGS, FCFLAGS, 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.

3.8.6 Linux

The f2cFortran flag is turned on by the configure script when GNU fortran is used.

         CPPFLAGS=-Df2cFortran

For Portland Group Fortran, set pgiFortran instead:

         CPPFLAGS=-DpgiFortran

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.

3.8.7 Macintosh

The f2cFortran flag is required with GNU fortran (CPPFLAGS=-Df2cFortran). The NetCDF configure script should and set this automatically.

For IBM compilers on the Mac, the following may work (we lack this test environment):

         CC=/usr/bin/cc
         CPPFLAGS=-DIBMR2Fortran
         FC=xlf
         F90=xlf90
         F90FLAGS=-qsuffix=cpp=f90

For the g95 compiler, you must set LIBS to -lSystemStubs before running configure.

3.8.8 OSF1

NetCDF builds out of the box on OSF1.

3.8.9 SunOS

PATH should contain /usr/ccs/bin to find make, nm, ar, etc.

For large file support, FILE OFFSET BITS must be 64. Configure will turn this on automatically.

Large file support doesn’t work with c89, unless the -Xa option is used. The netCDF configure script turns this on automatically where appropriate.

To compile in 64-bit mode, set -xarch=v9 on all compilers (i.e. in CFLAGS, FFLAGS, and CXXFLAGS).

When compiling with GNU Fortran (g77), the -Df2cFortran flag is required for the Fortran interface to work. The NetCDF configure script turns this on automatically if needed.

3.8.10 Handling Fortran Compilers

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.

3.8.10.1 Intel Fortran

Intel has provided a helpful web page on “Building netCDF with the Intel compilers” at

http://www.intel.com/support/performancetools/sb/CS-027812.htm, providing con-

figuration and set-up information, and instructions for building netCDF on Linux and Mac OS.

As an alternative, netCDF can be built successfully with CPPFLAGS set to pgiFortran. Configure can handle this automatically if your fortran compiler is named “ifort.”

3.8.10.2 Portland Group Fortran

The Portland Group fortran compiler requires that netCDF be built with the pgiFortran flag. It will be automatically turned on by configure if your fortran compiler is named “pgf90.”

   The Portland Group also has a “PGI Guide to NetCDF” at http://www.pgroup.com/resources/netcdf/netcdf362_
pgi71.htm.

3.8.10.3 GNU Fortran

The GNU Fortran 77 compiler (g77) requires that netCDF be built with the f2cFortran flag. This is turned on automatically by configure. Since g77 can’t build Fortran 90 code, the F90 API will not be built if g77 is the only available fortran compiler.

The version 4 series of gcc, the GNU Compiler Collection, offers a F95 compiler, usually called gfortran. NetCDF requires the pgiFortran flag to build with gfortran, and this is turned on automatically by configure.

3.8.10.4 g95

g95 is a Fortran 95 compiler which is different from the Free Software Foundation’s gfortran. The netCDF configure script sets the f2cFortran flag when g95 is used.

Some g95 users recommend instead setting the following, which handles the underscores differently, and reportedly works better when integrating with other packages or libraries:

     CC=gcc
     FC=g95
     CPPFLAGS=-DpgiFortran
     FFLAGS=-fno-second-underscore
     FCFLAGS=-fno-second-underscore

If this approach is taken, all fortran programs which use netCDF must be compiled with the -fno-second-underscore flag.

One the Macintosh, g95 requires environment variables LIBS and FLIBS to be set to -lSystemStubs.

3.8.10.5 g++

Older versions of the GNU C++ compiler don’t handle large files well. A version 3.2 installation of g++ fails to build for me without –disable-largefile. This turns off the ability of netCDF to handle files larger than about 2 GiBytes. Users should upgrade their g++, or learn to live with small files.

3.9 Additional Porting Notes

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

http://www.unidata.ucar.edu/software/netcdf/other-builds.html.  If you

build netCDF on a new platform, please send your environment variables and any other important notes to support@unidata.ucar.edu 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.

3.10 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.

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.

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.

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.

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 docu-

ments at the netCDF website. http://www.unidata.ucar.edu/software/netcdf/docs.

autoconf Generates the configure script. Version 2.59 or later is required.

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.

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.

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.

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 support@unidata.ucar.edu.

4 Building and Installing NetCDF on Windows

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. See Section 3.8 [Platform Specific Notes], page 12.

Instructions are also given for building the netCDF DLL from the source code using Microsoft’s Visual Studio and VC++.NET.

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 (per-

haps) 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

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconConsumingUnmanagedDLLFunctions.asp,

unless the page has been moved.

4.1 Getting Prebuilt netcdf.dll

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

ftp://ftp.unidata.ucar.edu/pub/netcdf/contrib/win32/netcdf-3.6.1-beta1-win32dll.zip.

(Note: we don’t have a C++ interface here).

4.2 Installing the DLL

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 www.msdn.microsoft.com).

Following Windows conventions, the netCDF files belong in the following places:

File(s)  Description  Location

netcdf.dll C and Fortran function in DLL Windows\System (98/ME) or Windows\System32 (2000/XP)

netcdf.lib Library file Windows\System (98/ME) or Windows\System32 (2000/XP)

ncgen.exe, ncdump.exe NetCDF utilities Windows\System (98/ME) or Windows\System32 (2000/XP)

netcdf-3 netCDF source code Program Files\Unidata

4.3 Using netcdf.dll with VC++ 6.0

When using the netCDF DLL, you should set the preprocessor flag DLL NETCDF. Do this in the properties window for your project in visual studio.

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)

4.4 Building netcdf.dll with 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.

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.

4.5 Using netcdf.dll with VC++.NET

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:

     #include <netcdf.h>

When using the netCDF DLL, you should set the preprocessor flag DLL NETCDF. Do this in the properties window for your project in visual studio.

22 NetCDF Installation and Porting Guide

5 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.

5.1 The Usual Build Problems

5.1.1 Taking the Easy Way Out

Why not take the easy way out if you can?

   Pre-compiled binaries for many platforms can be found at http://www.unidata.ucar.edu/software/netcdf/binaries.html.

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.).

5.1.2 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:

     make distclean

5.1.3 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 http://www.unidata.ucar.edu/software/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.

     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

5.1.4 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:

(http://www.unidata.ucar.edu/software/netcdf/other-builds.html).

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 support@unidata.ucar.edu.

5.1.5 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 complier 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.

5.1.6 What to Do If NetCDF Still Won’t Build

If none of the above help, try our troubleshooting section: See Section 5.2 [Troubleshooting], page 24.

Also check to see of your problem has already been solved by someone else (see Section 5.3 [Finding Help], page 25).

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 (see Section 5.4 [Reporting Problems], page 26).

5.2 Troubleshooting

5.2.1 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:

     checking CPPFLAGS...  -Df2cFortran
     checking CC CFLAGS... cc -g
     checking which cc... /usr/bin/cc
     checking CXX... c++
     checking CXXFLAGS... -g -O2
     checking which c++... /usr/local/bin/c++
     checking FC... f77
     checking FFLAGS...
     checking which f77... /usr/bin/f77
     checking F90... unset
     checking AR... ar
     checking ARFLAGS... cru
     checking which ar... /usr/bin/ar
     checking NM... nm
     checking NMFLAGS...
     checking which nm... /usr/bin/nm

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, 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.

5.2.2 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.

5.2.3 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.

5.3 Finding Help On-line

The latest netCDF documentation (including this manual) can be found at

http://www.unidata.ucar.edu/software/netcdf/docs.

The output of successful build and test runs for recent versions of netCDF can be found

at http://www.unidata.ucar.edu/software/netcdf/builds.

A list of known problems with netCDF builds, and suggested fixes, can be found at

http://www.unidata.ucar.edu/software/netcdf/docs/known_problems.html.

Reportedly successful settings for platforms unavailable for netCDF testing can be found

at http://www.unidata.ucar.edu/software/netcdf/other-builds.html. 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 support@unidata.ucar.edu. 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

http://www.unidata.ucar.edu/software/netcdf/faq.html.

To search the support database, see /search.jsp?support&netcdf.

The netCDF mailing list also can be searched; see /search.jsp?netcdfgroup.

5.4 Reporting Problems

To help us solve your problem, please include the following information in your email to

support@unidata.ucar.edu.

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?

1. the exact version of netCDF - see the VERSION file.

2. the *complete* output of “./configure”, “make”, and “make check. Yes, it’s long, but it’s all important.

3. if the configure failed, the contents of config.log.

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.

Index 27

Index

-

--disable-compiler-recover . . . . . . . . . . . . . . . . . 10

--disable-cxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 --disable-examples . . . . . . . . . . . . . . . . . . . . . . . . . . 10

--disable-extreme-numbers . . . . . . . . . . . . . . . . . . 10

--disable-f77 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 --disable-f90 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 --disable-flag-setting . . . . . . . . . . . . . . . . . . . . . . . 8

--disable-fortran-compiler-check . . . . . . . . . . 10
--disable-fortran-type-check . . . . . . . . . . . . . . . 10

--disable-largefile . . . . . . . . . . . . . . . . . . . . . . . . . . 9 --disable-utilities . . . . . . . . . . . . . . . . . . . . . . . . . . 9 --disable-v2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 --enable-c-only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 --enable-docs-install . . . . . . . . . . . . . . . . . . . . . . . . 8

--enable-large-file-tests . . . . . . . . . . . . . . . . . . . 9
--enable-separate-fortran . . . . . . . . . . . . . . . . . . 10

--enable-shared . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 --prefix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 --with-temp-large. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

LARGE FILES, on AIX . . . . . . . . . . . . . . . . . . . . . . 12

6

64-bit platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

A

AIX 64-bit build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 AIX, building on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 autoconf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 automake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

B

big endian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 binaries, windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 binary install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 binary releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 bugs, reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

C

config.log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 configure, running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 CRAY, porting to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Cygwin, building with . . . . . . . . . . . . . . . . . . . . . . . . . 12

D

debug directory, windows . . . . . . . . . . . . . . . . . . . . . . 21 DLL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 dll, getting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 documents, latest version . . . . . . . . . . . . . . . . . . . . . . . 5

E

earlier netCDF versions . . . . . . . . . . . . . . . . . . . . . . . . . 5 enable-large-file-tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

F

FAQ for netCDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 ffio.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 flex and yacc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 fortran, Intel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 fortran, Portland Group . . . . . . . . . . . . . . . . . . . . . . . 12

G

g++. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 g95. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 GNU make . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

H

HPUX, building on . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

I

install directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 installation requirements . . . . . . . . . . . . . . . . . . . . . . . . 5 installing binary distribution . . . . . . . . . . . . . . . . . . . . 1 installing netCDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Intel fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Irix, building on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

K

known problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

L

large file tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 large file tests requirements . . . . . . . . . . . . . . . . . . . . . 5 large file tests, for windows . . . . . . . . . . . . . . . . . . . . 21 libtool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Linux, building on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 little endian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

M

m4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Macintosh, building on . . . . . . . . . . . . . . . . . . . . . . . . 12

28 NetCDF Installation and Porting Guide

mailing lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 make all large tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 make check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 make install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 make lfs test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 make slow check. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 make test. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 make, running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 makeinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Microsoft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 MingGW, building with . . . . . . . . . . . . . . . . . . . . . . . 12

N

ncconfig.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 ncconfig.in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 ncconfig.inc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 ncdump, windows location . . . . . . . . . . . . . . . . . . . . . 19 ncgen, windows location . . . . . . . . . . . . . . . . . . . . . . . 19 ncio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 ncx.m4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 netcdf.dll, location. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 netcdf.lib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

O

OBJECT MODE, on AIX . . . . . . . . . . . . . . . . . . . . . 12 OSF1, building on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 other builds document . . . . . . . . . . . . . . . . . . . . . . . . . 25

P

porting notes, additional . . . . . . . . . . . . . . . . . . . . . . . 17 Portland Group fortran . . . . . . . . . . . . . . . . . . . . . . . . 12 posixio.c. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 prefix argument of configure . . . . . . . . . . . . . . . . . . . . 8 problems, reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Q

quick unix instructions. . . . . . . . . . . . . . . . . . . . . . . . . . 3 quick large files, in VC++.NET . . . . . . . . . . . . . . . . 21

R

release directory, windows . . . . . . . . . . . . . . . . . . . . . 21 reporting problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 running configure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 running make. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

S

sed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 shared libraries, building . . . . . . . . . . . . . . . . . . . . . . . . 3 shared libraries, using. . . . . . . . . . . . . . . . . . . . . . . . . . . 1 successful build output, on web . . . . . . . . . . . . . . . . 25 SunOS 64-bit build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 SunOS, building on . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 support email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

T

TEMP LARGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 testing large file features . . . . . . . . . . . . . . . . . . . . . . . 11 testing, for windows . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 tests, running. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 tex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 turning off C++, Fortran interface . . . . . . . . . . . . . . 24

V

VC++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 VC++ 6.0, using netcdf with . . . . . . . . . . . . . . . . . . . 20 VC++.NET, building with. . . . . . . . . . . . . . . . . . . . . . 21 VC++.NET, using netcdf with. . . . . . . . . . . . . . . . . . 21 visual studio 2003 properties . . . . . . . . . . . . . . . . . . . 21

W

windows large file tests . . . . . . . . . . . . . . . . . . . . . . . . 21 windows testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 windows, building on . . . . . . . . . . . . . . . . . . . . . . . . . . 19