(For user documentation of dfepl, the simplified interface to the Daikon
Perl front-end, see the Daikon manual.)

Usage of the Perl front-end is much like dfej and dfec, except that:

* A separate pass is needed to collect information about the types
  of variables, since Perl isn't statically typed.

* The .decls file is generated at the same time as the .dtrace output,
  rather than when the source is annotated.

The steps look like:

1. Generate an instrumented version of the program.
2. Run the instrumented version of the program to guess variable types.
3. Generate a new instrumented version of the program with the types
included.
4. Run the new instrumented version to generate .decls and .dtrace
files.
5. Run daikon on the .decls and .dtrace files.

----------------------------------------------------------------------
NOTE:
The rest of this file is a description of B::DeparseDaikon, the Perl
compiler back-end that instruments Perl programs for Daikon. While the
description is still accurate, there's now an easier-to-use front-end
script named "dfepl" that most people will want to use instead. dfepl
is documented in the regular Daikon manual.
----------------------------------------------------------------------

* Setting up your environment

The front-end works with version 5.8.0 of Perl. (Instrumented programs
can also run with 5.6.* versions, but the instrumenter itself won't.)
"perl -v" will tell you which version of perl you're using. (On the
PAG machines, version 5.8.0 is in /usr/local/bin/perl).

The modules used are in $INV/front-end/perl/lib, so you'll either want
to add "-I$INV/front-end/perl/lib" to the perl command line or add the
directory to the PERLLIB environment variable. (dfepl and dtrace-perl
do this for you).

* Instrumenter

To instrument a file "foo.pl" when you don't have any type
information, say

  perl -MO=DeparseDaikon foo.pl >foo_instrumented.pl

Note that without the redirection, the instrumented version would go
to the standard output. To include type information from a file named
"foo.types", instead say:

  perl -MO=DeparseDaikon,-t,foo.types foo.pl >foo_instrumented.pl

It's important that there be no space around the commas -- the entire
string "-MO=DeparseDaikon,-t,foo.types" has to be one argument from
the shell's point of view.

* Running instrumented programs

Instrumented programs, or programs that use instrumented libraries,
can be run in the usual way. They will generate three output files for
each instrumented package "foo" (recall that a program without a
package declaration will be in the package "main"):

- "foo.types"
  This file includes a guess at the type of any variables whose type
  was unknown when the package was instrumented, but for which
  examples were seen in this execution. Information is always appended
  to this file, and if a type occurs more than once, the instrumenter
  will use the least-upper-bound the occurrences, so using the output
  of multiple runs is safe.

- "daikon-output/foo.decls"
  Declarations for all the instrumented program points that were
  encountered. If the DTRACEAPPEND environment variable is set, these
  will be appended to the file rather than overwriting it. The
  "daikon-output" directory will be created if it does not exist.

- "daikon-output/foo.dtrace"
  Traces the values of variables every time one of the instrumented
  program points is reached. If the DTRACEAPPEND environment variable
  is set, these will be appended to the file rather than overwriting
  it. If the DTRACEFILE environment variable is set, that filename
  will be used instead.

Note that these paths are all relative to the current directory at the
point where they are created; watch out for scripts and makefiles that
call chdir().
