			    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
