# Installing NetCDF

(The latest version of this document is available at http://www.unidata.ucar.edu/packages/netcdf/INSTALL.html.

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 http://www.unidata.ucar.edu/packages/netcdf/binaries.html.

If you wish to report problems encountered during the installation of this package, see Reporting Problems below.

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

If you wish to build from source on a Windows (Win32) platform, different instructions apply. Obtain the file ftp://ftp.unidata.ucar.edu/pub/netcdf/contrib/win32/maks.zip, unpack it in the netCDF src/ directory, and read WIN32_INSTALL.

## Specifying the Environment for Building

Select and specify an appropriate build environment. If necessary, set whichever of the environment variables CC, CFLAGS, CPPFLAGS, FC, FFLAGS, CXX, CXXFLAGS, F90, and F90FLAGS are needed to represent that environment.

If you don't set an environment variable, the `configure` script will try to figure out a reasonable value. (See Setting Environment Variables to learn how to set environment variables.)

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, 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, if no Fortran 90 interface desired.
CXX | C++ compiler | If you don't specify this, the configure script will try to find a suitable C++ compiler. Set CXX to `""` explicitly, if no C++ interface is desired.
CFLAGS | C compiler flags | `"-O"` or `"-g"`, for example
CPPFLAGS | C preprocessor options | `"-DNDEBUG"` to omit assertion checks, for example
FFLAGS | Fortran compiler flags | `"-O"` or `"-g"`, for example
F90FLAGS | Fortran 90 compiler flags | `"-O"` or `"-g"`, for example. If you don't specify this, the value of FFLAGS will be used.
CXXFLAGS | C++ compiler flags | `"-O"` or `"-g"`, for example
ARFLAGS NMFLAGS FPP M4FLAGS LIBS FLIBS | Miscellaneous | One or more of these were needed for some platforms, as specified below.

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.

## 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 src/ 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 "..", which will install the package's files in ../bin, ../lib, and ../man relative to the netCDF src/ directory.

Execute the `configure` script:

        ./configure --prefix=whatever_you_decided

The "`--prefix=...`" specification is optional; if omitted, "`..`" designating the parent directory will be used as a default.

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.

Run "`make`". This will build one or more netCDF libraries. It will build the basic netCDF library libsrc/libnetcdf.a. If you have Fortran 77 or Fortran 90 compilers, then the Fortran interfaces will be included in this library. If you have a C++ compiler, then the C++ interface will be built into the library cxx/libnetcdf_c++.a. This will also build the netCDF utilities ncgen(1) and ncdump(1).

## Testing and Installing the Release

Run "`make test`" to verify that the netCDF library and executables have been built properly. This 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.

To install the libraries and executables, run "`make install`". Try linking your applications. Let us know if you have problems (see Reporting Problems below). Port the library to other platforms. Share data.

### Tested Systems

The following are environment variable settings that we've used to build netCDF-3 on various systems -- plus commentary. Take your pick if there is more than one set of settings for a particular system. For some platforms we have provided a simple setting for building the library and another setting that uses optimization flags (though optimization may not make much difference for an I/O library). On some platforms compilers emit harmless warning messages, which you can safely ignore unless the tests performed in the "make test" step fail.

If you don't find your environment listed here, then try http://www.unidata.ucar.edu/packages/netcdf/other-builds.html for reports of successful builds of this package in environments to which we had no access.

- AIX
- HP-UX
- IRIX and IRIX64
- Linux
- MacOSX (public beta)
- OSF1
- Solaris
- SunOS4

#### AIX

    AIX gale 3 4 001330614C00

        CC=/bin/xlC
        FC=/bin/xlf
        F90=/bin/xlf90
        F90FLAGS=-qsuffix=f=f90
        CXX=/bin/xlC

        --------

        CC=/bin/xlc
        CPPFLAGS=-DNDEBUG
        CFLAGS=-O
        FC=/bin/xlf
        FFLAGS=-O
        F90=/bin/xlf90
        F90FLAGS=-qsuffix=f=f90   # Note: no "-O" option
        CXX=/bin/xlC
        CXXFLAGS=-O

            When we added the "-O" option to the Fortran-90 compilation
            flags, the result was an error message "1501-229 Compilation
            ended due to lack of space".

        --------

            Carlie Coats reported that the following was necessary on an
            IBM AIX SP system for 64-bit mode:

        ARFLAGS='-X 64 cru'
        NMFLAGS='-X 64'

#### HP-UX

    HP-UX robin B.11.00 E 9000/715 2010262449

            No Fortran90 compiler was available for testing.

        CC=/bin/c89
        CPPFLAGS=-D_HPUX_SOURCE
        FC=/opt/fortran/bin/fort77
        FFLAGS=-w
        FLIBS=-lU77                  # needed to obtain getarg_
        CXX=/bin/CC

        --------

        CC=/bin/c89
        CPPFLAGS='-D_HPUX_SOURCE -DNDEBUG -w'
        CFLAGS=-O
        FC=/opt/fortran/bin/fort77      # might be /usr/bin/fort77 instead
        FFLAGS='-O2 -w'                 # "-O3" causes ncgen test to fail
        FLIBS=-lU77                     # needed to obtain getarg_
        CXX=/usr/bin/CC
        CXXFLAGS=-O

    	The above resulted in ignorable errors involving "Redefinition
    	of macro FD_ISSET."  Also, we don't have an f90 compiler
    	for HP-UX yet, so we haven't tested that interface.

#### IRIX and IRIX64

    IRIX chevy 6.5 01101244 IP22
    IRIX64 flip 6.5 10120105 IP30

            IRIX f90 Note: On IRIX 6.x platforms with version 7 compilers,
            the f90 compiler accepts 'integer*1', while f77 accepts both
            'integer*1' and 'byte'. Using FC=f90 forces the
            configure script to select 'integer*1'.  The
            resulting *.inc files and test configurations will then work
            with either compiler.

        CC=/bin/c89
        FC=/bin/f90  # builds both f77 and f90 interfaces
        CXX=/bin/CC

        --------

        CC=/bin/c89
        CPPFLAGS=-DNDEBUG
        CFLAGS=-O
        FC=/bin/f90  # f77 also works
        FFLAGS=-O
        F90=/bin/f90
        F90FLAGS=-O
        CXX=/bin/CC
        CXXFLAGS=-O

        --------

        CC=/bin/c89
        CPPFLAGS=-DNDEBUG
        CFLAGS='-O -o32'
        FC=/bin/f77
        FFLAGS='-O -o32 -nocpp'
        CXX=/bin/CC
        CXXFLAGS='-O -o32'
        FPP='/bin/cc -E'

        --------

        CC=/bin/c89
        CPPFLAGS=-DNDEBUG
        CFLAGS='-O -n32'
        FC=/bin/f90
        FFLAGS='-O -n32'
        CXX=/bin/CC
        CXXFLAGS='-O -n32'

        --------

        # requires IRIX64
        CC='/bin/cc -64'
        CPPFLAGS=-DNDEBUG
        CFLAGS=-O
        FC='/bin/f90 -64'
        FFLAGS=-O
        F90='/bin/f90 -64'
        CXX='/bin/CC -64'
        CXXFLAGS=-O

#### Linux

    Linux imogene 2.2.16-22enterprise #1 SMP EDT 2000 i686 unknown

            No Fortran90 compiler was available for testing.

        CC=/usr/bin/egcs
        CPPFLAGS=-Df2cFortran
        FC=/usr/bin/g77
        FFLAGS=-Wno-globals
        CXX=/usr/bin/g++

        --------

        CC=/usr/bin/egcs
        CPPFLAGS='-DNDEBUG -Df2cFortran'
        CFLAGS=-O
        FC=/usr/bin/g77
        FFLAGS="-O -Wno-globals"
        CXX=/usr/bin/g++

        --------

        CC=/usr/bin/egcs
        CPPFLAGS="-DNDEBUG -Df2cFortran"
        CFLAGS=-O
        FC=/opt/bin/fort77    # uses f2c
        FFLAGS="-O -Nx400 -w" # "-Nx400" permits many EXTERNAL statements
        CXX=/usr/bin/g++

    Linux aqua 2.2.5-16 #1 Tue Apr 27 04:55:03 EDT 1999 alpha unknown

        The following was reported to work on an Alpha Linux workstation:

        CC=ccc                      # Compaq C compiler
        CPPFLAGS='-DNDEBUG -Df2cFortran'
        FC=fort                     # Compaq Fort F77/F90 Compiler
        F90=fort
        CXX=/usr/bin/c++

#### MacOSX (public beta)

    Darwin Kernel Version 1.2

            No Fortran 90 compiler was available for testing.

            If no Fortran interface is required:

        CC=/usr/bin/cc
        CXX=/usr/bin/c++
        FC=""
        M4FLAGS=""  # m4 doesn't handle the -B10000 argument

        --------

            If f2c is installed for use with the Fortran interface:

        CPPFLAGS=-Df2cFortran
        FC=/bin/fc
        M4FLAGS=""
        FFLAGS=-w
        FPP="cc -E -C"

#### OSF1

    OSF1 ernie V4.0 1091 alpha

        NB: Use of "g++" in the following might require that the
        LD_LIBRARY_PATH environment variable be set to reference the
        directory that contains the "g++" sharable library, e.g.

            export LD_LIBRARY_PATH=/opt/gnu/lib

        CC=/bin/c89
        FC=/bin/f77
        F90=/bin/f90
        CXX=g++

        --------

        CC=/bin/c89
        CPPFLAGS=-DNDEBUG
        CFLAGS=-O
        FC=/bin/f77
        FFLAGS=-O
        F90=/bin/f90
        CXX=g++
        CXXFLAGS=-O

#### Solaris

    SunOS 5.7 sun4u sparc SUNW,Ultra-2
    SunOS 5.8 sun4u sparc SUNW,Ultra-2
    SunOS 5.8 i86pc i386

        CC=/opt/SUNWspro/bin/c89   # also works with cc
        FC=/opt/SUNWspro/bin/f90   # also works with f77
        FFLAGS=-w                  # disables an ignorable warning
        CXX=/opt/SUNWspro/bin/CC

        --------

        CC=/opt/SUNWspro/bin/c89
        CPPFLAGS=-DNDEBUG
        CFLAGS=-O
        FC=/opt/SUNWspro/bin/f77
        FFLAGS="-O -w"
        F90=/opt/SUNWspro/bin/f90
        F90FLAGS="-O -w"
        CXX=/opt/SUNWspro/bin/CC
        CXXFLAGS=-O

        --------

        CC=/opt/SUNWspro/bin/c89
        CPPFLAGS=-DNDEBUG
        CFLAGS=-O
        FC=/opt/SUNWspro/bin/f90
        FFLAGS="-O2 -w"          # "-O" causes "ncgen -f" test to fail
        CXX=/opt/SUNWspro/bin/CC
        CXXFLAGS=-O

        --------

        CC=/opt/SUNWspro/bin/c89
        CFLAGS="-xarch=v9"          # 64-bit SPARC binary
        FC=/opt/SUNWspro/bin/f90
        FFLAGS="-w -xarch=v9"
        CXX=/opt/SUNWspro/bin/CC
        CXXFLAGS="-xarch=v9"

        --------

        CC=gcc
        CPPFLAGS=-Df2cFortran       # necessary for Fortran API
        FC=g77
        F90=''
        CXX=g++

#### SunOS4

    SunOS gummo 4.1.4 11 sun4m

            No Fortran 90 compiler was available for testing.

        CC=/usr/lang/acc
        FC=/usr/lang/f77
        FFLAGS=-w
        CXX=/usr/lang/CC

        --------

        CC=/usr/lang/acc
        CPPFLAGS=-DNDEBUG
        CFLAGS=-O
        FC=/usr/lang/f77
        FFLAGS='-O -w'
        CXX=/usr/lang/CC
        CXXFLAGS=-O

        --------

        CC=gcc
        CPPFLAGS='-DNDEBUG -D__USE_FIXED_PROTOTYPES__'
        CFLAGS=-O
        FC=/usr/lang/f77
        FFLAGS='-O -w'
        CXX=g++
        LIBS='-L/usr/lang/SC3.0.1/lib -lansi'   # To obtain memmove().

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

If you can't run the `configure` script, you will need to create libsrc/ncconfig.h and fortran/nfconfig.inc. Start with libsrc/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.

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

## Setting Environment Variables

If you don't know what environment variables are or how to set them, then read this section; otherwise, you may safely skip it.

An environment variable is a named parameter that is managed by a user's shell program and which the shell makes available to the utilities that it executes (for example, a `configure` script). The following are examples of typical environment variables:

            NAME                    EXAMPLE VALUE
            ----                    -------------
            USER                    steve
            HOME                    /home/steve
            PATH                    /bin:/usr/bin:/home/steve/bin

You may obtain a listing of your environment variables by executing the command "env".

The way in which an environment variable is defined and set depends upon the shell the user is using. A user of a csh-like shell (e.g. csh, tcsh) might do the following:

        % setenv CC c89
        % setenv CPPFLAGS "-O -DNDEBUG"

whereas, the user of the standard UNIX shell (e.g. sh, ksh, bash) might, equivalently, do the following:

        $ export CC=c89
        $ export CPPFLAGS="-O -DNDEBUG"

In both cases, the quotes above are necessary to delimit a value that contains embedded whitespace. They do not, however, become part of the value.

A user of a standard shell has an additional, shorthand method for defining and setting environment variables for just a single command. Environment variables can be defined and set on the command-line and take effect for only that command. For example

        $ export FOO=foo
        $ env | grep FOO
        FOO=foo
        $ FOO=bar env | grep FOO
        FOO=bar
        $ env | grep FOO
        FOO=foo

For tested systems, environment variables and their values are given as if listed by the "env" utility. Users of the standard UNIX shell may use the syntax directly; whereas, users of a csh-like shell should convert the syntax to that expected by the shell. For example, a standard shell user might do the following (taken from the SunOS 5.6 example):

        $ CC=/opt/SUNWspro/bin/c89 CPPFLAGS=-DNDEBUG CFLAGS=-O \
        FC=/opt/SUNWspro/bin/f77 FFLAGS="-O -erroff=WDECL_LOCAL_NOTUSED" \
        CXX=/opt/SUNWspro/bin/CC ./configure >configure.log 2>&1

whereas a csh-like shell user would, equivalently, do the following:

        % setenv CC /opt/SUNWspro/bin/c89
        % setenv CPPFLAGS "-DNDEBUG"
        % setenv CFLAGS -O
        % setenv FC /opt/SUNWspro/bin/f77
        % setenv FFLAGS "-O -erroff=WDECL_LOCAL_NOTUSED"
        % setenv CXX /opt/SUNWspro/bin/CC
        % ./configure >&! configure.log

More information on environment variables can be found in the manual page for your shell (e.g. "man csh", "man ksh").

## Reporting Problems

If you have a problem with the installation and wish to report it, then please do the following:

1. Read this INSTALL document -- especially the examples and commentary relevant to your system.
2. Go to the top-level netCDF source directory, src/ (the directory containing the VERSION file).
3. Execute the command "make distclean". Don't worry if it fails.
4. Remove the file "config.cache" if it exists.
5. Set your environment variables as described above.
6. Re-execute the `configure` script. Redirect its standard output and standard error to the file "configure.log". If this step fails -- which is indicated by error messages (not warnings) in "configure.log" (not "config.log") -- then stop and send items A through E below to <support@unidata.ucar.edu>.
7. Execute the command "make". Redirect its standard output and standard error to the file "make.log". If this step fails, then stop and send items A through F below to <support@unidata.ucar.edu>.
8. Execute the command "make test". Redirect its standard output and standard error to the file "test.log". If this step fails, then stop and send items A through G below to <support@unidata.ucar.edu>.
9. Execute the command "make install". Redirect its standard output and standard error to the file "install.log". If this step fails, then stop and send items A through H below to <support@unidata.ucar.edu>.

The following items help us diagnose installation problems. PLEASE SEND THEM AS INCLUDED PLAIN TEXT IN YOUR EMAIL AND NOT AS ATTACHMENTS.

1. The standard output of the command "uname -a".
2. The contents of the file VERSION, which is in the top-level source directory.
3. The absolute pathnames of all compilers (C, Fortran, C++) used in the build process (use the type(1) or which(1) utility to determine this).
4. The file "configure.log" from step 6 above.
5. The file "config.log", which is created in the top-level source directory by the `configure` script during step 6 above.
6. The file "make.log" from step 7 above.
7. The file "test.log" from step 8 above.
8. The file "install.log" from step 9 above.