           Installation Notes for NSCRUNCH

Prepared by C.Ludescher-Furth cludesche@pppl.gov  04/09/99


Index:
   1. UNPACKING INSTRUCTIONS
   2. CONTENTS
   3. DESTINATIONS
   4. BUILDING INSTRUCTIONS
   5. TESTING
   6. FINAL INSTALLATION

**************************
1. UNPACKING INSTRUCTIONS:
**************************

for tarfiles:
  > gunzip nscrunch.tar.gz
  > tar xvf nscrunch.tar

or, for zip archives:
  > unzip nscrunch.zip


************
2. CONTENTS:
************

INSTALL_Nscrunch: This file.  Brief descriptions of the other files, and
                  instructions for compiling, testing and installing the
                  library libnscrunch.a and its test driver scrunch. 

README_Nscrunch:  Description of NSCRUNCH.

Makefile:         NOTE, "GNU make" must be used
                  (usually in /usr/gnu/bin or /usr/local/bin).
		  Main Makefile to envoke Makefile(s) in subdirectories.  

-- in subdirectory nscrunch:
   Copy of README
   Copy of INSTALL

   Makefile:   NOTE, "GNU make" must be used
            (usually in /usr/gnu/bin or /usr/local/bin).

   Sources to build libscrunch.a: *.f90, *.F90

   Sources for test program: drive.f 

   Sample output file: drive.ref
 
-- in subdirectory share:
   Make.flags:        Include file for Makefile, to setup Flags, etc.
   Make.local.sample: Include file for Makefile, to setup non-conventional,
                      site specific locations.

-- in subdirectory portlib:
   Makefile
   Sources to build internally used library libportlib.a.

-- in subdirectory fpreproc:
   Python scripts for fortran pre-processing.

-- in subdirectory include/fpreproc:
   *.h files for source pre-processing.

****************
3. DESTINATIONS:
****************
Or where do the files go?
(this refers to building and testing; see FINAL INSTALLATION for end result) 

The makefile will create the following sub directories,
include: for common include files
lib:     for the library, libscrunch.a
mod:     for the f90 modules
test:    for the test program "scrunch" and the sample output.
obj/nscrunch:   for preprocessed sources and objects

By default these directories are created in  
./<MACHINE>, which is determined by the Make.flags.
e.g.: if you are running Linux, and the tar file resides in $HOME/foo,
      the directories would be
      $HOME/foo/nscrunch
      $HOME/foo/LINUX/lib
etc.

You can overwrite the destination by defining OBJ, as an environment
variable (e.g. in your login setup, export OBJ=/dir1/dir2),
or with make (e.g. "make all OBJ=..").
If OBJ is defined, the destinations will be
$OBJ/lib and $OBJ/test.
If OBJ is defined as ".." then in the example above, the destination
would be $HOME/foo/lib.

The rational behind <MACHINE> is to facilitate building for various platforms.

Note: If you define OBJ as option to gmake, you have to consistently do so;
      e.g: gmake clean OBJ=., gmake install OBJ=.


*************************
4. BUILDING INSTRUCTIONS:
************************* 

NOTE:  The following libraries are required:
====       blas

blas is assumed to be in /usr/local,
if not, you can specify the location with LIBROOT,

e.g.: "gmake all LIBROOT=/usr/contrib".

Alternatively you can modify Make.local.sample
and rename it to Make.local.

Building libnscrunch.a and test propram
----------------------------------------
> gmake          -- to build/link library and programs

> gmake checklibs  -- tells you what the makefile will do
                      (without any action);
                      it sais which libraries it will make and
                      which ones it already found and where.
> gmake clean     -- to remove all .o files
> gmake realclean -- to remove everything but sources.


By default the Makefile will select Fujitsu f95.

To select a different compiler define
FORTRAN_VARIANT to "Portland"  "NagWare"  "Fujitsu" or "Absoft"

e.g.:
setenv FORTRAN_VARIANT Portland (csh)
FORTRAN_VARIANT=Portland; export  FORTRAN_VARIANT (sh)

Alternatively, FORTRAN_VARIANT can be passed directly to the gmake
command, as in:
gmake  FORTRAN_VARIANT=Portland

To use vastf90:
> gmake VAST90=y

To use NAG90: 
> gmake NAG90=y


Compiling on Alpha Linux:
-------------------------
The Makefile assumes the Compaq compiler and specifies the 
 " -assume no2underscores " option.

Therefor the calling user software must also be compiled with this
option, or you should edit share/Make.flags to remove the option.


Compiling on SUN:
-----------------
The Makefile specifies the " -fast " option which includes -dalign.
Therefor the calling user software must also be compiled with this
option, or you should edit share/Make.flags to remove the option.



***********
5. TESTING:
***********

directory $OBJ/test  -or-  <MACHINE>/test  will contain:

scrunch     :  Test driver for NSCRUNCH
drive.res   :  sample result file

To run test:
cd <MACHINE>/test
./scrunch

For details see README or http://w3.pppl.gov/NTCC/Nscrunch


**********************
6. FINAL INSTALLATION:
**********************

Choose or create the root directory in which you wish to install the software.
Common locations would be /usr/transp or /usr/ntcc, but installation
can occur in any directory where you have appropriate permissions.

You define your choice of root directory via PREFIX.
There is "no default" for PREFIX.

The assumptions are:

libraries in: $PREFIX/lib        = $LIBDIR       
man pages in: $PREFIX/man/man3   = $MANDIR/man3

To install the software, return to the top directory (the directory,
where you downloaded the tar files) and type

> gmake install PREFIX=/dir1/dir2/
    to install into /dir1/dir2/...

> gmake install
    if you are using Make.local


If you want things elsewhere, you can overwrite the default with
> gmake install LIBDIR=/yyy MANDIR=/zzz

NOTE:
-----
The library is installed as libnscrunch.a
Users should link with

-L<PREFIX>/lib -lnscrunch

Make sure users know what <PREFIX> is.

After you have installed the software, you can delete the entire tree
with
> cd ..
> rm -r foo
   assuming the previous example.
