% INSTALLATION OF GTOOL4
% Copyright (C) GFD-Dennou Club, 2001.  All rights reserved.
%
% 2001-12-09 TOYODA Eizi

1. GENERAL DESCRIPTION AND REQUIREMENTS

	gtool4 is a general Fortran I/O library for array-oriented data.
	This depends on three software packages - NETCDF, DCL, and DCL-F90.
	Recommend versions are:
		netcdf 3.4 (or later),
		dcl 5.2 (or later),
		and dcl-f90-unix of 2001-12-08 (or later).
	You must have Fortran 90 (or later) compiler for all packages,
	and C compiler to build netcdf and/or dcl.

	If you have binary packages for netcdf or dcl, be careful
	about what compiler the binary package is built for.
	G77/F2C have a different linkage convention and runtime library
	to that of Intel/Fujitsu/Lahey Fortran compiler; so you have to
	rebuild netcdf and dcl from the source code if you have package
	only for G77.

2. HOW TO INSTALL

	Like many other softwares, gtool4 can be installed with
	`configure, make, make install' manner. But you have to 
	tell the configure script something about your environment.

	The configure script saves these options at exit time, and
	you have not to specify these options again when you rerun
	configure.

 2.1 check your Fortran compiler

	By default, configure detects Fortran compiler automatically.
	(It is done by a shell script `chkfort.sh'.)
	If you do not agree with the configure's choice, rerun it with
	environment variable FC.

	In Bourne shell:

		$ FC=f90 ./configure

	In C shell:

		% setenv FC f90
		% ./configure

 2.2 check your NetCDF

	You have to tell configure about your netCDF library:

		./configure --with-netcdf=/usr/lib/libnetcdf.a

	Make sure that the netcdf library is built for the same
	Fortran compiler as the compiler you are going to use.

 2.2 check your DCL-F90

	If you have a normal installation of DCL-F90 after
	2001-12-08, you have `dclf90config' script and it gives us
	enough information about dcl and dcl-f90.

 2.2.1 specify dclf90config

	If you have dclf90config command in your $PATH, you have to
	add no options for configure. Otherwise, specify its path
	when running configure:

		./configure --with-dclf90config=/usr/local/bin/dclf90config

 2.2.2 specify libdclf90.a and dclconfig (not recommended)

	If you have DCL-f90 of earlier version without dclf90config, 
	the configure script will try to check dclconfig script
	and dcl-f90 library.

	By default, only `dclconfig' command in your $PATH is searched
	automatically. If you are to use another dclconfig, specify
	it with --with-dclconfig= options:

	    ./configure --with-dclconfig=/usr/local/dcl-5.2/bin/dclconfig

	Currently dcl-f90 library is not searched automatically.
	Specify its path:

	    ./configure --with-dclf90lib=/usr/local/dcl-f90/lib/libdclf90.a

 2.3 runtime library

	In most environment, system dependent routines in (OSLIB of) DCL
	are well configured with its configure script.
	Gtool4 uses DCL OSLIB routines by default, and it works well.
	(So if you are unsure, skip this section first and read here
	when something goes wrong.)
	
	But sometimes it may fail and OSLIB procedures are replaced
	with dummy (subroutines doing nothing).
	If you have such a misconfigured DCL and are forced to use it,
	select gtool4's system dependent routine.

	--with-arg=dcl		CALL DCL's OSGARG/OSQARN (default)
	--with-arg=hitachi	CALL GETARG/IARGC (suitable for HITACHI)
	--with-arg=common	CALL GETARG/IARGC (suitable for others)


	--with-abort=dcl	CALL DCL's OSABRT (default)
	--with-abort=abort	CALL ABORT (suitable for DEC/Sun)
	--with-abort=errtra-setrcd
				CALL ERRTRA, SETRCD, and EXIT
				(suitable for Lahey/Fujitsu Fortran)
	--with-abort=exit	CALL EXIT (suitable for Intel Fortran)
	--with-abort=setrcd	CALL SETRCD and EXIT
				(suitable for Fujitsu FQS frt)
	--with-abort=stop	siply STOP 3 (suitable for HITACHI)

 2.4 decide directory to install gtool4

	By default, gtool4 is installed to /usr/local/gtool4.
	If you are to install it to another place, tell configure
	with --prefix=<directory> or --bindir=<directory> options:

	    ./configure --prefix=/home/toyoda

3. BUILD

	$ make

	You can also test the result. It will invoke six test scripts:

	$ make test

	Sometimes the last test (diffusion.sh) fail with much output,
	but don't be serious.  It is caused by difference in expression
	and truncation of numbers.  Please tell me if you have a better
	idea than taking diff.

4. INSTALL

	$ make install

	It it works, that's all.

5. TIPS

 * FQS (Fujitsu Kyushu Software) compiler

	Make sure that the option -Am is specified as SYSFFLAGS.

 * Intel Fortran compiler

	Make sure that the option -Vaxlib is specified as SYSLDLIBS.

6. CAUTION FOR PROGRAMMERS

	The original source code is written in character set SHIFT_JIS.
	For most environment, it is better to use EUC-JP than SHIFT_JIS,
	then the source code is converted automatically into EUC-JP.
	If you are to do cvs diff/commit, you have to convert it back to
	SHIFT_JIS:

	$ make shift_jis
	
