INSTALLATION This document describes how to build and install the netCDF package on a UNIX system and how to port the installation procedures to a new system. For instructions on installing on a PCDOS, MSDOS, OS/2, or VMS system, see the notes at the end of this file. On a UNIX system: 1) Create the makefiles via the `configure' script. 1.1) Decide where you want the software installed. By default, all software will be installed in peer directories of the directory containing this file (e.g. in `../bin/', `../lib/', etc.). If you want the software installed someplace else then you'll need to specify this place to the `configure' script by using the `--prefix=...' option. For example, if you want the software to be installed under `/usr/local', then you should invoke the `configure' script as configure --prefix=/usr/local This will install the software in `/usr/local/bin', `/usr/local/lib', etc. The default is to install the software in subdirectories under `..' and is thus equivalent to invoking the configure script as configure --prefix=.. NB: You must have write access to the root of the installation tree (e.g. /usr/local) and its subdirectories in order to install the software. 1.2) Decide the values you want for the following symbols: Symbol Definition Default Value ----- ---------- ------------- CC C compiler cc CPPFLAGS C preprocessor options -DNDEBUG CFLAGS C compiler options -O FC FORTRAN compiler f77 FFLAGS FORTRAN compiler options -O OLD_FILLVALUES Use old, default floating- no point fill values? The default -DNDEBUG value for CPPFLAGS means that the C preprocessor will cause the use of the C assert() macro in the source files to be ignored -- resulting in a slight improvement in speed at the expense of some internal consistency-checking at runtime. If you want internal runtime consistency-checking, then you define CPPFLAGS as something else (such as the empty string). If you do not have a FORTRAN compiler, then you should set the FC macro to a dummy value (e.g. "/bin/f77" or just ""). The makefiles check to see that the compiler actually exists. The OLD_FILLVALUES macro is provided for backward compatibility only. If you are a new user of netCDF, then you may safely ignore it. If, however, you have an existing archive of netCDF files that use default floating-point fill values, then you should know that the definition of the default floating-point fill values changed with version 2.3 of the netCDF package. Prior to this release, the default floating-point fill values were not very portable: their correct behavior depended not only upon the particular platform, but also upon the compilation environment. This led to the definition of new, default floating-point fill values that are portable across all platforms and compilation environments. If you wish, however, to obtain the old, non-portable floating-point fill values, then OLD_FILLVALUES should have the value `yes'. Implementation detail on fill values is contained in the file libsrc/netcdf.h.in. 1.3) If you want changes to the above defaults to be somewhat permanent, then edit them into the CUSTOMIZE file, which is in the same directory as this file (the file itself will tell you how to make the edits). Otherwise, proceed with the next step. 1.4) Go to the directory containing this file and invoke the `configure' script -- specifying any changes to the above defaults that you have not made permanent in the CUSTOMIZE file (or that you wish to override). For example, if you want internal consistency-checking, want to use gcc(1) as the C compiler, and want to install the software in subdirectories of /usr/local, then do the following: If using csh(1) or tcsh(1): % setenv CC gcc % setenv CPPFLAGS % ./configure --prefix=/usr/local If using sh(1) or bash(1): $ CC=gcc CPPFLAGS= ./configure --prefix=/usr/local NOTE: You must run the `configure' script even if you accept all the defaults. 2) Make "all". It is to your advantage to log the build process in case something goes wrong and you request assistance. For example: If using csh(1) or tcsh(1): % make all >&! log & % tail -f log If using sh(1) or bash(1): $ make all > log 2>&1 & $ tail -f log 3) Make "test" if you wish to test the software. If this is your first time with the package, then testing is a good idea. The XDR library will be tested and the netCDF interface will be tested in the "nctest" directory. The Fortran netCDF interface will also be tested if appropriate. You will know the tests are successful if there are no error messages interspersed among the messages that look like *** Testing ncfoo ... ok 4) Make "install". This should install the header-files, the library (possibly with the Fortran interface) the utilities, and the manual pages. If you have an "info" reader like emacs, xinfo, or info, you can use the doc/ug.texinfo file to generate info files for an on-line hypertext version of the netCDF User's Guide. See a Texinfo manual for how to do this. 5) Make "clean". Notes: Shared libraries are no longer supported by the installation mechanism If you have a shared library from a previous release already installed, then you should probably delete it and relink the applications programs that used it against the new library. The reason for dropping support for shared libraries is that, basically, it became too great a headache (too many platforms, too many differences in the way they handled shared libraries). Our philosphy now is to advise users to use system-supplied shared runtime libraries (e.g. libc.a) but to link statically with Unidata-supplied ones. Because the FORTRAN interface to the netCDF library doesn't depend upon the existence of a FORTRAN compiler, it will always be built and incorporated into the netCDF library. If your platform doesn't have a FORTRAN compiler, however, then the FORTRAN interface will not be tested by `make test'. The "XDR_" macros will be set as appropriate for your system. If your system has an XDR library, then the "xdr" subdirectory will be ignored. The installation process will, however, build the test routine "xdr/xdrtest" against your XDR library and run it. This will superficially verify your vendor's XDR implementation. Systems that we know already have a satisfactory XDR library include Sun (in libc), CRAY/UNICOS, SGI/IRIX (in libsun) and IBM RS6000/AIX. Systems for which you should build an XDR library from the sources we provide include MSDOS, OS/2, VAX/VMS (unless you have a vendor-supplied one, e.g. from TGV), and DECstation/Ultrix (because of a bug in the vendor-supplied library, see note below). You might also wish to use our XDR library for VAXstation/Ultrix systems. Assuming you will use the XDR routines provided, do you want the XDR routines rolled in with the netcdf library, or placed in a separate library? The Makefiles are set up assuming the first choice was made. Note: If you are building the netCDF library on a DECstation under ULTRIX, you should use the provided XDR source instead of the XDR routines in the system library, since the XDR floating point routines in the latter contain a bug (this is checked for by the `configure' script). There are also (much less notable) problems on VAX ULTRIX. In both cases, the problems are isolated to the module xdr_float.c. We suggest replacing the /lib/libc.a module xdr_float.o in Ultrix distributions with the one provided here. Since there is no standard for calling C from Fortran, we provide a way of generating a Fortran interface for the most common platforms, and a way of parameterizing less common calling conventions so you can generate a Fortran interface for other platforms. If you use standard vendor-supplied C and Fortran compilers (or other compilers with the same Fortran-to-C calling conventions) on SunOS, Ultrix, Unicos, AIX, VMS, or Microsoft compilers on PCDOS, MSDOS, or OS/2, the Makefile we provide will generate the Fortran interface. If there are problems generating the Fortran interface, you will see them right away, since make tries to do this first. In that case, you might want to check the fortran/NOTES file for OS-specific hints. At the least, you must correctly define the OS macro in the Makefile to be one of the supported platforms. If you are not building on one of these platforms, follow the instructions in fortran/README to create new Fortran interface sources. Change back to the top-level netcdf directory before proceeding. On a VMS system: 1) Read the exposition of NC_OLD_FILLVALUES in the file libsrc/netcdf.h and set the macro appropriately. 2) Use the make.com files in each source directory, and build in the subdirectories in the following order: [.xdr], [.libsrc], [.nctest], [fortran.vms], [.ncdump], [.ncgen]. Note that, by default, the netCDF library will be installed in [-.lib], the C and FORTRAN include files will be installed in [-.include], and the programs `ncgen' and `ncdump' will *not* be installed but will be found in their respective subdirectories. On a PCDOS, MSDOS, or OS/2 system: 1) The netCDF package has been tested on MSDOS Version 5.0 and OS/2 Version 1.3. MSDOS: in order to build the package using recursive makes (nmake), you will have to boot a configuration that contains no (or as few as possible) TSRs from CONFIG.SYS. If you do not, the compiler and/or linker WILL run out of heap space at some time during the build. 2) Read the exposition of NC_OLD_FILLVALUES in the file libsrc/netcdf.h and set the macro appropriately. 3) If you are building the system on OS/2, you will have to set the "OS2" macro to 1 in the top-level msoft.mk file or supply the definition OS2=1 on the make invocation command line. Using msoft.mk from the top-level directory will invoke the make utility (nmake) recursively for all the source subdirectories. 4) Successively make the targets "all", "test" and "install". NOTES: o Recursive makes work with DOS 5.0 and OS/2 but may not work with earlier versions of DOS because of memory limitations (see 1) above); in this case you will have to use the msoft.mk files in each of the subdirectories. o You may have to delete or rename the VMS-specific make.com files if your make utility is named "make". o If you are making the Fortran interface, ignore the Fortran error messages about VALUE type and length mismatches. For FORTRAN users, the C library should be built without FORTRAN compatibility, but the FORTRAN library should be built with C compatibility. Questions about building or installing netCDF software should be sent to support@unidata.ucar.edu. Good Luck :-) Russ Rew Steve Emmerson Glenn Davis Tom Yoksas