/* 
* File:    README
* CVS:     $Id: README,v 1.8 2009/09/08 15:42:38 terpstra Exp $
* Author:  Philip Mucci
*          mucci@eecs.utk.edu
* Mods:    Dan Terpstra
*          terpstra@eecs.utk.edu
*/  

This directory contains:

README		This file.
LICENSE.txt	The text of the PAPI license.
INSTALL.txt	Instructions for installing on all supported platforms.
src/ 		The PAPI library source files and support files.
			See src/README for details.

NOTE on directory contents
--------------------------

Previous releases of PAPI contained man/ and doc/ directories with man pages
and user documentation. These contents have now been placed online and can be 
found under the PAPI References link on the main PAPI web page at: 
http://icl.cs.utk.edu/papi/, or directly at: 
http://icl.cs.utk.edu/projects/papi/wiki/Main_Page


Getting Started
---------------

If this is the first file you've opened in the PAPI tree, we'll try to give you
a few tips on where to go from here.

- Read the license found in LICENSE.txt. It's pretty short, and not very 
  restrictive, but it'll give you an idea of what you can and can't do with the
  PAPI sources.
- Visit the website at: <http://icl.cs.utk.edu/papi>
  There you can find late-breaking news that may be more current than in these
  files. You can also find a variety of online documentation for the PAPI API.
- Subscribe to the PAPI User Forum. A link can be found on the PAPI home page.
- Sign up for the PAPI mailing list(s). Instructions are under the Contacts tab
  on the PAPI home page.
- Scan the RELEASENOTES.txt file to get an idea of what's new in the current release.


Installing PAPI
---------------

To install PAPI on your system:
- Find the section in INSTALL.txt that pertains to your hardware and operating
  system.
- Follow the directions to install required components and build the PAPI
  libraries.
- Run the test suite when you are finished to verify that everything went ok.
  NOTE: Although we make every attempt to get all tests to PASS or SKIP on all
  platforms, there are occasional instances of FAILures due to excessively 
  tight compliance thresholds or platform ideosynchracies. Occasionally a test
  may FAIL when run from the script and PASS when run from the command line.
  Sometimes a test is on the edge and will PASS on some runs and FAIL on 
  others. Don't panic if one or two tests FAIL. Contact us with complete 
  output and we'll see what we can do.

Using PAPI
----------

To use PAPI in your own programs:
- Read the User's Guide found online at: 
  http://icl.cs.utk.edu/projects/papi/wiki/User_Guide. 
- Try out the utility programs in /utils to see what's in your system.
- Try a test program. Source for a number of tests in both C and FORTRAN is
  available in the src/tests/ and src/ftests/ directories. Find a program
  that's similar to what you want to do. Make sure you can build it and run it.
- Write a test program of your own, exercising the PAPI events and features of
  interest to you.
- Go for broke. Fold PAPI calls into your sources and see what you can learn.


Bugs and Questions
------------------
- Visit our FAQ at: http://icl.cs.utk.edu/papi/faq/
- Join the PAPI User Forum at: http://icl.cs.utk.edu/papi/forum/
- Subscribe to the PAPI mailing list at:
  http://lists.eecs.utk.edu/mailman/listinfo/ptools-perfapi
- Read historical postings to the forum and mailing list.
- Post questions.
- Post bugs to the PAPIZilla bug tracker at:
  http://icl.cs.utk.edu/projects/papi/bugz/