Skip to content
Branch: master
Go to file
Code

Latest commit

Files

Permalink
Failed to load latest commit information.

README

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

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 seven plug-in projects:

 edu.rice.cs.hpc.common (common plugin for hpcviewer and hpctraceviewer)
 edu.rice.cs.hpc.data   (hpcdata)
 edu.rice.cs.hpc.filter (hpcfilter plugin for hpcviewer and hpctraceviewer)
 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. 

The viewers also requires two additional plugins from hpcviewer-externals
https://github.com/HPCToolkit/hpcviewer-externals :

 com.graphbuilder (Java parser for mathematical expression)
 org.swtchart     (Java library for plotting charts)

These libraries are not copyrighted by Rice University, and maintained by 
their respective original authors and customized for HPCToolkit viewers. 

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



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

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

Download required software:

For Mac OS:
    * Eclipse 4.6.x (Neon) version or newer
          o Eclipse for RCP and RAP Developers
    * Java JDK (ver 1.8 or above). OpenJDK, Oracle or IBM (IceTea) JDK is recommended
    * Technically, this version of Eclipse works also on Linux and Windows but with 
      some bugs on TWM window manager and some performance bugs.

For Linux and Windows platforms:
    * Eclipse 3.7.x (Indigo) 
          o Eclipse for RCP and RAP Developers
    * Java JDK (ver 1.7). Oracle or IBM (IceTea) JDK is recommended


Check out the source code

    * select File - Import menu
    * Select "Project from Git"
    * Clone from: 

        https://github.com/HPCToolkit/hpcviewer.git

    * Select master branch
          o For Eclipse 3.7.x: select indigo branch
         
    * Import existing Eclipse projects
    * Make sure all these projects are selected: 

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

Check out the external libraries

    * select File - Import menu
    * Select "Project from Git"
    * Clone from: 

        https://github.com/HPCToolkit/hpcviewer-externals.git

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

    com.graphbuilder
    com.jcraft.jzlib
    org.swtchart
    org.swtchart.ext
    
Now, change the perspective into Plug-in or Java perspective to see the source code and launch the application.

Note:
    * there will be many Java warnings, but no error messages. Some test projects (like test.swtchart) may cause 
      error messages on certain platform. If this is the case, it's safe to close the project.
    * If you are on Windows or Linux platforms, it's highly suggested to use Eclipse 3.7.x instead of Eclipse 4.x due
      to performance bugs in Eclipse compatibility layer in Eclipse 4.x.  


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:
	  	- for Eclipse Indigo: open hpcviewer.indigo.product file
	  	- for Eclipse Neon:   open hpcviewer.plugin.product file
	  	- for Eclipse Photon: open hpcviewer.photon.product file
	  	- for Eclipse 2018:   open hpcviewer.simrel.product file
	  	- for Eclipse 2019:   open hpcviewer.2019.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, see Eclipse instructions:
      https://wiki.eclipse.org/A_Brief_Overview_of_Building_at_Eclipse#Preferred_way_of_doing_multi-platform_builds
      
      
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 (right now only support Eclipse Neon), 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 


About

HPCToolkit performance tools: hpcviewer and hpctraceviewer graphical user interfaces

Resources

You can’t perform that action at this time.