examples/README:

$APROBE/examples is the root directory of a collection of examples
which illustrate the usage and capabilities of Aprobe.  

Running the Examples
--------------------

All the examples use the "make" command, generally found in /usr/ccs/bin.
Generally there is a 'Makefile' for the default C or C++ compiler, an
additional "Makefile.gcc" if appropriate, and possibly other Makefiles
for other supported compilers.    Just follow the directions in the README 
file in each directory.  

Most of the Makefiles have a 'test' target which runs the whole
example, so, for example, you would enter

   make -f Makefile.gcc test

to run the whole example automatically using 'gcc'.  If you just enter
make without specifying the 'test' target, it will build the example
executable and possibly the probe, but won't run aprobe.  

However, each README gives all the steps done by the Makefile, so you'll
learn the most by entering each step "by hand", or at least cutting/pasting
from the README file.


What Is Here
------------

The directory $APROBE/examples contains 4 subdirectories:

predefined_probes/

   The directory $APROBE/examples/predefined_probes/ contains ordered
   exercises designed to introduce a prospective customer to the five
   predefined probes included with Aprobe. The file
   $APROBE/examples/predefined_probes/README provides more information on
   this set of examples.

evaluate/
   The directory $APROBE/examples/evaluate/ contains ordered on-line
   exercises designed to help a prospective customer evaluate Aprobe
   and or introduce a new user to Aprobe.

   It is important to the proper evaluation and understanding of Aprobe
   that you take the time to work through the examples in 
   the "evaluate" subdirectory.  This should take about 45 minutes.
   Below is an excerpt from the README file there in order to illustrate 
   some of the topics covered:

   1.hello/
   
      This shows about the simplest possible probe, which essentially
      prints "I am here." on entry and exit to main().
   
   2.fib/
   
      This is example 2-1 from the Aprobe User's Guide.  It illustrates a
      practical use for Aprobe: counting calls in a recursive program.
      It also shows how variables from the user program can be queried
      from a probe and introduces the concept of "logging" data, which
      minimizes the data to be recorded by deferring the formatting of
      the data until after the program has been run.
   
   3.apcgen/
   
      This example introduces the 'apcgen' tool, which may be used to
      generate probes automatically from the debug information in a
      compiled executable or object file.
   
   4.predefined/
   
      This example introduces the concept of a "predefined probe",
      which is a probe included with the product to perform a specific
      function on any application: you don't have to write any APC at
      all!  Many have a Java graphical interface for configuring the
      probe and for analyzing its results.
   
      The available predefined probes are described in detail in
      Appendix D of the Aprobe User's Guide. This example shows
      one:
   
      trace.ual traces the entry and exit of every function in your
      program.
   
   5.threads/
   
      This example returns us to writing our own apc, and explains the
      motivation and usefulness of the "probe thread" and "probe
      program" constructs.
   
   6.umbrella/
   
      The term "umbrella" in Aprobe refers to the activation of a
      probe only when its enclosing probe is active.  This allows very
      precise control over the events being probed.
   
   7.c++/
   
      This is a bigger example consisting of several C++ files.  It
      illustrates Aprobe's usefulness in examining the behavior of an
      object-oriented application by putting a probe on the
      constructor.
   
   8.exception/
   
      This is a quick example which shows Aprobe's features for
      handling and reporting C++ exceptions.
   
   9.lines/
   
      This example demonstrates setting probes on individual source
      lines.

learn/

   Each directory in $APROBE/examples/learn under this directory
   provides a working example of how to perform a specific task using
   Aprobe.  It builds upon the examples in $APROBE/examples/evaluate,
   and is primarily intended for users who are writing probes for
   their application.
   

hello/
   This directory contains a tiny Aprobe example to help in verifying 
   the correctness of Aprobe installation.  It is automatically 
   executed as part of the installation process, and may be otherwise
   ignored.