Overview of Tool Gear, Memcheckview, Mpipview, Umpireview, and dynTG
--------------------------------------------------------------------

Tool Gear is an open source (BSD license) infrastructure for quickly
creating GUIs for tools.  Several GUIs for popular open-source tools 
have been created using Tool Gear (described below).   This tarball
contains one or more of these Tool-Gear-based GUIs.  Instructions for
building the GUIs included in this tarball can be found in INSTALL.
  
Tool Gear 2.00 is a major new Tool Gear release with a new XML-based 
interface.  Tools written in any programming or scripting language
can quickly be adapted to offer a Tool Gear GUI by generating output
in our XML format.  Detailed documentation on how to create new tools
using Tool Gear 2.00's XML interface can be found in CREATING_NEW_TOOLS.

The full Tool Gear 2.00 tarball includes four Tool-Gear-based GUIs
(memcheckview, mpipview, umpireview, and dynTG).  By popular demand, 
Tool Gear is now providing tar balls of individual tools (i.e., 
just mpipview or memcheckview) as well as for all the tools 
in one tar ball at www.llnl.gov/CASC/tool_gear.

Demos of the GUIs for mpipview, memcheckview, and umpireview can be found in
demos/TGui (and don't require mpiP, Valgrind, or Umpire to be installed).
See demos/TGui/README for details on how to run the demos.

Here is a brief description of the tool GUIs and scripts available
(the full Toolgear 2.00 tar ball contains all these tools):

Mpipview 2.00:

  mpipview provides a GUI for the lightweight, scalable MPI profiling 
  tool 'mpiP' (www.llnl.gov/CASC/mpip) and now supports mpiP 2.9.


Memcheckview 2.00:

  memcheckview provides a GUI for Valgrind's heavy-weight memory tool 
  Memcheck (requires Valgrind 3.0.1 or later).  Valgrind documentation,
  downloads, etc. can be found at valgrind.org.

  memcheck is a script that runs Valgrind's Memcheck tool (i.e, valgrind 
  --tool=memcheck --xml=yes) on serial applications with the memcheckview GUI
  displaying Valgrind's warnings as they are found.

  memcheck_all is a script that runs Valgrind on parallel MPI applications and
  includes support for Valgrind's new MPI wrappers, which dramatically 
  reduce false positives for MPI applications.  To use the new MPI wrappers,
  you will need to set MPI_WRAPPERS to the appropriate path in the 
  memcheck_all script.  memcheckview is used to view the output files 
  generated by memcheck_all.


Umpireview 2.00:

  umpireview provides a GUI for viewing the output of Umpire, an MPI wrapper 
  library that detects unsafe or erroneous MPI usage.  Umpire was written by 
  Bronis de Supinski, John May, Jeff Vetter, Chris Chambreau, and 
  Martin Schulz at LLNL. (A web page to download Umpire from LLNL 
  is expected soon.)


DynTG 2.00:

  DynTG is a tool for interactive, dynamic instrumentation of either
  serial or parallel applications.  Users can insert calls to timers,
  hardware performance counters or other instrumentation on the fly.
  DynTG was written by Martin Schulz, John May, and John Gyllenhaal at LLNL.
  DynTG relies on DPCL for instrumentation and is currently only supported
  on AIX (other ports are in progress).


Each GUI or tool is invoked by a script in the bin directory.  Run the 
following user scripts (if present) with no arguments for usage info:

  mpipview:        Displays GUI for mpiP output file
  memcheck:        Runs Valgrind's Memcheck tool on serial program (w/GUI)
  memcheck_all:    Runs Valgrind's Memcheck tool on parallel program (w/o GUI)
  memcheckview:    Displays GUI for Valgrind Memcheck XML output file
  umpireview:      Displays GUI for Umpire output files
  dyntg:           Runs dynamic instrumentation tool on serial or parallel app


The bin directory may also contain the following utility programs and files
that are used by the above scripts but are not typically used directly 
by the user (and are not installed in /usr/local/bin by "make install",
see INSTALL file for details):

  install_links:   Installs links to user-level scripts in specified location
  TGui:            XML interface script used by most GUIs (e.g., mpipview)
  TGclient:        Tool Gear's GUI client, used by TGui (and thus by most GUIs)
  TGxmlserver:     Tool Gear's XML server, used by TGui (and thus by most GUIs)
  TGmemcheck2xml:  Converts Valgrind's XML into Tool gear XML (memcheckview)
  mpi_suppression: Memcheck suppression file for Elan3 MPI (used by memcheck)
  TGmpip2xml:      Converts MpiP text output into Tool Gear XML (mpipview)
  dpclcol:         Tool Gear's DPCL server (used by dyntg)
  AIXisParallel:   On AIX, determines if a program uses MPI (used by dyntg)
  TGLICENSE:       The BSD license used by Tool Gear


Please direct questions, bug reports, and feedback on any of these GUIs
to either John Gyllenhaal (gyllen@llnl.gov) or John May (johnmay@llnl.gov).
DynTG-specific questions may be also be directed to Martin Schulz 
(schulz6@llnl.gov).