$Id: README 1721 2014-03-13 23:03:27Z [email protected] $
$LastChangedDate: 2014-03-13 18:03:27 -0500 (Thu, 13 Mar 2014) $


=============================================================================
=============================================================================

README

=============================================================================
=============================================================================

Contents:
  0. What are hpcviewers and hpctraceviewer
  1. Obtaining and Installing hpcviewer/hpctraceviewer
  2. Building hpcdata
  3. Building hpctraceviewer
  4. For More Information

=============================================================================

----------------------------------------
0. What are hpcviewer and hpctraceviewer
----------------------------------------

hpcviewer is the presentation layer of HPCToolkit which is a suite of tools
for measurement and analysis of program performance.
hpctraceviewer is the presentation tool to visualize trace data generated
by hpcrun if the flag "-t" is specified. For static linked program, the
variable environment HPCRUN_TRACE has to be set. 

The viewers contain six plug-in projects:

 edu.rice.cs.hpc.common (common plugin for hpcviewer and hpctraceviewer)
 edu.rice.cs.hpc.data (hpcdata)
 edu.rice.cs.hpc.remote (hpcremote, used currently by hpctraceviewer)
 edu.rice.cs.hpc.viewer (hpcviewer)
 edu.rice.cs.hpc.traceviewer (hpctraceviewer)
 edu.rice.cs.hpc.traceviewer.data (hpctraceviewer's data management)

hpcdata is the command line version of hpcviewer which is used to read the
database generated by hpcprof (or hpcprof-mpi) into an XML file format.
hpcviewer is a GUI tool to present profile data and hpctraceviewer is 
the presentation layer to display trace data. 

More information can be found at
  http://hpctoolkit.org.



=============================================================================

----------------------------------------
1. Obtaining and Installing hpcviewer
----------------------------------------

Download required software:

    * Eclipse 3.7 (Indigo) version
          o RCP package is necessary  
    * Either subclipse or subversive (the latter is recommended):
          o Subclipse (ver. 1.6 or above) depending the subversion client version
          o Subversive 
    * Java JDK (ver 1.6 or above). SUN or IBM (IceTea) JDK is recommended


Install Eclipse subversion plugin (or subversive):
    o (If you use subclipse, see the subclipse installation website for more details)
    o Go to *Help* - *Install New Software ...* menu
    o On Work with combobox, choose *Indigo - http://download.eclipse.org/releases/indigo*
    o Check the node Collaboration - Subversive SVN Team Developer
    o Go *Next*, then confirm the license aggreement and click *Finish*. 

Check out the source code

    * select File - New - Project menu
    * Select "Project from SVN"
    * Check out from: 

	https://hpcviewer.googlecode.com/svn/trunk 

    * When the window "Check out as" appears, check the option "Find projects in the children of the selected resource"
    * Make sure all six projects are selected: 

    edu.rice.cs.hpc.common
    edu.rice.cs.hpc.data 
    edu.rice.cs.hpc.remote
    edu.rice.cs.hpc.viewer 
    edu.rice.cs.hpc.traceviewer 
    edu.rice.cs.hpc.traceviewer.data 

Now, change the perspective into Plug-in or Java perspective to see the source code and launch the application.

Testing hpcviewer
================

Under edu.rice.cs.hpc.viewer project, launching the application from Eclipse can be done either via

    * product configurations (recommeded):
          o Under edu.rice.cs.hpc.viewer project, open hpcviewer.plugin.product file
          o Then, click "Launch an Eclipse application" 

    * plugin.xml (not recommended, but works in some Eclipse versions)
          o plugin.xml: go to "Overview" tab, and click "Launch an Eclipse application" 

Exporting hpcviewer
================

    * Under edu.rice.cs.hpc.viewer project, open the product configuration: hpcviewer.plugin.product
    * Fill the Root directory and Destination directory fields, then click Finish 
    * Note: make sure that "Generate metadata repository" is unchecked
    * To export to another platform, you need Eclipse delta pack. A How-to of delta pack installation
	can be seen at http://www.vogella.de/articles/EclipsePDEBuild/ar01s02.html

Installing hpcviewer
===================

Once hpcviewer has been exported successfully, we need to prepare a distribution package of hpcviewer:
   * In the command line, go to script directory
   * Run make-dist shell script. The script will generate hpcviewer.tar.gz package file ready to install
   * Copy hpcviewer.tar.gz file into the machine to be installed
	scp hpcviewer.tar.gz your_account@machine:
   * uncompress the tar file 
	tar xzf hpcviewer.tar.gz
   * run install script:
	install [hpctoolkit_installation_directory]


=============================================================================

----------------------------------------
2. Building hpcdata
----------------------------------------

To build the jar file (and the launch script), you need either Eclipse or Apache Ant tool (recommended). 
To build with Apache Ant tool, you just need to go to the script directory:

cd edu.rice.cs.hpc.data/script

then launch the build script with Ant tool:

ant -buildfile hpcdata.xml

This process creates "hpcdata.zip" file which contains hpcdata.jar (the bytecodes), 
required libraries and the launch script (hpcdata.sh). 
Once you unzip the file, you can run the launch script:

sh hpcdata.sh [-o output_file] database_directory

Currently we only provide the launch script for Linux/Unix/Mac OSX. 
Adopting the launch script for Windows platform should be trivial.



=============================================================================

----------------------------------------
3. Building hpctraceviewer
----------------------------------------

Similar to hpcviewer, to launch hpctraceviewer via Eclipse, you need to:

  * select edu.rice.cs.hpc.traceviewer project
  * open hpctraceviewer.product file
  * click Launch Eclipse application

Similar procedures also apply to export and install hpctraceviewer.



=============================================================================

----------------------------------------
4. For More Information
----------------------------------------

WWW Page:
  [www]   http://hpctoolkit.org
  [local] <hpctoolkit-install>/share/doc/hpctoolkit/index.html

Documentation:
  [www]   http://hpctoolkit.org/documentation.html
  [local] <hpctoolkit-install>/share/doc/hpctoolkit/documentation.html

  N.B.: See especially the "Quick Start" chapter of the Users Manual.

Email (for compliments, complaints and cash):
  hpctoolkit-team <at> mailman.rice.edu