ada_examples/README:

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

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

For each example, use gnatmake to compile the Ada code, with
the "-g" option to include debugging information.

Use apc to compile the probe's APC code into a "User Action
Library" (a .ual file), and aprobe to run program with the probe.

For example,
  gnatmake -g hello_program.adb
  apc hello_probe.apc
  aprobe -u hello_probe.ual hello_program

See the README included with each specific example for exact
details, flags, filenames, etc., required for that example.


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

The directory $APROBE/ada_examples contains 2 subdirectories:

evaluate/
   The directory $APROBE/ada_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.
   See the README file there for details about 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 by the
      files $APROBE/probes/README.*.  This example shows:

      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.exception/

      This is a quick example which shows Aprobe's features for
      handling and reporting Ada exceptions.

   8.lines/

      This example demonstrates setting probes on individual source
      lines.


learn/

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