           Installation Instructions for Ufiles-related Modules

Prepared by C.Ludescher-Furth -- 10/01/01

****************
REVISION HISTORY
****************
      date          Description

  May  15, 1999  -- Created
  Oct.  1, 2001  -- Use <subdir>/Makefile instead of TRANSP scripts.
  May  07, 2004  -- Added ufile's idl functions.

Index:
   1.  CONTENTS
   2.  UNPACKING INSTRUCTIONS
   3.  DESTINATIONS
   4.  BUILDING INSTRUCTIONS
   4A. BUILDING libufshr
   4B. Ufile IDL functions
   5.  TESTING INSTRUCTIONS
   6.  DOCUMENTATION
   7.  FINAL INSTALLATION


************
1. CONTENTS:
************
This directory should contain the following files:

   - README            --  brief description
   - INSTALL 	       --  detailed installation (this file)
   - Makefile          --  to build all all libraries and test programs 
   ./share             --  include file Make.flags, Make.local.sample
   ./include/fpreproc  --  *.h files for cpp
   ./fpreproc          --  scripts for pre-processing of fortran
   ./portlib           --  internally used library
   ./vaxonly           --  internally used library (no relation to VAX)
   ./sgdummy           --  stubs for sglib
 
   ./<libdir>          --  Makefile and sources for various libraries

**************************
2. UNPACKING INSTRUCTIONS:
**************************
Note: Download the module(s) into an empty directory.

for tarfiles:
  > gunzip <module>.tar.gz
  > tar xvf <module>.tar

or, for zip archives:
  > unzip <module>.zip

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

When you extract the tar file you get sub directories:
./share             --  include file Make.flags, Make.local.sample
./include/fpreproc  --  *.h files for cpp
./fpreproc          --  scripts for pre-processing of fortran
./test              --  sample data for testing

./<libdir>          --  Makefile and sources for various libraries


The makefile will create more sub directories,

