$Id: INSTALL,v 1.7 1996/08/21 16:48:26 rkambic Exp $

INTRODUCTION
------------
Greetings,

This file explains how to incorporate netCDFPerl, the perl extension for
netCDF dataset access, into perl 5.00? on a UNIX system.  (I'm afraid
you're on your own for non-UNIX systems.)


PLATFORMS
---------
I've successfully incorporated netCDFPerl into perl 5.003 on the
following systems:

    Machine		Operating System	C Compiler

    DEC Alpha		Digital UNIX V4.0	/bin/cc
    DEC RISC		ULTRIX 4.5		/bin/cc
    HP 9000/715		HP_UX A.09.05		/bin/c89
    Intel 386		BSDI BSD/OS 2.1		/usr/bin/cc
    IBM rs6000		AIX 4.1			/bin/cc
    SGI IP20		IRIX 5.3		/bin/cc
    SGI IP22		IRIX 6.2		/bin/cc
    SGI IP26		IRIX64 6.2		/bin/cc
    Sun sun4m		SunOS 4.1.4		SC3.0.1/bin/acc
    Sun sun4m		SunOS 5.5		SC4.0/bin/cc


PREREQUISITES
-------------
In order to incorporate netCDFPerl, you must already have version of 
perl 5.003 installed on your system.  Perl can be obtained from URL

    http://www.metronet.com/perlinfo/perl5.html.

You should also have the netCDF package installed.  The version should
be 2.3.2, patch level 4, or later.  The netCDF package can be obtained
from URL

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

In order to be usable by a dynamically-linked netCDFPerl package, the
object modules in the netCDF library should have been compiled in a
position-independent manner, i.e. they should have been compiled as if
they were going to be shared in a dynamic library (which they will be in
a dynamically-linked netCDFPerl module).  The following table gives the
relevant C compiler option that should have been used:

                    Operating System    Option

                    HP-UX               +z
                    SunOS 4.x           -pic
                    SunOS 5.x           -Kpic

On many other systems, generating position-independent code is
the default.  Check the manual page for your compiler for further
information.

If your system has perl4 or an early version of perl5 installed as well as
version 5.003, they must be moved before installing netCDFPerl because the 
netCDFPerl installation will use the old perl binaries.


INSTALLATION INSTRUCTIONS
-------------------------
When you have the prerequisite perl 5.003 and netCDF packages installed, then
do the following to incorporate netCDFPerl:

    1.  Go to the directory containing this file.

    2.  Run the `configure' script:

            ./configure

        This will configure this package's installation procedures.

	The following variables may be used to customize the
	installation process.  They may be set either in the environment
	or in the file CUSTOMIZE.

	    Variable	Meaning
	    --------	-------
	    CC		C compiler.  You should use the same C
			compiler that was used to build perl.
                        If you don't know which C compiler that was,
                        then use the one that the configure script
                        determines and see what happens.  On an IRIX64 6.2 
			system, you must ensure that the same Application
			Binary Interface is used for the perl, netCDF, and
			netCDFPerl packages.

	    CPP_NETCDF	C compiler reference for the location of the
			netCDF header file (e.g.
			`-I/usr/local/include').

	    LD_NETCDF	Linker reference for the location of the
			netCDF library (e.g. `-I/usr/local/lib -lnetcdf').

	    PERL	Pathname of the perl(1) utility.  If given, it
			*must* refer to a perl 5 utility (and not a perl
			4 one).

	    PERL_MANDIR	Pathname of the root of the directory hierarchy
			that contains the perl manual pages (e.g.
			`/usr/local/man').  The netCDFPerl(1) manual
			page will be install under this directory.

        The configure script will look for your installed netCDF package
        and for your perl package.  If it can't find them, then it will
        tell you how to help it find them (via the variables mentioned
        above).

    3.  Execute `make'.  This will build netCDFPerl in the perl/
        subdirectory.  On systems that support dynamic libraries, a
        netCDFPerl dynamic library will be built.  On systems that
        lack dynamic library support, a new, statically-linked perl
        utility will be built that incorporates netCDFPerl as well as
        all previously incorporated extensions (e.g. TkPerl).

        NOTE: On a DEC RISC/ULTRIX 4.5 system, the perl-generated
        makefile `perl/Makefile' incorrectly believes that
        running the ranlib(1) utility on the created library
        perl/blib/auto/NetCDF/NetCDF.a is unnecessary.  Thus, the `make'
	will fail.  The workaround is to manually run ranlib(1) on the 
	library man and then re-execute the `make'.

    4.  Execute 'make test'.  This will test netCDFPerl.  The perl
        script that executes the test is in perl/test.pl.  You might
	wish to peruse it as an example.

    5.  Execute `make install'.  This will incorporate netCDFPerl
        and its manual page into the perl installation.  To do this,
        you might need to be the user who originally installed
        perl.  NOTE: Currently, there is a bug in the perl/Makefile
        created by perl.  To correct the problem, edit the file
        per/Makefile: on the line with "MOD_INSTALL" (near line 210) add
        "-I$(PERL_ARCHLIB)" before "-I$(PERL_LIB)".

    6.  Execute `make realclean'.  This will remove all intermediate
	files, allowing you to incorporate netCDFPerl on another platform.


SUPPORT
-------
Questions should be directed to support@unidata.ucar.edu.  For help
on installation, please enclose everything possible that might help a
diagnosis.  I suggest the following:

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

    2.  The file `VERSION'.

    3.  Output from executing the configure script.

    4.  The file `config.log'.

    5.  Output from the command `make all' (if possible).

    6.  Output from the command `make test' (if possible).

    7.  Output from the command `make install' (if possible).


Regards,
Steve Emmerson	<support@unidata.ucar.edu>
Robb Kambic <support@unidata.ucar.edu>
