			    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 Windows NT, 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.  Invoking the
          `configure' script with no arguments, i.e.

                configure

	  will result in makefiles that install the netCDF software 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
          must 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.  In this context, the invocation

 		configure --prefix=..

          is equivalent to invoking 'configure' with no arguments.
 
 	  NB: You must invoke 'configure' in order to create the makefiles
          for your system, and 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			platform dependent
	CPPFLAGS	C preprocessor options
	CFLAGS		C compiler options		-O
	FC		FORTRAN compiler		platform dependent
	FFLAGS		FORTRAN compiler options	-O
	CXX		C++ compiler			platform dependent
	CXXCPPFLAGS	C++ preprocessor options	
	CXXFLAGS	C++ compiler options

         If you do not have a FORTRAN compiler or do not want the FORTRAN
         interface, then you should set the FC macro to the empty string
         (i.e. "").  This will cause the building, testing, and installation
         of the FORTRAN interface to be skipped.

         If you do not have a C++ compiler or do not want the C++
         interface, then you should set the CXX macro to the empty string
         (i.e. "").  This will cause the building, testing, and installation
         of the C++ interface to be skipped.

    1.3) If you want changes to the above 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 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), ksh(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.

    1.5) If an error occurs during the the execution of the `configure'
         script, then you might try looking at the file `config.log'.
         This file contains the output from standard error of tests
         that the configure script runs in order to determine the
         characteristics of your development environment.  Most messages
         are the result of such tests, however, certain messages might
         indicate a severe problem with your environment.  For example:

	     ld: Can't open: /usr/lib/crt1.o (No such file or directory)

	     gcc: installation problem, cannot exec as: No such file or \
	     directory

	 If messages like the above appear, then you will have to fix
	 your development environment before you can successfully
	 execute the `configure' script.  Before re-executing the
	 `configure' script, you should ensure that the file
	 `config.cache' does *not* exist.

2) Make "all".  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), ksh(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 and C++ netCDF interfaces 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), a C++ library if appropriate, the
   utilities, and the manual pages.  If you have an "info" reader like
   emacs, xinfo, or info, you can use the doc/guide.tex 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:

   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.

   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:

       Use the makevms.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 Windows NT system:

       The netCDF package has been tested on Windows NT 3.51 using Visual
       C++ 2.2 and Fortran Powerstation 1.0.  The '*.mak' files provided are
       for use within these systems.  Build in the subdirectories in the
       order util, xdr, libsrc, nctest, fortran, ncdump, ncgen.  Before
       building,

       1) copy local_nc.gen to local_nc.h  in the libsrc directory
       2) copy msoftyy.c to ncgenyy.c and copy msofttab.h to ncgentab.h in
          the ncgen directory

On an MSDOS system:

    1) The netCDF package has been built and tested on MSDOS Version
       6.20 using a DJGPP/f2c development environment.  DJGPP is a
       port of the GNU C development environment to MSDOS.  It is
       freely-available from the following URL:

	    ftp://ftp.coast.net/SimTel/vendors/djgpp/

       The version we used was `v1' for a 32-bit (80386 CPU or better)
       environment (a user-report indicates that version 2 also
       works). f2c is a FORTRAN-to-C translation utility and runtime
       environment.  It is freely-available from the following URL:

	    ftp://netlib.att.com:/netlib/f2c/

       We chose to support this freely-available development environment
       rather than the multitude of commercial environments.

       In order to build the package using recursive makes, you should
       boot a configuration that contains no (or as few as possible)
       TSRs from CONFIG.SYS.  If you do not, the compiler and/or linker
       might run out of heap space at some time during the build.

    2) Go to the top-level source directory.
    
    3) Edit the file `djgpp32a.mak' as specified by the in_file 
       commentary.

    4) Sequentially make the targets "all", "test", "install", and
       "clean" using the makefile `djgpp32.mak', e.g.

	    gmake -f djgpp32.mak all

    NOTES:
       o A `make' from the top-level source directory might fail because
         of memory limitations (they do on our 8 MB system).  In this
         case you will have to use the makefiles `djgpp32.mak' in each
         of the subdirectories.  Following the same sequence that's in
         the top-level `djgpp32.mak' makefile.

       o If you are making the FORTRAN interface, then you should ignore
         the error messages from the `f2c' translator about inconsistent
         calling sequences and unused external functions.

       o If you are making the C++ interface, then you should ignore the
         error messages from the compiler about "return to `<foo>' from
         `<bar>'" in file cxx/ncvalues.cc.

On an OS/2 system:

    1) The netCDF package has been built and tested on OS/2 Version 2.10
       using an EMX development environment.  EMX is a port of the GNU C
       development environment to OS/2.  It is freely-available from the
       following URL:

	    ftp://hobbes.nmsu.edu/os2/unix/emx09b/

       In addition to the EMX development environment, we also used the
       following packages to build and test the netCDF package:

	    Make utility:
		ftp://hobbes.nmsu.edu/os2/unix/gnumake.zip

	    Lexical scanner generator:
		ftp://hobbes.nmsu.edu/os2/unix/flex2522.zip

	    Grammatical parser generator:
		ftp://hobbes.nmsu.edu/os2/unix/gnubison.zip

	    FORTRAN-to-C translator:
		ftp://hobbes.nmsu.edu/os2/dev32/f2cbin.zip

       You also might need other utilities (e.g. diff).

       We chose to support this freely-available development environment
       rather than the multitude of commercial environments.

    2) Go to the top-level source directory.
    
    3) Edit the file `emx1.mak' as specified by the in-file commentary.

    4) Sequentially make the targets "all", "test", "install", and
       "clean" using the makefile `emx.mak', e.g.

	    gmake -f emx.mak all

    NOTES:
       o A `make' from the top-level source directory might fail because
         of memory limitations.  In this case you will have to use the
         makefiles `emx.mak' in each of the subdirectories.  Following
         the same sequence that's in the top-level `emx.mak' makefile.

       o If you are making the FORTRAN interface, then you should ignore
         the error messages from the `f2c' translator about inconsistent
         calling sequences and unused external functions.

       o If you are making the C++ interface, then you should ignore the
         error messages from the compiler about "return to `<foo>' from
         `<bar>'" in file cxx/ncvalues.cc.

Questions about building or installing netCDF software should be sent to
support@unidata.ucar.edu.  It would greatly help if you would include
the following information:

    1.  Output from the command `uname -a'.

    2.  Output from the command `env'.

    3.  The file CUSTOMIZE -- but only if it sets something.

    4.  Output from the `configure' script.

    5.  Output from the `make' commands.

Good Luck  :-)

Russ Rew
Steve Emmerson
Glenn Davis
Harvey Davies
