       JUMPSHOT-2 : A Graphical Visualization Tool for Parallel Programs
       ---------------------------------------------------------------

Jumpshot-2 is a graphical tool which has evolved from Upshot and Nupshot.  It
interprets binary __clog__ tracefiles which displays them on a canvas object.
This file only serves as a guide to configuration of the tool.

In order to run this code, one must have Java 1.1.6 or above.

Directory Structure
--------- ---------

In the jumpshot-2 directory, we have the following subdirectories:

bin/       contains the actual jumpshot wrappers

doc/       contains various jumpshot documentations

lib/       contains jumpshot's setup files and various jar's for the GUI

logfiles/  contains the sample clogfiles

src/       contains the actual JAVA codes for the GUI

swing/     contains the swing library needed to build Jumpshot if you
           are using JDK 1.1.x.



Jumpshot Installation
-------- ------------

In order to build Jumpshot, we need to build four jar files and some
wrapper scripts.  This can be achieved simply by doing the following:

        cd $(JUMPSHOT-2)
        ./configure --with-java=<Your_JAVA_full_pathname>
        make

Where "--with-java=<Your_JAVA_full_pathname>" is optional.  It is necessary
only when configure cannot find a good version of JDK in the typical
java location.   The procedure listed above is for the case when the 
source and installed files are put in the same directory.  The more 
elaborated procedure is to do a VPATH build like the following:

       cd $(build_dir)
       ./configure --with-java=<Your_JAVA_full_pathname> --prefix=<install_dir>
       make
       make install

Or     

       cd $(build_dir)
       ./configure --with-java=<Your_JAVA_full_pathname>
       make
       make install PREFIX=<install_dir>

For further details of configure, do "./configure --help"
After "make install", "make uninstall" will remove all installed files.
        
Note: ignore the warning messages during compilation of jumpshot.jar.

In AIX, be sure the "java -fullversion" return a build data later than 
or equal to "JDK 1.1.6 IBM build a116-19990115 (JIT enabled: jitc)"



Running Jumpshot
------- --------

There are 2 ways to run jumpshot-2.

1, using the supplied script in $(JUMPSHOT-2)/bin:
   cd to $(JUMPSHOT-2)/bin and run Jumpshot by entering "jumpshot" or
   "jumpshot clog_filename", e.g.

   /homes/chan/jumpshot-2> bin/jumpshot logfiles/merge.clog

   With a filename as the command line argument, jumpshot skips the 
   logfile selection process and starts reading the file immediately.

2, run jumpshot directly using "java" or "jre"
   Set the CLASSPATH in your local shell to where jumpshot.jar
   and swing.jar are located.  Check $(JUMPSHOT-2)/bin/jumpshot 
   for exact syntax.  Then you can invoke jumpshot-2 as "java jumpshot"
   or "java jumpshot clog_filename".



Using Jumpshot
----- --------

The documentation on how to use Jumpshot-2, a color PS file is at

ftp://ftp.mcs.anl.gov/pub/mpi/misc/jumpshot.ps.gz


Current Limitations
------- -----------
Jumpshot-2's development is basically stopped.  There are numerous GUI 
bug fixes available in Jumpshot-3 but not in Jumpshot-2.  If you notice 
problems in jumpshot-2 GUI, try convert the clog file to slog file to 
see if the problems go away by displaying using Jumpshot-3.

In case questions, contact mpi-maint@mcs.anl.gov or chan@mcs.anl.gov