lib:     for the library, libxplasma.a
mod:     for the f90 modules
obj/*:   for compiled objects and pre-processed sources
test:    for the test programs and the sample output files.

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

You can overwrite the destination by defining OBJ, as an environment
variable (e.g. 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 rationale 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:
************************* 

Steps to do:
------------
For example, if you were to download the archives into directory /scratch/foo,
to install the package, you would use the following commands:

If you have downloaded tarfiles in /scratch/foo:
> cd /scratch/foo
> gunzip <module>.tar.gz
> tar xmvf <module>.tar
> /usr/local/bin/gmake all >& my.log &
  or
> /usr/local/bin/gmake all OBJ=. >& my.log &


If you have downloaded zip archives:
> cd /scratch/foo
> unzip -qo <module>
> rm <module>.zip
> /usr/local/bin/gmake all >& my.log &

This will make all Ufiles-related libraries and test programs/utilities
of the module(s) that you have downloaded including xtc.
During the make, some compiler warnings are likely to be generated.
Usually, these can be ignored.  However, more serious errors should
be reported to the authors.

> gmake checklibs      -- tells you what the makefile will do
                          (without any action);
                          it says which libraries it will make and
                          which ones it already found and where.
 
> gmake clean          -- to remove objects
> gmake realclean      -- to remove objects and library

> gmake show_makeflags -- to display make definitions


Command Line Editing Feature:
-----------------------------
The Makefile tries to determine if you have command line editing libraries
"-lreadline -lhistory -ltermcap" and accordingly compiles portlib and links
programs. If your site has a partial installment,
define  NO_EDITLIBS

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


Porting:
========
The following architectures are supported:

AIX
IRIX64
HP_UX
OSF1
SunOS 
Linux 
Alpha Linux
CRAY 


Compiling on Linux:
-------------------

By default the Makefile will select Lahey Fujitsu.

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.


               ----------------------------------

If you have any problems or need to add a new architecture, the files
to change are:

share/Make.flags   : for SGLIB and Xtc / Tek
sglib/Makefile     : for sglib
xtctek/Makefile    : for Xtc / Tek

Customizing:
------------
To define custom specific installations 
rename share/Make.local.sample to share/Make.local
and edit it accordingly.


*********************
4A. BUILDING libufshr
*********************
To build a shareable image of uflib:
 
1. you will also need the modules TrGraf and SGlib
   (if you downloaded uutil, you already have everything)
2. build all libraries as described in "4. BUILDING INSTRUCTIONS"
3. make libufshr.so
   - cd uflib
   - gmake SHARED=Y so
     libufshr.so will be in ../<MACHINE>/lib/libufshr.so
4. copy libufshr.so into your "site specific" library directory
   - the library location must be in the LD_LIBRARY_PATH of the users
   - if you have an MDSplus Server, it must also be in the Servers, PATH


***********************    
4B. Ufile IDL functions
***********************    
IDL functions to read/write Ufiles are in subdirectory mdspro.
Copy these functions into your "site specific" location.
The location must be in the users's IDL_PATH



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

Data files for testing are provided in the subdirectory "test".
For convenience, do a "cd" into this directory.

To test Ufiles Library, use uftype:
===================================
"uftype" is a user interactive Ufiles format analysis / conversion tool
(for online help type <MACHINE>/test/uftype).
 
> cd <MACHINE>/test
> ./uftype ACS37065.ECS

output should be:
 %UFINIT -- using root directory for temporary files:
 /u/xshare/
 ACS37065.ECS:  portable_binary 2d   nsc=1  npt=65536  4096x16 
 [OLD VALUE:  "ACS37065.ECS                                      ..."]
uftype:  enter filename:

enter "q" to quit

               ------------------------------------

To test Trgraf Module, use tgtest:
==================================
"tgtest" uses SGLIB to plot data, contours, etc. See sglib/README to test
SGLIB.
Also, for SGLIB, TERMINAL_TYPE must be defined
e.g.: TERMINAL_TYPE=XTERM

> cd <MACHINE>/test
> ./tgtest @tgtest.ind

               ------------------------------------

To test full set of utilities:
===============================
All utilities need SGLIB. See sglib/README to test SGLIB.
Also, for SGLIB, TERMINAL_TYPE must be defined
e.g.: TERMINAL_TYPE=XTERM

The utility programs are described briefly in the "utilities" section
of "Ufiles Help", an HTML version of which is accessible via the Ufiles
home page.

> cd <MACHINE>/test
> ./concat  @concat.demo
> ./extrac  @extrac.demo
> ./gaver1  @gaver1.demo
> ./gsmoo1  @gsmoo1.demo
> ./gsmoo2  @gsmoo2.demo
> ./propane @propane.demo
> ./sawtoo  @sawtoo.demo
> ./splice  @splice.demo
> ./splice2 @splice2.demo
> ./thin1   @thin1.demo
> ./thin2   @thin2.demo
> ./ugraf1  @ugraf1.demo
> ./ugraf2  @ugraf2.demo


************************
6. DOCUMENTATION:
************************

Ufiles Home Page:
http://w3.pppl.gov/NTCC/Ufiles

NTCC Home Page:
http://w3.pppl.gov/NTCC


**********************
7. FINAL INSTALLATION:
**********************

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

You define your choice of root directory via PREFIX.
The default for PREFIX is /usr/ntcc.

The assumptions are:

libraries in: $PREFIX/lib        = $LIBDIR       
programs  in: $PREFIX/bin        = $BINDIR
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  
    to install into /usr/ntcc/...

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

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

NOTE:
-----
All libraries are installed following unix conventions.
Users should link with:

-L<PREFIX>/lib -luflib -lufhdf, etc.

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.

Note:
      You might wish to preserve the demo files in subdirectory "test".


----------------------------------------------------------------------------

IF YOU HAVE ANY PROBLEMS, PLEASE CONTACT EITHER:

        TRANSP Support - transp_support@pppl.gov

	Princeton Plasma Physics Laboratory
