daikon.texinfo

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename daikon.info
@settitle The Daikon Invariant Detector User Manual
@c %**end of header

@c To update all the nodes and menus all at once:   C-u C-c C-u m
@c You shouldn't need to do that, though; makeinfo does it for you.

@c I can't get this to work, don't know why.  MDE 4/2001.
@c @alias directory = file

@c Note about ``@table @option''.
@c Unfortunately, @option{} adds quotes in the Info and printed output
@c which is not necessary in a table.  However, @t and @code compress any
@c two adjacent hyphens to one in Info and HTML output, which is even worse.

@c Problem: with texinfo 4.0, the HTML formatting leaves the "{}" after
@c uses of the macro.  (Formatting seems fine for info, for printing, etc.)
@c So for now, I have inlined all instances of the macro.  Yuck.
@c Another solution would be to use "makeinfo -E" (then process the
@c resulting file with "makeinfo --html").

@macro daikonemail{}
@email{daikon-developers@@googlegroups}
@end macro

@macro nospellcheck{text}
\text\
@end macro

@tex
\global\tableindent=.4in
@end tex

@c set overall document style
@c @setchapternewpage odd
@paragraphindent 1
@firstparagraphindent insert
@codequotebacktick on
@c default value for example indentation
@set exin 4
@c default value for example indentation within an @enumerate
@set exinenum 1
@exampleindent 4

@c Avoid black boxes marking overfull hboxes in TeX output.
@finalout

@c Start of Document

@titlepage
@sp 10

@c Could also use @title, @subtitle, @author here.
@center @titlefont{Daikon Invariant Detector User Manual}

@sp 2
@center Daikon version 5.6.7

@sp 1

@ifset final
@c FINAL version
@c Print out the Daikon version 5.6.7 release date
@center July 2, 2018
@end ifset

@ifclear final
@c DRAFT version
@center DRAFT Version @today{}
@end ifclear

@sp 5
@c reads daikon-logo.{eps,pdf} (not .txt, .png, or .jpg, because info
@c and HTML don't get the title page)
@image{images/daikon-logo,4in,}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998-2014
@end titlepage

@c set document heading/footing style
@c The texinfo support for headings is too broken to use;
@c perhaps we could fix texinfo.tex some day.
@c @headings off
@c @evenheading @thispage @| @thischaptername @| Chapter @thischapternum
@c @oddheading Section @thissectionnum @| @thissectionname @| @thispage
@c @oddheading Chapter @thischapternum: @thischaptername @| @| @thispage
@c @evenheading @thispage @| @| Section @thissectionnum: @thissectionname

@ifclear final
@c DRAFT version
@everyfooting DRAFT @| @| @today{}
@end ifclear

@html
@image{images/daikon-logo}
@end html

@c Putting this lower in the HTML version looks a little bit strange,
@c but it's acceptable.
@ifnothtml
@contents
@end ifnothtml

@ifnottex
@node Top
@top Daikon Invariant Detector User Manual

This is the user manual for the Daikon invariant detector.
It describes Daikon version 5.6.7, released July 2, 2018.

@menu
* Introduction::
* Installing Daikon::
* Example usage::
* Running Daikon::
* Daikon output::
* Enhancing Daikon output::
* Front ends (instrumentation)::
* Tools::
* Troubleshooting::
* Details::
* General Index::

@c Putting end menu here is not how it's supposed to be done,
@c but it seems to fix the html toc indentation bug.
@end menu
@end ifnottex

@ifhtml
@contents
@end ifhtml


@node    Introduction
@chapter Introduction

@c If you edit the introduction, then re-generate daikon.html and insert
@c its ``Introduction'' section into $DAIKONDIR/doc/www/index.html .

@uref{http://plse.cs.washington.edu/daikon/, ,Daikon} is an implementation of
dynamic detection of likely invariants; that is, the Daikon invariant
detector reports likely program invariants.  An invariant is a property
that holds at a certain point or points in a program; these are often
seen in assert statements, documentation, and formal specifications.
Invariants can be useful in program understanding and a host of other
applications.  Examples include @samp{x.field > abs(y)}; @samp{y = 2*x+3};
@samp{array a is sorted}; @samp{for all list objects lst, lst.next.prev =
lst}; @samp{for all treenode objects n, n.left.value < n.right.value}; @samp{p
!= null => p.content in myArray}; and many more.  You can extend Daikon
to add new properties (@pxref{Enhancing Daikon output}, or
@pxref{New invariants,,,developer,Daikon Developer Manual}).

Dynamic invariant detection runs a program, observes the values that the
program computes, and then reports properties that were true over the
observed executions.
@c Daikon's output, which is sometimes called an ``operational abstraction'',
@c looks like a formal specification, or the contents of assert statements.
Daikon can detect properties in C, C++, C#, Eiffel, F#, Java, Perl, and
Visual Basic programs;
in spreadsheet files; and in other data sources.  (Dynamic invariant
detection is a machine learning technique that can be applied to
arbitrary data.)  It is easy to extend Daikon to other applications.

Daikon is freely available for download from
@uref{http://plse.cs.washington.edu/daikon/download/, ,download-site}.  The distribution
includes both source code and
@uref{http://plse.cs.washington.edu/daikon/download/doc/, ,documentation},
and Daikon's license permits unrestricted use (@pxref{License}).  Many
researchers and practitioners have used Daikon; those uses, and Daikon
itself, are described in various
@uref{http://plse.cs.washington.edu/daikon/pubs/, ,publications}.

For more information on Daikon,
@pxref{Top, , Introduction, developer, Daikon Developer Manual}.
For instance, the @cite{Daikon Developer Manual} indicates how to
extend Daikon with new invariants, new derived variables, and front
ends for new languages.  It also contains information about the
implementation and about debugging flags.

@menu
* Mailing lists::
@end menu

@node    Mailing lists
@section Mailing lists
@cindex mailing lists
@cindex daikon-announce mailing list
@cindex daikon-discuss mailing list
@cindex daikon-developers mailing list

The following mailing lists (and their archives) are available:
@table @samp
@item daikon-announce@@googlegroups.com
A low-volume, announcement-only list.  For example,
announcements of new releases are sent to this list.
To subscribe, visit
@uref{https://groups.google.com/forum/#!forum/daikon-announce}.
@item daikon-discuss@@googlegroups.com
A moderated list for the community of Daikon users.  Use it to share
tips and successes, and to get help with questions or problems (after
checking the documentation).  To subscribe, visit
@uref{https://groups.google.com/forum/#!forum/daikon-discuss}.
@item daikon-developers@@googlegroups.com
This list goes to the Daikon maintainers.  Use it for bug reports,
suggestions, and the like.  If you are an active contributor to Daikon,
you may send mail to the list asking to be added.
@end table

Do @emph{not} send the same message to multiple mailing lists.  Doing so is
antisocial:  it causes confusion and extra work.  If you do so, your
question will not be answered.


@node    Installing Daikon
@chapter Installing Daikon
@cindex installing Daikon

Shortcut for the impatient:  skip directly to the installation instructions
for @ref{Unix/Linux/MacOSX installation}, or @ref{Windows installation}.

The main way to install Daikon is from a release, as explained in this
section.
(Alternately,
@pxref{Version control repository,,,developer,Daikon Developer Manual},
to obtain the latest Daikon source code from its version control repository.)
Here is an overview of the steps.

@enumerate
@item
Download Daikon.

@item
Place three commands in your shell initialization file.

@item
Optionally, customize your installation.

@item
Compile Daikon and build other tools.

@end enumerate

Details appear below; select the
instructions for your operating system.


Differences from previous versions of Daikon appear
in the file @url{CHANGES,,@file{doc/CHANGES}} in the distribution.
To be notified of new releases, or to join discussions about Daikon,
subscribe to one of the mailing lists (@pxref{Mailing lists}).


@menu
* Requirements::
* Unix/Linux/MacOSX installation::
* Windows installation::
* Running Daikon under Windows::
@end menu


@node       Requirements
@section    Requirements for running Daikon

In order to run Daikon, you must have a Java 7 (or later) JDK, including a
@uref{http://www.oracle.com/technetwork/java/javase/overview/index.html,,
Java Virtual Machine} and a Java compiler.

If you wish to analyze C or C++ programs, you need a C or C++
compiler such as @command{gcc}.

If you wish to edit the Daikon source code and re-compile Daikon,
@pxref{Compiling Daikon,,,developer,Daikon Developer Manual}.


@c The explicit installation instructions, segregated by OS type, is
@c helpful to users.


@node       Unix/Linux/MacOSX installation
@section    Unix/Linux/MacOSX installation

@exampleindent 1
@enumerate
@item
Choose the directory where you want to install Daikon; we'll call this
the @var{daikonparent} directory.  In this directory, download and
unpack Daikon.

@example
cd @var{daikonparent}
wget http://plse.cs.washington.edu/daikon/download/daikon-5.6.7.tar.gz
tar zxf daikon-5.6.7.tar.gz
@end example

@noindent
This creates a @file{@var{daikonparent}/daikon-5.6.7/} subdirectory.

@item
Place three commands in your shell initialization file:
set two environment variables
and source a Daikon startup file.


We will assume that you are using the bash shell or one of its variants.
Add commands like these to your @file{~/.bashrc} or @file{~/.bash_profile} file:
@example
# The absolute pathname of the directory that contains Daikon
export DAIKONDIR=@var{daikonparent}/daikon-5.6.7
# The absolute pathname of the directory that contains the Java JDK
export JAVA_HOME=@var{/usr/lib/jvm/java}
source $DAIKONDIR/scripts/daikon.bashrc
@end example

A setting of @env{JAVA_HOME} that @emph{sometimes} works (it might not
because @command{java} might be the version in the JDK or in the JRE) is:

@exampleindent 0
@smallexample
export JAVA_HOME=$@{JAVA_HOME:-$(dirname $(dirname $(dirname $(readlink -f $(/usr/bin/which java)))))@}
@end smallexample
@exampleindent 1

After editing your shell initialization file, either execute the commands
you placed in it, or else log out and log back in to achieve the same
effect.

@item
Optionally, customize other variables.  The customizable variables are
listed in the Daikon startup file: @file{$DAIKONDIR/scripts/daikon.bashrc}.

You may customize them by setting environment variables, or by adding a
@file{Makefile.user} file to directory @file{$DAIKONDIR/java} (it is
automatically read at the beginning of the main Makefile, and prevents
you from having to edit the main Makefile directly).

@item
Compile Daikon and build other tools.
First, make sure that you have satisfied the requirements in
@ref{Requirements for compiling Daikon,,,developer,Daikon Developer Manual}
and
@ref{Requirements for compiling Kvasir,,,developer,Daikon Developer Manual}.
Then, run:

@c Note that this step is @emph{not} required if you only want to use Daikon
@c with its .NET front end (Celeriac).
@c This step is required for using
@c Daikon with its C/C++ front end (Kvasir), and for other tools such as DynComp.

@example
make -C $DAIKONDIR rebuild-everything
@end example

@noindent
This builds the various executables used by Daikon, such as the
C/C++ front end Kvasir (@pxref{Installing Kvasir}) and the
JDK for use with DynComp (@pxref{Instrumenting the JDK with DynComp}).
If you need more
information about compiling Daikon, see
@ref{Compiling Daikon,,,developer,Daikon Developer Manual}.
If you have trouble compiling the C/C++ front end Kvasir, see
@xref{Installing Kvasir}.

Note that running this make command may take 20 minutes or more,
depending on your computer.

Optionally, download other executables, such as
the Simplify theorem prover (@pxref{Installing Simplify}).

@end enumerate
@exampleindent 4

@node       Windows installation
@section    Windows installation

If you use Windows, an easy way to use Daikon is to run it under Windows
Subsystem for Linux (WSL).

The remainder of this section describes how to proceed if you prefer to use
Daikon under Windows.

To perform a complete install on
Windows, it is necessary to install the Cygwin toolset.
After you have installed Daikon, you can run it using either Cygwin or
the regular Windows shell (@pxref{Running Daikon under Windows}).

The Cygwin toolset (available at
@uref{http://cygwin.com/}) contains everything you need
to compile and run Linux programs under Windows.  You can install Cygwin
by running the appropriate setup program; either
@uref{http://cygwin.com/setup-x86.exe} or
@uref{http://cygwin.com/setup-x86_64.exe},
as determined by your machine type.
The default installation of Cygwin is sufficient for installing Daikon.


@exampleindent 1
@enumerate
@item
Choose the directory where you want to install Daikon; we'll call this
the @var{daikonparent} directory.  In this directory, download and
unpack Daikon. (Substitute the current version number for @file{#.#.#}.)

@example
cd @var{daikonparent}
wget http://plse.cs.washington.edu/daikon/download/daikon-5.6.7.tar.gz
tar zxf daikon-5.6.7.tar.gz
@end example

@noindent
This creates a @file{@var{daikonparent}/daikon-5.6.7/} subdirectory.

@item
Place three commands in your shell initialization file @file{~/.bashrc}:
set two environment variables
and source a Daikon startup file.
Do not use a Windows shell; use the Cygwin bash shell instead.

@example
# The full pathname of the directory that contains Daikon
export DAIKONDIR=@var{daikonparent}/daikon-5.6.7
# The full Linux pathname of the directory that contains the Java JDK
export JAVA_HOME=/cygdrive/c/Program Files/Java/jdk1.7.0_45
source $DAIKONDIR/scripts/daikon.bashrc
@end example

@noindent
Use the Cygwin/Linux path style (e.g., @code{/cygdrive/c/daikon}) rather than the
windows path style (@code{C:\daikon}).
Some users have reported problems when using pathnames
with spaces.  You can avoid the problem by using the @command{ln} command to add a
symbolic link without spaces to @code{Program Files}.

@example
cd /cygdrive/c
ln -s "Program Files" program_files
@end example

@noindent
and then the JAVA_HOME line becomes:
@example
export JAVA_HOME=/cygdrive/c/program_files/Java/jdk1.7.0_45
@end example

@c You can also
@c set the environment variables in the registry (right-click My Computer,
@c and then click Properties; click the Advanced tab; click Environment
@c variables), but that only reduces the number of steps you have to do for
@c each shell from 3 (two variables plus running the @file{daikonenv.bat}
@c file) to 1 (running the @file{daikonenv.bat} file).

After editing your shell initialization file, either execute the commands
you placed in it, or else log out and log back in to achieve the same
effect.

@item
Optionally, customize other variables.  The customizable variables are
listed in the Daikon startup file: @file{$DAIKONDIR/scripts/daikon.bashrc}.

You may customize them by setting environment variables, or by adding a
@file{Makefile.user} file to directory @file{$DAIKONDIR/java} (it is
automatically read at the beginning of the main Makefile, and prevents
you from having to edit the main Makefile directly).

The one variable you must customize is
to define the @env{OSTYPE} variable to be @samp{cygwin}.
@example
OSTYPE = cygwin
@end example

@item
Compile Daikon and build other tools.
@c Note that this step is @emph{not} required if you only want to use Daikon
@c with its .NET front end (Celeriac).
@c This step is required for using other tools such as DynComp.

@example
make -C $DAIKONDIR rebuild-everything
@end example

@noindent
This builds the various executables used by Daikon, such as the
JDK for use with DynComp (@pxref{Instrumenting the JDK with DynComp}).
If you need more
information about compiling Daikon, see
@ref{Compiling Daikon,,,developer,Daikon Developer Manual}.
If you have trouble compiling the C/C++ front end Kvasir, see
@xref{Installing Kvasir}.  Note that
Kvasir does not work under Cygwin.

Note that running this make command may take 20 minutes or more,
depending on your computer.
On Windows, running @command{make} requires
that @uref{http://www.cygwin.com/,Cygwin} be installed.

Optionally, download other executables, such as
the Simplify theorem prover (@pxref{Installing Simplify}).

@end enumerate
@exampleindent 4


@node       Running Daikon under Windows
@section    Running Daikon under Windows
@cindex Windows
@cindex Microsoft Windows

After you have installed Daikon under Windows (@pxref{Windows
installation}), you can run it either using native Windows utilities, or
using the Cygwin environment --- it's your choice.

Daikon is a @strong{command-line application} (and so are its related
programs, such as Chicory).  You should invoke them from a command shell
--- either a Windows command shell or a Cygwin command shell --- rather
than by double-clicking their icons.  In any event, double-clicking
would not supply the proper arguments to the program.

First, a little background/review.   Java on Linux separates its
@env{CLASSPATH} entries using the colon (@samp{:}) while Java on Windows
separates the entries with a semi-colon (@samp{;}). There is a good reason
for this; on Windows the colon would have been impractical as it is
used in file paths (@file{c:\}); on Linux the semi-colon is impractical,
as it is used to end a command line.  The tricky bit is that Cygwin
provides a Linux like environment on top of Windows.  So Cygwin mainly
wants colon separators but @command{java} is a Windows application, so it wants
semi-colons.  Another point is that when a Cygwin shell starts up,
it copies the Windows environment into its Linux like environment with
no changes --- except for the @env{PATH} variable.  This it converts
to Linux format (with colons) and adds "/usr/local/bin:/usr/bin:" to
the front.  Hence, it is all set to run both Cygwin and existing
Windows applications.


@menu
* Windows command line::
* Cygwin shell::
@end menu


@node          Windows command line
@subsection    Windows command line

The first option is to run Daikon using native Windows utilities.
The is done in the normal fashion.  However, getting the correct
value for @env{CLASSPATH} can be confusing.  As noted above, it
must be
specified in Windows format (Windows paths and semicolon separators).
It must include either @file{$DAIKONDIR/daikon.jar} or
@file{$DAIKONDIR/java} (if you
have recompiled the Daikon source).  A typical example for
@env{CLASSPATH} might be:

@exampleindent 1
@example
C:\cygwin64\home\user\invariants\daikon\daikon.jar;.;C:\Program Files
(x86)\QuickTime\QTSystem\QTJava.zip;C:\Program Files\Java\jdk1.7.0_45\
jre\lib\rt.jar;C:\Program Files\Java\jdk1.7.0_45\lib\tools.jar
@end example
@exampleindent 4

@noindent
With this done, one may enter: @command{java daikon.Daikon} in any
directory and Daikon should start up correctly.


@node          Cygwin shell
@subsection    Cygwin shell

@cindex Cygwin toolset

The second option for Windows (and the one we recommend) is to run
Daikon using the Cygwin toolset
(available at @uref{http://cygwin.com/}), which
contains everything you need to compile and run Linux programs under
Windows.  You can install Cygwin by simply running one of the setup
programs (based on your machine type) found
at @uref{http://cygwin.com/}.

As noted above, when running any Java program (such as Daikon or Chicory),
the @env{CLASSPATH} must be specified in Windows format.  Your initial
install of the Java JDK will have set the basics for the @env{CLASSPATH}.
When you installed Daikon, you were instructed to place into your
shell initialization file commands to set @env{JAVA_HOME}
and then @command{source $DAIKONDIR/scripts/daikon.bashrc}.  This will
set @env{CLASSPATH} properly each time you start a Bash shell.  The
result should be a value for @env{CLASSPATH} that looks something like:

@exampleindent 1
@example
C:\cygwin64\home\user\invariants\daikon\daikon.jar;.;C:\Program Files
(x86)\QuickTime\QTSystem\QTJava.zip;C:\Program Files\Java\jdk1.7.0_45\
jre\lib\rt.jar;C:\Program Files\Java\jdk1.7.0_45\lib\tools.jar
@end example
@exampleindent 4

If you wish to override @env{CLASSPATH} by using the @option{-classpath}
(or @option{-cp}) option, you need to remember that the result must be
in Windows format.  This can get confusing because the Cygwin
bash interpreter is going to process the command line prior to handing it
off to @command{java}.  Hence:
@exampleindent 1
@example
java -cp c:\cygwin64\home\user\invariants\daikon\daikon.jar daikon.Daikon
@end example
@exampleindent 4

@noindent
will fail as the backslash @samp{\} is processed by bash and removed.  Any of
the following will work:

@tex
\global\hfuzz=35pt
@end tex
@exampleindent 1
@example
java -cp c:\\cygwin64\\home\\user\\invariants\\daikon\\daikon.jar daikon.Daikon
java -cp "c:\cygwin64\home\user\invariants\daikon\daikon.jar" daikon.Daikon
java -cp c:/cygwin64/home/user/invariants/daikon/daikon.jar daikon.Daikon
@end example
@exampleindent 4
@tex
\global\hfuzz=1pt
@end tex

The last is interesting as this is almost the same as on ``real'' Linux.  Windows
accepts either forward (@samp{/}) or backward (@samp{\}) slashes as directory separators
in paths.  There are similar command parsing issues with parenthesis and blanks.
These are legal in Windows paths, but will cause bash to get confused.
In general, enclosing a valid Windows path within double quotes (@samp{"})
is the preferred way to avoid these problems.
If you find it more convenient to use Linux paths, or want to use an
existing environment variable that contains a Linux path, the @command{cygpath} tool
will do the job.  Thus, instead of:
@exampleindent 1
@example
java -cp $HOME/invariants/daikon/daikon.jar daikon.Daikon
@end example
@exampleindent 4

@noindent
(which will fail), use
@exampleindent 1
@example
java -cp `cygpath -wp $HOME/invariants/daikon/daikon.jar` daikon.Daikon
@end example
@exampleindent 4

@noindent
(note the back quotes @samp{`}) and everything should work as expected. Or even better:
@exampleindent 1
@example
java -cp "`cygpath -wp $HOME/invariants/daikon/daikon.jar`" daikon.Daikon
@end example
@exampleindent 4

@noindent
since there may be some Windows path characters contained in the environment variables.


@node    Example usage
@chapter Example usage for Java, C/C++, C#/F#/Visual Basic, Perl, and Eiffel

Detecting invariants involves two steps:
@enumerate
@item
Obtain one or more data trace files by running your program under the control of a
front end (also known as an instrumenter or tracer) that records information about
variable values.  You can run your program over one or more inputs of your own
choosing, such as regression tests or a typical user input session.
You may choose to obtain trace data for only part of
your program; this can avoid inundating you with
output, and can also improve performance.

@item
Run the Daikon invariant detector over the data trace files
(@pxref{Running Daikon}).  This detects invariants in the recorded
information.  You can view the invariants textually, or process them
with a variety of tools.
@end enumerate

This section briefly describes how to obtain data traces for Java, C,
C#, Perl, and Eiffel programs, and how to run Daikon.  For detailed
information about these and other front ends that are available for
Daikon, @pxref{Front ends (instrumentation)}.

@menu
* Detecting invariants in Java programs::
* Detecting invariants in C/C++ programs::
* Detecting invariants in C# programs::
* Detecting invariants in Perl programs::
* Detecting invariants in Eiffel programs::
* Detecting invariants in Simulink/Stateflow programs::
@end menu

@node    Detecting invariants in Java programs
@section Detecting invariants in Java programs

In order to detect invariants in a Java program, you will run the program
twice --- once using DynComp (@pxref{DynComp for Java}) to create a
@file{.decls} file and once using Chicory (@pxref{Chicory}) to create a
data trace file.
Then, run Daikon on the data trace file to detect invariants.
With the @option{--daikon} option to Chicory, a single command performs
the last two steps.

@exampleindent 1
For example, if you usually run
@example
java mypackage.MyClass arg1 arg2 arg3
@end example

@noindent
then instead you would run
@example
java daikon.DynComp mypackage.MyClass arg1 arg2 arg3
java daikon.Chicory --daikon \
                    --comparability-file=MyClass.decls-DynComp \
                    mypackage.MyClass arg1 arg2 arg3
@end example
@exampleindent 4

@noindent
and the Daikon output is written to the terminal.


@menu
* StackAr example::
* Detecting invariants when running a Java program from a jar file::
* Understanding the invariants::
* Second Java example::
@end menu

@c Commented out as of summer 2005, because David Cok doesn't seem likely
@c to pick this up again, and we don't want to lead users astray or
@c discourage them with non-functional software.
@c @node    Eclipse plug-in
@c @subsection Eclipse plug-in
@c @cindex Eclipse plug-in
@c @cindex GUI, Eclipse
@c
@c Daikon is integrated with the
@c @uref{http://eclipse.org/, ,
@c Eclipse} IDE (Integrated Development Environment) for Java.
@c The Daikon plug-in provides a convenient way to instrument files,
@c obtain trace information, analyze those traces,
@c and create appropriately annotated Java source code.
@c For
@c details, see the @uref{daikonHelp.html, , Daikon Eclipse plug-in
@c documentation}.
@c
@c As of this writing (February 11, 2005), the plug-in only works with
@c Daikon 3 (for instance, version 3.1.7), not with Daikon 4.  Support for
@c Daikon 4 is underway.
@c
@c For brief troubleshooting information, see @ref{Eclipse plug-in problems}.


@node       StackAr example
@subsection StackAr example

The Daikon distribution contains some sample programs that will help
you get practice in running Daikon.

To detect invariants in the @file{StackAr} sample program, perform the
following steps after installing Daikon (@pxref{Installing Daikon}).

@exampleindent 1
@enumerate
@item
Compile the program with the @option{-g} switch to enable debugging
symbols.  (The program and test suite appear in the
@file{DataStructures} subdirectory.)
@example
cd examples/java-examples/StackAr
javac -g DataStructures/*.java
@end example

@item
Run the program under the control of DynComp to generate comparability
information in the file @file{StackArTester.decls-DynComp}.

@example
java -cp .:$CLASSPATH daikon.DynComp DataStructures.StackArTester
@end example

@noindent
If you have not yet set the CLASSPATH, you may add it to the command
line for now --- but don't forget to set it later.

@exampleindent 0
@smallexample
java -cp "../../../daikon.jar:." daikon.DynComp DataStructures.StackArTester
@end smallexample
@exampleindent 1

@item
Run the program a second time, under the control of the Chicory front end.
Chicory observes the variable values and passes the information to Daikon.
Daikon infers invariants, prints them, and writes a binary representation
of them to file @file{StackArTester.inv.gz}.

@example
java -cp .:$CLASSPATH daikon.Chicory --daikon \
     --comparability-file=StackArTester.decls-DynComp \
     DataStructures.StackArTester
@end example


@noindent
Alternately, replacing the @option{--daikon} argument by
@option{--daikon-online} has the same effect, but does not write a data
trace file to disk.

@end enumerate

If you wish to have more control over the invariant detection process,
you can split the third step above into multiple steps.  Then, step 3
would become:

@enumerate 3
@item
Run the program under the control of the Chicory front end
in order to create a trace file named
@file{StackArTester.dtrace.gz}.

@example
java -cp .:$CLASSPATH daikon.Chicory \
     --comparability-file=StackArTester.decls-DynComp \
     DataStructures.StackArTester
@end example

@item
Run Daikon on the trace file.

@example
java daikon.Daikon StackArTester.dtrace.gz
@end example
(Note the classpath (@option{-cp}) argument is not needed as we are not
running the @command{StackArTester} program.)

Daikon can analyze multiple runs (executions) of the program.  You can
supply Daikon with multiple trace files:

@exampleindent 0
@smallexample
java daikon.Chicory --dtrace-file=StackArTester1.dtrace.gz \
     --comparability-file=StackArTester.decls-DynComp DataStructures.StackArTester
java daikon.Chicory --dtrace-file=StackArTester2.dtrace.gz \
     --comparability-file=StackArTester.decls-DynComp DataStructures.StackArTester
java daikon.Chicory --dtrace-file=StackArTester3.dtrace.gz \
     --comparability-file=StackArTester.decls-DynComp DataStructures.StackArTester
java daikon.Daikon StackArTester*.dtrace.gz
@end smallexample
@exampleindent 1

@c @noindent
@c or, you can append information from multiple runs in a single trace file
@c (but in this case you cannot use a compressed trace file):
@c
@c @example
@c java -DDTRACEAPPEND=1 daikon.Chicory --dtrace-file=StackArTester.dtrace DataStructures.StackArTester
@c java -DDTRACEAPPEND=1 daikon.Chicory --dtrace-file=StackArTester.dtrace DataStructures.StackArTester
@c java -DDTRACEAPPEND=1 daikon.Chicory --dtrace-file=StackArTester.dtrace DataStructures.StackArTester
@c java daikon.Daikon StackArTester.dtrace
@c @end example

@noindent
(In this example, all the runs are identical, so multiple runs yield the
same invariants as one run.)

@item
Examine the invariants.  (They were also printed to standard out
by the previous step.)

There are various ways to do this.
@itemize @bullet
@item
Examine the output from running Daikon.  (You may find it
convenient to capture the output in a file; add @samp{> StackAr.txt}
to the end of the command that runs Daikon.)

@item
Use the @command{PrintInvariants} program to display the invariants.

@example
java daikon.PrintInvariants StackArTester.inv.gz
@end example

For more options to the @command{PrintInvariants} program, see @ref{Printing
invariants}.

@item
Use the Annotate program to insert the invariants as comments
into the Java source program.

@example
cd ..
java daikon.tools.jtb.Annotate StackArTester.inv.gz \
     DataStructures/StackAr.java
@end example

(Here and elsewhere in the manual, the continuation character @samp{\} is
used to split a long command across lines.  Windows uses the @samp{^}
character instead.)

Now examine file @file{DataStructures/StackAr.java-escannotated}.
For more information about the Annotate program, see @ref{Annotate}.


@end itemize
@end enumerate
@exampleindent 4


@node Detecting invariants when running a Java program from a jar file
@subsection Detecting invariants when running a Java program from a jar file

If your Java program is run directly from a @file{jar} file,
such as either of:

@exampleindent 1
@example
java mypackage.jar arguments
java -cp <originalclasspath> mypackage.jar arguments
@end example

@noindent
then to detect invariants in that Java program,
run these commands:

@example
java -cp mypackage.jar:<original classpath> daikon.DynComp <MyMain> arguments
java -cp mypackage.jar:<original classpath> daikon.Chicory --daikon \
     --comparability-file=<MyMain>.decls-DynComp <MyMain> arguments
@end example

@noindent
where @command{<MyMain>} is the Main-class of the @file{jar} file, which you
can determine by running the command:

@example
unzip -p mypackage.jar META-INF/MANIFEST.MF | grep '^Main-Class:'
@end example
@exampleindent 4


@node       Understanding the invariants
@subsection Understanding the invariants

This section examines some of the invariants for the @file{StackAr} example.
For more help interpreting invariants, see @ref{Interpreting output}.

The @file{StackAr} example is an array-based stack implementation.  Take a
look at @file{DataStructures/StackAr.java} to get a sense of the
implementation.  Now, look at the sixth section of Daikon output.

@exampleindent 1
@example
======================================================================
StackAr:::OBJECT
this.theArray != null
this.theArray.getClass().getName() == java.lang.Object[].class
this.topOfStack >= -1
this.topOfStack <= size(this.theArray[])-1
======================================================================
@end example

These four annotations describe the representation invariant.  The
array is never null, and its runtime type is @code{Object[]}.  The
@code{topOfStack} index is at least -1 and is less than the length
of the array.

Next, look at the invariants for the @code{top()} method.
@code{top()} has two different exit points, at lines 74 and 75
in the original source.  There is a set of invariants for each exit
point, as well as a set of invariants that hold for all exit points.
Look at the invariants when @code{top()} returns at line 75.

@example
======================================================================
StackAr.top():::EXIT75
return == this.theArray[this.topOfStack]
return == this.theArray[orig(this.topOfStack)]
return == orig(this.theArray[post(this.topOfStack)])
return == orig(this.theArray[this.topOfStack])
this.topOfStack >= 0
return != null
======================================================================
@end example

The return value is never null, and is equal to the array element at
index @code{topOfStack}.  The top of the stack is at least 0.
@exampleindent 4

@node       Second Java example
@subsection A second Java example

A second example is located in the @file{examples/java-examples/QueueAr} subdirectory.
Run this sample using the following steps:

@itemize @bullet
@item Compile
@exampleindent 1
@example
cd examples/java-examples/QueueAr
javac -g DataStructures/*.java
@end example

@item Trace file generation and invariant detection
@example
java -cp .:$CLASSPATH daikon.DynComp DataStructures.QueueArTester
java -cp .:$CLASSPATH daikon.Chicory --daikon \
     --comparability-file=QueueArTester.decls-DynComp \
     DataStructures.QueueArTester
@end example

@end itemize

Alternately, you can split the very last command into two parts:

@itemize

@item Trace file generation
@example
java -cp .:$CLASSPATH daikon.Chicory \
     --comparability-file=QueueArTester.decls-DynComp \
     DataStructures.QueueArTester
@end example

@item Invariant detection
@example
java daikon.Daikon QueueArTester.dtrace.gz
@end example
@exampleindent 4

@end itemize


@page

@node    Detecting invariants in C/C++ programs
@section Detecting invariants in C/C++ programs

In order to detect invariants over C or C++ programs, you must first install
a C/C++ front end (instrumenter).  We recommend that you use Kvasir (@pxref{Kvasir}),
and this section gives examples using Kvasir.
By default, Kvasir also runs the DynComp tool
to improve Daikon's performance and Daikon's output by filtering out invariants
involving unrelated variables (see @ref{DynComp for C/C++}).

To use the C/C++ front end Kvasir with your program, first make sure that
your program has been compiled with DWARF-2 format debugging
information, such as by giving the @option{-gdwarf-2} flag to @command{gcc} when
compiling.  Some versions of @command{gcc} now output position independent
code by default.  Kvasir cannot properly process these binaries.
You must add the @option{-no-pie} option to disable this feature.
Then, run your program as usual, but prepend
@command{kvasir-dtrace} to the command line.

Kvasir will produce two output files:
a @file{.dtrace} file containing a trace of a particular execution,
and a @file{.decls} file that contains
information about what variables and functions exist in a program, along
with information grouping the variables into abstract types.
You will supply both of these files to Daikon.

For more information about Kvasir, including more detailed
documentation on its command-line options, see @ref{Kvasir}.


@menu
* C examples::
* Dealing with large examples::
@end menu

@node       C examples
@subsection C examples

The Daikon distribution comes with several example C programs
to enable users to become familiar with running Daikon on C programs.
These examples are located in the @file{examples/c-examples} directory.

@c There are two sets of examples, corresponding to the two supplied C
@c front ends.  Examples intended for use with the binary-based front end
@c Kvasir are in a subdirectory @file{c-examples}; examples for the
@c older source-based front end dfec are in a subdirectory
@c @file{dfec-examples}.  It should be possible to instrument the dfec
@c examples with Kvasir, though we will not give directions here.
@c Instrumenting the Kvasir examples with dfec is not recommended (and is
@c not likely to work).


To detect invariants for a program with Kvasir, you need to perform
two basic tasks:  run the program under Kvasir to create a trace
and declaration files (steps 1--3), and run
Daikon over these files to produce invariants (step 4).
The following instructions are for the wordplay example, which is a
program for finding anagrams.

@exampleindent 1
@enumerate
@item
Change to the directory containing the program.
@example
cd $DAIKONDIR/examples/c-examples/wordplay
@end example

@item
Compile the program with DWARF-2 debugging information enabled
(and all optimizations disabled).
@example
gcc -gdwarf-2 -no-pie wordplay.c -o wordplay
@end example

Kvasir can also be used for programs constructed by compiling a number
of @file{.c} files separately, and then linking them together; in such
a program, specify @option{-gdwarf-2} when compiling each source file
containing code you wish to see invariants about.

@item
Run the program just as you normally would, but prepend
@command{kvasir-dtrace} to the command line.

@example
kvasir-dtrace ./wordplay -f words.txt 'Daikon Dynamic Invariant Detector'
@end example

@noindent
Any options to the program can be specified as usual; here, for
instance, we give commands to look for anagrams of the phrase ``Daikon
Dynamic Invariant Detector'' using words from the file @file{words.txt}.

Executing under Kvasir, the program runs normally, but Kvasir
executes additional checks and collects trace information (for this
reason, the program will run more slowly than usual).  Kvasir creates a
directory named @file{daikon-output} under the current directory, and
creates the @file{wordplay.dtrace} file, which lists variable
values, and the @file{wordplay.decls} file that contains
information about what variables and functions exist in a program, along
with information grouping the variables into abstract types.

Kvasir will also print messages if it observes your program doing
something with undefined effects; these may indicate bugs in your
program, or they may be spurious.  (If they are bugs, they can also be
tracked down by using Valgrind (@uref{http://www.valgrind.org/})
with its regular memory checking
tool; if they do not appear with that tool, they are probably
spurious).

@item
Run Daikon on the trace and declaration files.
@smallexample
java daikon.Daikon \
     --config_option daikon.derive.Derivation.disable_derived_variables=true \
     daikon-output/wordplay.decls daikon-output/wordplay.dtrace
@end smallexample

The invariants are printed to standard output, and a binary representation
of the invariants is written to @file{wordplay.inv.gz}.  Note that the
example uses a configuration option to disable the use of derived
variables; it can also run without that option, but takes significantly
longer.

Daikon can analyze multiple runs (executions) of the program.  You can
supply Daikon with multiple trace files:

@smallexample
kvasir-dtrace --dtrace-file=daikon-output/wordplay1.dtrace \
    ./wordplay -f words.txt 'daikon dynamic invariant detector'
kvasir-dtrace --no-dyncomp --dtrace-file=daikon-output/wordplay2.dtrace \
    ./wordplay -f words.txt 'better results from multiple runs'
kvasir-dtrace --no-dyncomp --dtrace-file=daikon-output/wordplay3.dtrace \
    ./wordplay -f words.txt 'more testing equals better testing'
java -Xmx256m daikon.Daikon daikon-output/wordplay*.dtrace daikon-output/wordplay.decls
@end smallexample

@noindent
Note that this example makes the assumption that the DynComp @file{.decls} information
for @command{wordplay} does not vary from run to run.
Thus it specifies @option{--no-dyncomp} on subsequent runs to improve performance.
(This assumption may not be true for other programs.)

Alternatively, you can append information from multiple runs in a single trace file:

@smallexample
kvasir-dtrace --dtrace-file=daikon-output/wordplay-all.dtrace \
    ./wordplay -f words.txt 'daikon dynamic invariant detector'
kvasir-dtrace --no-dyncomp --dtrace-append \
    --dtrace-file=daikon-output/wordplay-all.dtrace \
    ./wordplay -f words.txt 'better results from multiple runs'
kvasir-dtrace --no-dyncomp --dtrace-append \
    --dtrace-file=daikon-output/wordplay-all.dtrace \
    ./wordplay -f words.txt 'more testing equals better testing'
java -Xmx256m daikon.Daikon daikon-output/wordplay-all.dtrace daikon-output/wordplay.decls
@end smallexample

@item
Examine the invariants.  As described in @ref{StackAr example},
there are several ways to do this:
@itemize
@item
Examine the output from running Daikon.
@item
Use the @command{PrintInvariants} program to display the invariants.
@end itemize

@noindent
For help understanding the invariants, see @ref{Interpreting output}.

@end enumerate
@exampleindent 4

There is a second example C program in the @file{bzip2} directory.
It may be run in a similar fashion as the @file{wordplay} example,
but it is a more complex program and the @command{kvasir-dtrace}
step may take several minutes.

@c For instance, one effect of DynComp that can be seen in the wordplay
@c example concerns the global variables @code{largestlet},
@c @code{rec_anag_count}, @code{adjacentdups}, @code{specfirstword},
@c @code{maxdepthspec}, and @code{silent}.
@c These variables are all 0 in the sample execution (for instance, several
@c of them correspond to command-line options that are not enabled), so
@c without DynComp, Daikon gives the invariants that they are all equal.
@c However, DynComp's analysis finds that the variables are of different
@c abstract types, so it is not meaningful to compare them.
@c When DynComp information is provided, Daikon instead gives separate
@c invariants about the value of each variable.


@node       Dealing with large examples
@subsection Dealing with large examples

Since the default memory size used by a Java virtual machine varies, we
suggest that Daikon be run with at least 256 megabytes of
memory (and perhaps much more), specified for many JVMs by the option @option{-Xmx256m}.
For more information about specifying the memory usage for Daikon, see
@ref{Out of memory}.

Disk usage can be reduced by specifying that the front end should
compress its output @file{.dtrace} files.
@c ; see @ref{dfec runtime customization}.

In some cases, the time and space requirements of the examples can be
reduced by reducing the length of the program run.
However, Daikon's running time
depends on both the length of the test run and the size of the program
data (such as its use of global variables and nested data
structures).
The examples also demonstrate disabling derived variables, which
significantly improves Daikon's performance at the cost of producing
fewer invariants.
For more techniques for using Daikon with large programs
and long program runs, see @ref{Large dtrace files}.


@page

@node    Detecting invariants in C# programs
@section Detecting invariants in C#, F#, and Visual Basic programs

The Daikon front end for .NET languages (C#, F#, and Visual Basic) is
called Celeriac.

Please see its documentation at
@ifnothtml
: @* @ @ @ @ @ @
@end ifnothtml
@url{https://github.com/codespecs/@/daikon-dot-net-front-end}.


@node    Detecting invariants in Perl programs
@section Detecting invariants in Perl programs

The Daikon front end for Perl is called @command{dfepl}.

Using the Perl front end is a two-pass
process: first you must run the annotated program so that the runtime
system can dynamically infer the kind of data stored in each variable,
and then you must re-annotate and re-run the program with the added
type information.
This is necessary because Perl programs do not contain type declarations.

@command{dfepl} requires version 5.8 or later of Perl.

@menu
* Instrumenting Perl programs::
* Perl examples::
@end menu


@node       Instrumenting Perl programs
@subsection Instrumenting Perl programs

Perl programs must be instrumented twice.  First they must be
instrumented without type information.  Then, once the first
instrumented version has been run to produce type information, they
must be instrumented again taking the type information into account.

To instrument a stand-alone Perl program, invoke @command{dfepl} with
the name of the program as an argument.

@exampleindent 1
@example
dfepl program.pl
@end example

To instrument a Perl module or a collection of modules, invoke
@command{dfepl} either with the name of each module, or with the name
of a directory containing the modules.  To instrument all the modules
in the current directory, give @command{dfepl} the argument @file{.}.
For instance, if the current directory contains a module
@code{Acme::Trampoline} in @file{Acme/Trampoline.pm} and another
module @code{Acme::Date} in @file{Acme/Date.pm}, they can be annotated
by either of the following two commands:

@example
dfepl Acme/Trampoline.pm Acme/Date.pm
dfepl .
@end example

Once type information is available, run the instrumentation command
again with the @option{-T} or @option{-t} options added to use the
produced type information.

For more information about @command{dfepl}, see @ref{dfepl}.


@node       Perl examples
@subsection Perl examples

The Daikon distribution includes sample Perl programs suitable for use
with Daikon in the @file{examples/perl-examples} directory.

Here are step-by-step instructions for examining a simple module,
@file{Birthday.pm}, as used by a test script @file{test-bday.pl}.

@exampleindent 1
@enumerate
@item Change to the directory containing the @file{Birthday.pm}
module.
@example
cd examples/perl-examples
@end example

@item Instrument the @file{Birthday.pm} file.
@example
dfepl Birthday.pm
@end example

@noindent
This command creates a directory @file{daikon-untyped}, and puts
the instrumented version of @file{Birthday.pm} into
@file{daikon-untyped/Birthday.pm}.  As the directory name implies, this
instrumented version doesn't contain type information.

@item Run a test suite using the instrumented @file{Birthday.pm}
file.
@example
dtype-perl test_bday.pl 10
@end example

@noindent
The @file{dtype-perl} is a script that runs Perl with the appropriate
command line options to find the modules used by the Daikon Perl
runtime tracing modules, and to use the instrumented versions of
modules in @file{daikon-untyped} in preference to their original
ones.  The number 10 is an argument to the @file{test_bday.pl} script
telling it to run a relatively short test.

This will also generate a file
@file{daikon-instrumented/Birthday.types} recording the type of each
variable seen during the execution of the instrumented program.

@item Re-annotate the module using the type information.
@example
dfepl -T Birthday.pm
@end example

@noindent
This step repeats step 2, except that the @option{-T} flag to
@command{dfepl} tells it to use the type information generated in the
previous step, and to put the output in the directory
@file{daikon-instrumented}.  @command{dfepl} also converts the
type information into a file @file{daikon-output/Birthday.decls}
containing subroutine declarations suitable for Daikon.

@item Run the full test suite with the type-instrumented
@file{Birthday.pm}.
@example
dtrace-perl test_bday.pl 30
@end example

@noindent
Here we run another test suite, which happens to be the same
@file{test_bday.pl}, but running for longer. (The example will also
work with a smaller number).  The script @command{dtrace-perl} is
similar to @command{dtype-perl} mentioned earlier, but looks for
instrumented source files in @file{daikon-instrumented}.

This creates @file{daikon-output/test_bday-combined.dtrace}, a trace
file containing the values of variables at each invocation. (The
file name is formed from the name of the test program, with
@file{-combined} appended because it contains the trace information
from all the instrumented modules invoked from the program).

@item Change to the @file{daikon-output} directory to analyze the
output.
@example
cd daikon-output
@end example

@item Run Daikon on the trace file
@example
java daikon.Daikon Birthday.decls test_bday-combined.dtrace
@end example

@item
Examine the invariants.  They are printed to standard output, and
they are also saved to file @file{Birthday.inv.gz}, which you can
manipulate with the @command{PrintInvariants} program and other Daikon tools.
For example:
@example
java daikon.PrintInvariants Birthday.inv.gz
@end example

Invariants produced from Perl programs can be examined using the same
tools as other Daikon invariants.
@end enumerate
@exampleindent 4

In the example above, the script @file{test_bday.pl} was not itself
instrumented; it was only used to test the instrumented code.  The
Perl front end can also be used to instrument stand-alone Perl
programs.  The following sequence of commands, similar to those above,
show how Daikon can be used with the stand-alone program
@file{standalone.pl}, also in the @file{examples/perl-examples}
directory.

@exampleindent 1
@example
dfepl standalone.pl
dtype-perl daikon-untyped/standalone.pl
dfepl -T standalone.pl
dtrace-perl daikon-instrumented/standalone.pl
cd daikon-output
java daikon.Daikon -o standalone.inv standalone-main.decls \
     standalone-combined.dtrace
@end example
@exampleindent 4

@noindent
Note two differences when running a stand-alone program.  First, the
instrumented versions of the program, in the @file{daikon-untyped} or
@file{daikon-instrumented} directory, are run directly.  Second, the
declarations file is named after the package in which the subroutines
were declared, but since every stand-alone program uses the
@code{main} package, the name of the program is prepended to the
@file{.decls} file name to avoid collisions.


@node    Detecting invariants in Eiffel programs
@section Detecting invariants in Eiffel programs

CITADEL is an Eiffel front-end to the Daikon invariant detector.
You can obtain Citadel from
@uref{http://se.inf.ethz.ch/people/polikarpova/citadel/}.


@node    Detecting invariants in Simulink/Stateflow programs
@section Detecting invariants in Simulink/Stateflow programs

@nospellcheck{Hynger (HYbrid iNvariant GEneratoR) instruments Simulink/Stateflow (SLSF)}
block diagrams to generate Daikon input (@file{.dtrace} files).  Hynger was created
by @nospellcheck{Taylor Johnson, Stanley Bak, and Steven Drager.}  You can obtain Hynger
from @uref{https://bitbucket.org/verivital/hynger}.


@node    Running Daikon
@chapter Running Daikon

This section describes how to run Daikon on a data trace
(@file{.dtrace}) file, and describes Daikon's command-line options.
This section assumes you have already run a front end (e.g., an
instrumenter) to produce a @file{.dtrace} file (and optionally
@file{.decls} and @file{.spinfo} files); to learn more about that
process, @pxref{Example usage}, and @pxref{Front ends (instrumentation)}.

Run the Daikon invariant detector via the command
@example
java daikon.Daikon @i{[@var{flags}]} @var{dtrace-files...} \
     @i{[@var{decls-files...}]} @i{[@var{spinfo-files...}]}
@end example

@itemize
@item
The @var{dtrace-files} are data trace (@file{.dtrace}) files containing
variable values from an execution of the target program.

@item
The @var{decls-files} are declaration (@file{.decls}) files containing
program point declarations.  Be sure to include all declaration files
that are needed for the particular data trace file; the simplest way
is to include every declaration file created when instrumenting the
program.

Not all Daikon front ends produce @file{.decls} files, since program point
declarations may also appear in @file{.dtrace} files.  For instance, the
Chicory front end for Java (@pxref{Chicory}) produces only @file{.dtrace}
files.  If there are no @file{.decls} files, then it is not necessary to
include them on the command line to Daikon.

Note that combining input files from Chicory and (Java) DynComp can lead to
a @nospellcheck{decl} format error. The preferred usage is to use the DynComp generated
@file{.decls} file(s) as input to Chicory.
See @ref{Detecting invariants in Java programs} for more details.

@item
The @var{spinfo-files} are splitter info (@file{.spinfo}) files that
enable detection of conditional invariants (@pxref{Conditional
invariants}); these are optional and may be created automatically or by hand.

@end itemize

@noindent
The files may appear in any order;
the file type is determined by whether the file name contains
@file{.decls}, @file{.dtrace}, or @file{.spinfo}.
As a special case, a file name of @file{-} means to read data trace
information from standard input.


@cindex command line options for Daikon
@cindex flags for Daikon
The optional flags are described in the sections that follow.  For
further ways to control Daikon's behavior via configuration options, see
@ref{Configuration options}; also see the list of options to the front
ends --- such as DynComp (@pxref{DynComp for Java options}),
Chicory (@pxref{Chicory options}) or Kvasir (@pxref{Kvasir options}).


@menu
* Options to control Daikon output::
* Options to control invariant detection::
* Processing only part of the trace file::
* Daikon configuration options::
* Daikon debugging options::
@end menu


@node    Options to control Daikon output
@section Options to control Daikon output

@c Unfortunately, @option{} adds quotes in the Info and printed output
@c which is not necessary in a table.  However, @t and @code compress
@c the two hyphens to one in Info and HTML output, which is even worse.
@table @option
@item --help
Print usage message.

@item -o @var{inv_file}
Output serialized invariants to the specified file; they can later be
postprocessed, compared, etc.  Default: @file{@var{basename}.inv.gz} in
the current directory, where the first data trace file's basename starts
with @file{@var{basename}.dtrace}.  Default is no serialized output, if
no such data trace file was supplied.  If a data trace file was
supplied, there is currently no way to avoid creating a serialized
invariant file.

@item --no_text_output
Don't print invariants as text output.  This option may be used in
conjunction with the @option{-o} option.

@item --format @var{name}
Produce output in the given format.  For a list of the output formats
supported by Daikon, see @ref{Invariant syntax}.

@item --show_progress
@itemx --no_show_progress
Prints (respectively, suppresses) timing information as major portions of Daikon are executed.

@item --noversion
Suppress the printing of version information

@item --output_num_samples
@cindex samples breakdown output
@cindex mux output
Output numbers of values and samples for invariants and program points;
this is a debugging flag.  (That is, it helps you understand why Daikon
produced the output that it did.)

The @samp{Samples breakdown} output indicates how many samples in the
@file{.dtrace} file had a modified value (@samp{m}), had an unmodified
value (@samp{u}), and had a nonsensical value (@samp{x}).  The summary uses a
capital letter if the sample had any of the corresponding type of
variable, and a lower-case letter if it had none.  These types affect
statistical tests that determine whether a particular invariant (that
was true over all the test runs) is printed.

Only variables that appear in both the @nospellcheck{pre-state} and the post-state
(variables that are in scope at both procedure exit and entry) are
eligible to be listed as modified or unmodified.  This is why the list
of all variables is not the union of the modified and unmodified
variables.

@item --files_from @var{filename}
Read a list of @file{.decls}, @file{.dtrace}, or @file{.spinfo} file names from the
given text file, one filename per line, as an alternative to providing
the file names on the command line.


@item --server @var{dirname}
Server mode for Daikon in which it reads files from @var{dirname} as they
appear (sorted lexicographically) until it finds a file ending in @samp{.end},
at which point it calculates and outputs the invariants.



@item --omit_from_output [0rs]
Omit some potentially redundant information from the serialized output
file produced with @option{-o}.
By default, the serialized output contains all of the data structures
produced by Daikon while inferring invariants.
Depending on the use to which the serialized output will later be put,
the file can sometimes be significantly shortened by omitting
information that is no longer needed.
The flag should be followed by one or more characters each representing
a kind of structures the can be omitted.
The following characters are recognized:

@table @option
@item 0 (zero)
Omit information about program points that were declared, but for which
no samples were found in any @file{.dtrace} file.

@item r
Omit @dfn{reflexive} invariants, those in which a variable appears more
than once.
Usually, such invariants are not interesting, because their meaning is
duplicated by invariants with fewer variables: for instance, @code{x =
x - x} and @code{y = z + z} can be expressed as @code{x = 0} and
@code{y = 2 * z} instead.
However, Daikon generates and uses such invariants internally to
decide what invariants to create when two previously equal variables
turn out to be different.

@item s
Omit invariants that are suppressed by other invariants.
@dfn{Suppression} refers to a particular optimization
in which the processing of an invariant is
postponed as long as certain other invariants that logically imply it
hold.
@end table

For most uses of serialized output in the current version, it is safe
to use the @option{0} and @option{r} omissions, but the @option{s} omission
will cause subtle output changes.
In many cases, the amount of space saved is modest (typically around
10%), but the savings can be more substantial for programs with many
unused program points, or program points with many variables.

@end table

@node    Options to control invariant detection
@section Options to control invariant detection

@table @option
@cindex confidence limit
@item --conf_limit @var{val}
Set the confidence limit for justifying invariants.
If the confidence level for a given invariant is larger than the limit, then
Daikon outputs the invariant.  This mechanism filters out
invariants that are satisfied purely by chance.
This is only relevant to invariants that were true in all observed
samples; Daikon never outputs invariants that were ever false.

@var{val} must be between 0 and 1; the default is .99.  Larger values
yield stronger filtering.

Each type of invariant has its own rules for determining confidence.
See the @code{computeConfidence} method in the Java source code for the
invariant.

For example, consider the invariant @var{a}<@var{b} whose confidence computation
is @code{1 - 1/2^@var{numsamples}}, which indicates the likelihood that the
observations of @var{a} and @var{b} did not occur by chance.  If there were 3
samples, and @var{a}<@var{b} on all of them, then the confidence would be 7/8 =
.875.  If there were 6 samples, and @var{a}<@var{b} on only 5 on them, the
confidence would be 0.  If there were 9 samples, and @var{a}<@var{b} on all of
them, then the confidence would be 1-1/2^9 = .998.

@exampleindent 1
There are two ways to print the confidence of each invariant.  You can
use Diff (@pxref{Invariant Diff}):
@example
java daikon.diff.Diff MyFile.inv.gz
@end example

@noindent
or you can use @command{PrintInvariants}
(@pxref{Printing invariants}):
@example
java daikon.PrintInvariants --dbg daikon.PrintInvariants.repr \
     MyFile.inv.gz
@end example
@exampleindent 4

To print the confidence of each invariant that is discarded, run Daikon
with the @option{--disc_reason all} command-line option (@pxref{Daikon
debugging options}).

@item --list_type @var{classname}
Indicate that the given class implements the @code{java.util.List}
interface.  The preferred mechanism for indicating such information is
the @code{ListImplementors} section of the @file{.decls} file.
See @ref{ListImplementors declaration,,,developer,Daikon Developer Manual}.

@item --user-defined-invariant @var{classname}
Use a user-defined invariant that not built into Daikon but
is defined in the given class.
The @var{classname} should be in the fully-qualified format expected by
@uref{https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#getName--,,@code{Class.getName()}},
such as ``@code{mypackage.subpackage.ClassName}'',
and its @file{.class} file should appear on the classpath.

@item --disable-all-invariants
Disable all known invariants:  all those that are built into Daikon, and
all those that have been specified by @option{--user-defined-invariant} so
far.  An invariant may be re-enabled after this option is specified,
see @ref{Options to enable/disable specific invariants}.

@item --nohierarchy
@cindex hierarchy, disabling
@cindex unmatched entries, not ignoring
Avoid connecting program points in a dataflow hierarchy.  For example,
Daikon normally connects the @code{:::ENTER} program points of class methods
with the class's @code{:::CLASS} program point, so that any invariant
that holds on the @code{:::CLASS} program point is considered to hold
true on the @code{:::ENTER}
program point.  With no hierarchy, each program point is treated
independently.  This is for using Daikon on applications that do not
have a concept of hierarchy.  It can also be useful when you wish to
process unmatched enter point samples from a trace file that is missing
some exit point samples.

@item --suppress_redundant
Suppress display of logically redundant invariants, using the Simplify
automatic theorem prover.  Daikon already suppresses most logically
redundant output (this can be controlled by invariant filters;
@pxref{Invariant filters}.
For example, if @samp{x >= 0} and @samp{x > 0} are both
true, then Daikon outputs only @samp{x > 0}.  Use of the
@option{--suppress_redundant} option tells Daikon to use Simplify to
eliminate even more redundant output, and should be used if it is
important that absolutely no redundancies appear in the output.

The Simplify program must be installed in order to take
advantage of this option (@pxref{Installing Simplify}).
Beware that Simplify can run slowly;
the amount of effort Simplify exerts for each invariant can be controlled
using both the @option{daikon.simplify.Session.simplify_max_iterations} and
@option{daikon.simplify.Session.simplify_timeout} configuration
options.

@end table


@node    Processing only part of the trace file
@section Processing only part of the trace file

@table @option
@item --ppt-select-pattern=@var{ppt_regexp}
Only process program points whose names match the regular expression.
The @option{--ppt-omit-pattern} argument takes precedence over this argument.

@item --ppt-omit-pattern=@var{ppt_regexp}
Do not process program points whose names match the regular expression.
This takes precedence over the @option{--ppt-select-pattern} argument.

@item --var-select-pattern=@var{var_regexp}
Only process variables (whether in the trace file or derived) whose
names match the regular expression.
The @option{--var-omit-pattern} argument takes precedence over this argument.

@item --var-omit-pattern=@var{var_regexp}
Ignore variables (whether in the trace file or derived) whose names
match the regular expression.
This takes priority over the @option{--var-select-pattern} argument.

@end table

All of the regular expressions used by Daikon use
@uref{https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html#sum,,Java's regular expression syntax}.
Multiple items can be matched by using the logical or operator (@samp{|}),
for example @code{var1|var2|var3}.
Java's regular expression syntax is similar to Perl's but
@uref{https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html#jcc,,not
exactly the same}.

The @var{...-omit-pattern} arguments take precedence:  if a name matches
an omit pattern, it is excluded.  If a name does not match an omit
pattern, it is tested against the select pattern (if any).  If any
select patterns are specified, the name must match one of the patterns
in order to be included.  If no select patterns are specified, then any
@samp{ppt} name that does not match the omit patterns is included.

Using @option{--ppt-select-pattern} and @option{--ppt-omit-pattern} can
save time even if there are no samples for the excluded program points,
as Daikon can skip the declarations and need not initialize data
structures that would be used if samples were encountered.

Front ends such as Chicory (@pxref{Program points in Chicory output})
and Kvasir (@pxref{Kvasir options}), and other tools such as DynComp
(@pxref{DynComp for Java options}) and @command{PrintInvariants} (@pxref{Printing
invariants}), also support these command-line options (Kvasir names them
slightly differently).  Passing the command-line option to the front end
means that the target program will run faster and the trace file will be
smaller.


@node    Daikon configuration options
@section Daikon configuration options

@table @option
@item --config @var{filename}
Load the configuration settings specified in the given file.
@xref{Configuration options}, for details.

@item --config_option @var{name}=@var{value}
Specify a single configuration setting.
@xref{Configuration options}, for details.

@end table

@node    Daikon debugging options
@section Daikon debugging options

@table @option
@item --dbg @var{category}
@itemx --debug
@cindex debugging flags
@cindex category, for debugging
@cindex logging, for debugging Daikon
@cindex Logger
These debugging options cause output to be written to a log file (by
default, to the terminal); in other words, they enable a Logger.
The @option{--dbg @var{category}} option
enables debugging output (logging output) for a specific part of Daikon; it may be
specified multiple times, permitting fine-grained control over debugging
output.  The @option{--debug} option turns on all debugging flags.
(This produces a lot of output!)  Most categories are class or
package names in the Daikon implementation, such as @code{daikon.split}
or @code{daikon.derive.binary.SequencesJoin}.  Only classes that check
the appropriate categories are affected by the debug flags; you can
determine this by looking for a call to @code{Logger.getLogger} in
the specific class.

@item --track @var{class}<@var{var1},@var{var2},@var{var3}>@@@var{ppt}
@cindex debugging flags
@cindex category, for debugging
@cindex logging, for debugging Daikon
@cindex Logger
Turns on debugging information on the specified class, variables, and
program point.  In contrast to the @option{--dbg} option, track logging follows
a particular invariant through Daikon.  Multiple @option{--track} options
can be specified.  Each item (class, variables, and program point) is optional.
Multiple classes can be specified separated by vertical bars (@samp{|}).
Matching
is a simple substring (not a regular expression) comparison.  Each item
must match in order for a printout to occur.  For more information, see
@ref{Track logging,,,developer,Daikon Developer Manual}.

@item --disc_reason @var{inv_class}<@var{var1},@var{var2},...>@@@var{ppt}
Prints all discarded invariants of class @var{inv_class} at the program point
specified that involve exactly the variables given, as well as a short reason
and discard code explaining why they were not worthy of print.  Any of
the three parts of the argument may be made a wildcard by excluding it.
For example, @samp{@var{inv_class}} and
@samp{<@var{var1},@var{var2},...>@@@var{ppt}} are valid arguments.
Some concrete examples are
@samp{Implication<x,y>@@foo():::EXIT},
@samp{<x,y>@@foo():::EXIT},
and @samp{Implication<x,y>}.
To print all discarded invariants, use the argument @samp{all}.

@item --mem_stat
Prints memory usage statistics into a file named @file{stat.out} in the
current directory.

@end table



@node    Daikon output
@chapter Daikon output

Daikon outputs the invariants that it discovers in textual form to your
terminal.  This chapter describes how to interpret those invariants ---
in other words, what do they mean?

Daikon also creates a @file{.inv} file that contains the invariants in
serialized (binary) form.  You can use the @file{.inv} file to print the
invariants (@pxref{Printing invariants}) in a variety of formats, to
insert the invariants in your source code (@pxref{Annotate}), to perform
run-time checking of the invariants (see @ref{Runtime-check instrumenter},
and @ref{InvariantChecker}), and to do various other operations.  See
@ref{Tools}, for descriptions of such tools.

If you wish to write your own tools for processing invariants, you have
two general options.  You can parse Daikon's textual output, or you can
write Java code that processes the @file{.inv} file.  The @file{.inv}
file is simply a serialized
@uref{http://plse.cs.washington.edu/daikon/download/api/daikon/PptMap.html,@code{PptMap}}
object.  In addition to reading the Javadoc, you can examine how the
other tools use this data structure.


@menu
* Invariant syntax::
* Program points::
* Variable names::
* Interpreting output::
* Invariant list::
* Invariant filters::
@end menu

@node    Invariant syntax
@section Invariant syntax

Daikon can produce output in a variety of formats.  Each of the format
names can be specified as an argument to the @option{--format} argument
of Daikon (@pxref{Options to control Daikon output}), @command{PrintInvariants}
(@pxref{Printing invariants}), and Annotate (@pxref{Annotate}).
When passed on the command line, the format names are case-insensitive:
@option{--format JML} and @option{--format jml} have the same effect.

You can enhance Daikon to produce output in other formats.  See
@ref{New formatting for invariants,,,developer,Daikon Developer Manual}.

@cindex invariant output format
@cindex output format, for invariants

@table @asis

@cindex Daikon output format
@cindex output format, Daikon
@item Daikon format

Daikon's default format is a mix of Java, mathematical logic, and some
additional extensions.  It is intended to concisely convey meaning to
programmers.

@cindex DBC output format
@cindex output format, DBC
@cindex Jtest DBC output format
@cindex output format, Jtest DBC
@item DBC format
This format produces output in the design-by-contract (@dfn{DBC}) format
expected by @nospellcheck{Parasoft's} @command{Jtest} tool (@uref{https://www.parasoft.com}).

@c This implementation detail is not relevant to users
@c Like the Java output format, this output format makes extensive use of
@c helper methods defined in class @code{daikon.Quant}.

@cindex ESC/Java output format
@cindex output format, ESC/Java
@item ESC/Java format
@itemx ESC format
The Extended Static Checker for Java (@command{ESC/Java}) is a programming tool
for finding errors in Java programs by checking annotations that are
inserted in source code; for more details, see
@uref{http://www.hpl.hp.com/downloads/crl/jtk/}.  Daikon's @option{ESC/Java} format
(which can also be specified as @option{ESC} format) is intended for use with the
original @command{ESC/Java} tool.  Use Daikon's @option{JML} format for use with the
@uref{http://kindsoftware.com/products/opensource/ESCJava2/, ,ESC/Java2}
tool.

@cindex Java output format
@cindex output format, Java
@item Java format
Write output as Java expressions.  This means that each invariant
is a valid Java expression, if inserted at the correct program
point: right after method entry, for method entry invariants;
right before method exit, for method exit invariants; or anywhere in
the code, for object invariants.

There are two exceptions.  Method exit invariants that refer to
@samp{pre-state}, such as @samp{x == old(x) + 1}, are output with the tag
@samp{\old} surrounding the @samp{pre-state} expression (e.g. @samp{x ==
\old(x) + 1}.  Method exit invariants that refer to the return value of
the method, such as @samp{return == x + y}, are output with the tag
@samp{\result} in place of the return value (e.g. @samp{\result == x + y}).
These expression are obviously not valid Java code.

@c This implementation detail not relevant to users
@c The Java output format makes extensive use of helper methods defined
@c in class @code{daikon.Quant}, which provides methods for
@c quantification and set comprehension over Java collections.  For
@c example, @code{daikon.Quant.eltsEqual(int[] seq1, int elt)} checks
@c whether all elements in @code{seq1} are equal to @code{elt}.  For
@c detailed meanings of all methods in the @code{Quant} class, see the
@c Javadoc documentation for the class (or look inside
@c @file{daikon/QuantBody.java}).

@cindex JML output format
@cindex output format, JML
@item JML format
Produces output in JVM (Java Modeling Language,
@uref{http://www.jmlspecs.org}); for details, see the
@uref{http://www.eecs.ucf.edu/~leavens/JML/documentation.shtml, ,JML Manual}.  @option{JML}
format lets you use the various JVM tools on Daikon invariants,
including runtime assertion checking and the
@uref{http://kindsoftware.com/products/opensource/ESCJava2/, ,ESC/Java2}
tool.

@c This implementation detail not relevant to users
@c Like the Java output format, this output format makes extensive use of
@c helper methods defined in class @code{daikon.Quant}.

@cindex Simplify output format
@cindex output format, Simplify
@item Simplify format
Produces output in the format expected by the Simplify automated theorem
prover; for details, see the
@c was: @uref{http://research.compaq.com/SRC/esc/simplify/InputSyntax.html}
@uref{http://www.hpl.hp.com/downloads/crl/jtk/,,Simplify distribution}.

@cindex CSharpContract output format
@cindex output format, CSharpContract
@item CSharpContract format
Produces C# output for use with Microsoft's Code Contracts
@uref{http://www.microsoft.com/en-us/research/project/code-contracts/,,}.
The format employs some extension/utility methods to improve contract
readability; the library containing these methods can be found at
@uref{https://github.com/twschiller/daikon-code-contract-extensions,,}.

@end table


@node    Program points
@section Program points
@cindex program point

A program point is a specific place in the source code, such as
immediately before a particular line of code.  Daikon's output is
organized by program points.

@cindex :::ENTER program point
@cindex ENTER program point
@cindex precondition

For example, @code{foo():::ENTER} is the point at the entry to procedure
@code{foo()}; the invariants at that point are the preconditions for the
@code{foo()} method, properties that are always true when the procedure
is invoked.

@cindex :::EXIT program point
@cindex EXIT program point
@cindex postcondition
@cindex hierarchy of program points
@cindex program point hierarchy

Likewise, @code{foo():::EXIT} is the program point at the procedure
exit, and invariants there are postconditions.  When there are multiple
exit points from a procedure (for instance, because of multiple
@code{return} statements), the different exits are differentiated by
suffixing them with their line numbers; for instance,
@code{StackAr.top():::EXIT79}.  The exit point lacking a line number (in
this example, @code{StackAr.top():::EXIT}) collects the postconditions
that are true at every numbered exit point.  This is an example of a
program point that represents a collection of locations in the program
source rather than a single location.  This concept is represented in
Daikon by the dataflow hierarchy, see
@ref{Dataflow hierarchy,,,developer,Daikon Developer Manual}.

@cindex :::EXCEPTION program point
@cindex EXCEPTION program point

In a similar manner, @code{foo():::EXCEPTION} is the program point that
represents all the procedure's exceptional exits,
and invariants there are postconditions.  When there are multiple
exception exits from a procedure (for instance, because of multiple
@code{throw} statements), the different exits are differentiated by
suffixing them with their line numbers; for instance,
@code{StackAr.top():::EXCEPTION59}.

The Java instrumenter Chicory selects names for program
points that include an indication of the argument and return types for
each method.  These signatures are presented in @code{Class.getName} format: one
character for each primitive type (@samp{B} for byte, @samp{C} for
character, @samp{Z} for boolean, etc.);
@samp{L@var{classname};} for object types; and a @samp{[}
prefix for each level of array nesting.


@menu
* OBJECT and CLASS program points::
@end menu


@node    OBJECT and CLASS program points
@subsection OBJECT and CLASS program points
@cindex program point

@cindex :::OBJECT program point
@cindex OBJECT program point
@cindex :::CLASS program point
@cindex CLASS program point
@cindex object invariants
@cindex representation invariants
@cindex class invariants

Two program point tags that have special meaning to Daikon's hierarchy
organization are @code{:::OBJECT} and @code{:::CLASS}.
The @code{:::OBJECT} tag indicates object invariants (sometimes called
representation invariants or class invariants) over all the instance
(member) fields and static fields of the class.  These properties always hold
for any object of the given class, from the point of view of a client or
user.  These properties hold at entry to and exit from every public
method of the class (except not the entry to constructors, when fields
are not yet initialized).

The @code{:::CLASS} tag is just like @code{:::OBJECT}, but only for
static variables, which have only one value for all objects.  Static
fields and instance fields are often used for different purposes.
Daikon's separation of the two types of fields permits programmers to
see the properties over the static fields without knowing which are the
static fields and pick them out of the @code{:::OBJECT} program point.

@cindex private methods

(By contrast, @option{ESC/Java} and @option{JML} make class invariants hold even at the
entry and exit of private methods.  Their designers believe that most
private methods preserve the class invariant and are called only when
the class invariant holds.  @option{ESC/Java} and @option{JML} require an explicit
@dfn{helper} annotation to indicate a private method for which the class
invariant does not hold.)

A trace file does not contain samples for the @code{:::OBJECT} and
@code{:::CLASS} program points.  Variable values for these artificial
program points are constructed from samples that do appear in a trace file.
For example, an object invariant is a property that holds at entry to and
exit from every public method of the class, so the @code{:::OBJECT} program
point is constructed from samples at those points.


@node    Variable names
@section Variable names

A front end produces a trace file that associates trace variable names
with values.  Trace variable names need not be exactly the same as the
variables in the program.  The trace may contain values that are not
held in any program variables; in this case, the front end must make up
a name to express that value (see below for examples).

Daikon ignores variable names when inferring invariants; it uses the
names only when performing output.  (Thus, the only practical
restriction on trace names is that the @code{VarInfoName parse} method
must be able to parse the name.)

By convention, trace variables are similar to program variables and
field accesses.  For example, @code{w} and @code{x.y.z} are legal trace
variables.  (So are @samp{a[i]}, and
@samp{a[0].next}, but these are usually handled as derived variables
instead; see below.)  As in languages such as
Java and C, a period character represents field access and square
brackets represent selecting an element of a sequence.

@cindex derived variables, explanation of

In addition to variables that appear in the trace file, Daikon creates
additional variables, called @dfn{derived variables}, by combining trace
variables.  For example, for any array @code{a} and integer @code{i},
Daikon creates a derived variable @code{a[i]}.  This is not a variable
in the program (and this expression might not even appear in the source
code), but it may still be useful to compute invariants over this
expression.  For a list of derived variables and how to control Daikon's
use of them, see @ref{Options to enable/disable derived variables}.

@cindex nonsensical values for variables

Some trace variables and derived variables may represent meaningless
expressions; in such a circumstance, the value is said to be nonsensical
(@pxref{Nonsensical values,,,developer,Daikon Developer Manual}).

The remainder of this section describes conventions for naming
expressions.  Those that cannot be named by simple C/Java expressions
are primarily related to arrays and sequences.  (In part, these special
expressions are necessary because Daikon can only handle variables of
scalar (integer, floating-point, boolean, String) and array-of-scalar
types.  Daikon cannot handle structs, classes, or multidimensional
arrays or structures, but such data structures can be represented as
scalars and arrays by choosing variable names that indicate their
relationship.)


@itemize @bullet
@item
@code{a[i]} array access.
@code{a} and @code{i} are themselves
arbitrary variable names, of array and integral type, respectively.

@item
@cindex @code{-1} array index (counts from end of array)
@cindex negative array index (counts from end of array)
@code{a[-1]} from-end array access.
@code{a[-1]} denotes the last element of array @code{a};
it is syntactic sugar for @code{a[a.length-1]}.

@item
@cindex @code{[]} variable name (array contents)
@code{a[]} array contents.
For array-valued expression @code{a}, all of its elements, as a
sequence.  Simply using the expression @code{a} means the identity
(address or hashcode) of the array, not a list of its elements.  For two
arrays @code{a} and @code{b}, @samp{a=b} implies @samp{a[]=b[]}, but
@samp{a[]=b[]} does not imply @samp{a=b}.

@item @code{x.y}, @code{x->y} field access.
When field access is applied to a structure/class, it has the usual
meaning of selecting one field from the structure/class.

When field access is applied to an array, it means to map the field
access across the elements of the array.  For example, if @code{a} is an
array, then @code{a[].foo} is the sequence consisting of the @code{foo}
fields of each of the elements of @code{a}.  Likewise,
@code{a[].foo.bar} contains the @code{bar} fields of @code{a[].foo}.  By
contrast, @code{a.foo} does not make sense, because one cannot ask for
the @code{foo} field of an address, and @code{a[].foo[]} would be a
two-dimensional array.

@item
@cindex @code{.getClass()} variable
As in Java, @code{x.getClass()} is the runtime type of @code{x}, which may
differ from its declared type.

@item
@cindex @code{.length} variable name
@code{a.length} is the length (number of elements) of array @code{a};
this is not necessarily the number of initialized or used elements.

@item
@cindex @code{.toString} variable
@code{s.toString} is the string value of String @code{s}, namely a
sequence of characters.

@item
@code{Classname.varname} static class variable.
Static variables of a class have names of the form
@samp{@var{classname}.@var{varname}}

@item
@cindex @code{orig()} variable (pre-state value)
@cindex pre-state variables
@code{orig(x)} refers to the value of variable @code{x} upon
entry to a procedure (because the procedure body might modify the value
of @code{x}).  These variables appear only at @code{:::EXIT} and
@code{:::EXCEPTION} program
points.  Typically, @code{orig()} variables do not appear in the trace,
but are automatically created by Daikon when it matches up
a @code{:::ENTER} with a @code{:::EXIT@var{nn}}
or with a @code{:::EXCEPTION@var{nn}} program point.
@xref{orig variable example}.

This variable prints as @code{orig} when using Daikon output format
(@pxref{Invariant syntax}), but may print differently in other formats
(such as @code{\old}).

@item
@cindex @code{post()} variable (post-state value)
@cindex post-state variables
@code{post(x)} refers to the value of variable @code{x} upon exit from a
procedure.  Such a value is usually written simply @code{x}; the
@code{post} prefix is needed only within an @code{orig} expression, when
the post-state value needs to be referenced.  Just as @code{orig} may
be used only in a post-state context and specifies an expression to be
evaluated in the @samp{pre-state}, @code{post} may be used only in a
@samp{pre-state} context and specifies an expression to be evaluated in the
post-state.  @xref{orig variable example}.


@c Old version.  Do any of the front ends still do this?
@c @item
@c @cindex @code{::} variable (C global)
@c @code{::x} is the global variable @code{x}.

@item
@cindex @code{/} variable (C global or file-static)
@code{/globalVar} C global variable.  In C output, global variables with
external linkage are
prefixed with a slash.  For instance, global @code{/x} is distinct from
procedure parameter @code{/x}.  (In Java programs, variables can be
distinguished by prefixing them with @code{this.} or, for class-static
variables, a class name.)

@item
@code{myfile_c/staticVar} C static variable.  In C output, file-static
variables have names of the form @samp{@var{filename}/@var{varname}},
where periods (@samp{.}) in the filename are converted into underscores
(@samp{_}).  For example, @samp{Global_c/x} is the name for a
file-static variable @code{x} declared in the file @file{Global.c}).

@item
@cindex @code{@@} variable (C function-scoped static)
@code{myfile_c@@funcname/funcStaticVar} C function-scoped static variable.
In C output, for static variables which are
declared within functions, an at-sign @samp{@@} separates the filename
and the function name and then a slash separates the function name and
variable name (e.g., @samp{Global_c@@main/funcStaticVar} for a static
variable @code{funcStaticVar} declared within the function @code{main}
in the file @file{Global.c}).

@end itemize

@cindex local variables
@cindex variables, local
@cindex temporary (local) variables
@cindex variables, temporary (local)
Daikon's current front ends do not produce output for local variables,
only for variables visible from outside a procedure.  (Also see the
@option{--std-visibility} option to Chicory, @ref{Chicory options}.)
More generally, Daikon's front ends produce output at procedure exit and
entry, not within the procedure.  Thus,
Daikon's output forms a specification from the view of a client of a
procedure.  If you wish to compute invariants over local variables, you
can extend one of Daikon's front ends (or request us to do so).
An alternative that permits computing invariants at arbitrary locations
is to call a dummy procedure, passing all the variables of interest.
The dummy procedure's @nospellcheck{pre} and postconditions will be identical and will
represent the invariants at the point of call.


The array introduction operator @code{[]} can made Daikon variables look
slightly odd, but it is intended to assist in interpreting the variables
and to provide an indication that the variable name cannot be
substituted directly in a program as an expression.

Each array introduction operator @code{[]} increases the dimensionality
of the variable, and each array indexing operation @code{[i]} decreases
it.  Since all Daikon variables are scalars or one-dimensional arrays,
these operators must be matched up, or have at most one more @code{[]}
than @code{[i]}.  (There is one exception:  according to a strict
interpretation of the rules, the C/Java expression @code{a[i]} would
turn into the Daikon variable @code{a[][i]}, since it does not change
the dimensionality of any expression it appears in.  However, that would
be even more confusing, and the point is to avoid confusion, so by
convention Daikon front ends use just @code{a[i]}, not @code{a[][i]}.
Strictly speaking, none of the @code{[]} operators is necessary, since a
user with a perfect knowledge of the type of each program variable and
field could use that to infer the type of any Daikon expression.)


@menu
* orig variable example::
@end menu

@node       orig variable example
@subsection orig() variable example

@cindex @code{orig()} variable (pre-state value)

This section gives an example of use of @code{orig()} and @code{post()}
variables and arrays.

Suppose you have initially that (in Java syntax)
@example
int i = 0;
int[] a = new int[] @{ 22, 23 @};
int[] b = new int[] @{ 46, 47 @};
@end example

@noindent
and then you run the following:
@example
// pre-state values at this point
a[0] = 24;
a[1] = 25
a = b;
a[0] = 48;
a[1] = 49;
i = 1;
// post-state values at this point
@end example

@noindent
The values of various variables are as follows:

@table @code
@item orig(a[i]) = 22
The value of @code{a[i]} in the @samp{pre-state}: @{22, 23@}[0]

@item orig(a[])[orig(i)] = 22
This is the same as orig(a[i]):   @{22, 23@}[0].

@item orig(a[])[i] = 23
The value of @code{a[]} in the @samp{pre-state} (which is an array object, not
a reference), indexed by the post-state value of i:  @{22, 23@}[1]

@item orig(a)[orig(i)] = 24
@code{orig(a)} is the original value of the reference @code{a}, not
@code{a}@verb{|'s|} original elements: @{24, 25@}[0]

@item orig(a)[i] = 25
The original pointer value of a, indexed by the post-state value
of i:  @{24, 25@}[1]

@item a[orig(i)] = 48
In the post-state, @code{a} indexed by the original value of
@code{i}: @{48, 49@}[0]

@item a[i] = 49
The value of @code{a[i]} in the post-state.

@item b = orig(b) = @var{some hashcode}
The identity of the array @code{b} has not changed.

@item b[] = [48, 49]
@itemx orig(b[]) = [46, 47]
For an array @code{b}, @samp{b=orig(b)} does not imply @samp{b[]=orig(b[])}.

@item orig(a[post(i)]) = 23
The @samp{pre-state} value of @code{a[1]} (because the post-state value of
@code{i} is 1):  @{22, 23@}[1]

@end table

@node    Interpreting output
@section Interpreting Daikon output

@cindex @samp{Exiting}, in Daikon output

If nothing gets printed before the @samp{Exiting} line, then Daikon
found no invariants.  You can get a little bit more information by using
the @option{--output_num_samples} flag to Daikon
(@pxref{Options to control Daikon output}).

@cindex nonsensical values, ignored when computing invariants

Daikon's output is predicated on the assumption that all expressions
that get evaluated are sensible.  For instance, if Daikon prints
@samp{a.b == 0}, then that means that @emph{if} @samp{a.b} is sensible (that
is, @samp{a} is non-null), then its value is zero.  When @samp{a} is
@samp{null}, then @samp{a.b} is called @dfn{nonsensical}.  Daikon's output
ignores all nonsensical values.  If you would like
the assumptions to be printed explicitly, then set the
@option{daikon.Daikon.guardNulls} configuration option (@pxref{General
configuration options}).


@menu
* Redundant invariants::
* Equal variables::
* Has only one value variables::
* Object inequality::
@end menu

@node       Redundant invariants
@subsection Redundant invariants

By default, Daikon does not display redundant invariants --- those
that are implied by other invariants in the output --- because such
results would merely clutter the output without adding any valuable
information.  For instance, if Daikon reports @samp{x==y}, then it never
also reports @samp{x-1==y-1}.  You can control this behavior to some extent by
disabling invariant filters; @pxref{Invariant filters}.
(You can also print all invariants, even
redundant ones, by saving the invariants to a @file{.inv} file and
then using the @command{PrintInvariants} (@pxref{Printing invariants}) or Diff
(@pxref{Invariant Diff}) programs to print the results.)


@node       Equal variables
@subsection Equal variables

If two variables @code{x} and @code{y} are equal, then any invariant
about @code{x} is also true about @code{y}.  Daikon chooses one variable
(the leader) from the set of equal variables, and only prints invariants
over the leader.
@c This is true, but I believe it detracts from the point.
@c Daikon also prints equalities about the variables in the set.

Suppose that @code{a = b = c}.  Then Daikon will print @code{a = b} and
@code{a = c}, but not @code{b = c}.  Furthermore, Daikon might print
@code{a > d}, but would not print @code{b > d} or @code{c > d}.

You can control which variables are in an equality set;
@pxref{Variable comparability,,,developer,Daikon Developer Manual}.


@node       Has only one value variables
@subsection Has only one value variables

@cindex has only one value, in invariant output
@cindex hashcode type, for variables

The output @samp{@var{var} has only one value} in Daikon's output means
that every time that variable @var{var} was encountered, it had the same
value.  Daikon ordinarily reports the actual value, as in
@samp{@var{var} == 22}.
Typically, the ``has only one value'' output means that the variable is a
hashcode or address --- that is, its declared type is @samp{hashcode}
(@pxref{Variable declarations,,,developer,Daikon Developer Manual}).
For example, @samp{@var{var} == 0x38E8A} is not very illuminating,
but it is still interesting that
@var{var} was never rebound to a different object.

Note that @samp{@var{var} has only one value} is different from
saying that @var{var} is unmodified.

A variable might have only one value but @emph{not} be reported as unmodified
because the variable is not a parameter to a procedure --- for instance,
if a routine always returns the same object, or in a class invariant.  A
variable can be reported as unmodified but @emph{not} have only one value
because the variable is never modified during any execution of the
procedure, but has different values on different invocations of the
procedure.


@node       Object inequality
@subsection Object inequality

Daikon may report @samp{x < y} where the operator @samp{<} is not
applicable to the type of @samp{x} and @samp{y}, as in @samp{myString <
otherString}.

In this case, the invariant means that the first expression is always less
than the second, according to the @samp{Comparable.compareTo} method.



@node    Invariant list
@section Invariant list

@cindex invariant list
@cindex invariants, list of all
The following is a list of all of the invariants that Daikon detects.
Each invariant has a configuration enable switch.  By default most invariants
are enabled.  Any that are not enabled by default are indicated below.
Some invariants also have additional configuration switches that control
their behavior.  These are indicated below as well.
@xref{Options to enable/disable specific invariants}.

@tex
\global\hfuzz=35pt
@end tex
@table @asis
@exampleindent 0
@include invariants-doc.texinfo
@exampleindent 4
@end table
@tex
\global\hfuzz=1pt
@end tex

@node    Invariant filters
@section Invariant filters

@cindex invariant filters
@cindex filters

Invariant filters are used to suppress the printing of invariants that
are true, but not considered ``interesting'' --- usually
because the invariants are considered obvious or redundant in a given
context.

The following is a list of the invariant filters that Daikon supports.
Each of these filters has a corresponding configuration enable switch;
by default, all filters are enabled.  @xref{Options to enable/disable filters},
for details.

@itemize @bullet

@cindex DerivedParameterFilter
@item DerivedParameterFilter: suppress parameter-derived postcondition invariants

This filter suppresses invariants at procedure exit points that are
uninteresting because they refer to @samp{pre-state} variables derived from
pass-by-value parameters.  For example, suppose that @code{param} is a
parameter to a
Java method.  If @code{param} itself is modified, that change won't be
visible to a caller, so it's uninteresting to print.  If @code{param} points
to an object, and that object is changed, that is visible, but
only if @code{param} hasn't changed; otherwise, the invariant would report a
change in some object other than the one that was passed in.


@cindex ObviousFilter
@cindex implied invariant
@cindex redundant invariant
@item ObviousFilter: suppress ``obvious'', or redundant, invariants ---
that is, invariants that are implied by some other invariant

This filter suppresses any invariant that is a logical consequence of
other invariants that are printed.  This keeps the output from becoming
cluttered with redundant facts.  Some examples are:

@itemize @bullet

@item If @samp{size(args[])==0} is shown, then @samp{size(args[])-1==-1} is
obvious and will not be displayed by default.
@item If @samp{this.topOfStack < size(this.theArray[])-1} is shown, then
@samp{this.@/topOfStack < size(this.theArray[])} is obvious and will not be
displayed by default.

@end itemize

To suppress even more invariants, use the @option{--suppress_redundant}
command-line option; @pxref{Options to control invariant detection}.


@cindex OnlyConstantVariablesFilter
@item OnlyConstantVariablesFilter: suppress invariants containing only constants

This filter suppresses comparison invariants in which all of the
variables being compared were observed to be constant.  In the current
version of Daikon, most such invariants are not even created in the
first place, because constants are detected on an early pass over the
data.  However, Daikon will note that all of the invariants that had
any particular constant value were also equal to each other: such
invariants will be suppressed by this filter.


@cindex ParentFilter
@item ParentFilter:  filter invariants that match a parent program point invariant

A controlled invariant is an invariant that is ``controlled'' --- or
implied --- by a parent program point in the dataflow hierarchy.
For example, for Java instrumented
code each class is associated with an object program point, which
contain invariants that are found at the entry and exit of all public
methods.  So in addition to the usual program points such as
@code{StackAr.StackAr(int):::ENTER} and
@code{StackAr.isEmpty():::EXIT48}, Daikon outputs invariants for the
artificial program point @code{StackAr:::OBJECT}.  The invariants for
@code{StackAr:::OBJECT} control the invariants for
@code{StackAr.StackAr(int):::ENTER} and
@code{StackAr.isEmpty():::EXIT48}, because the former imply the latter.
Because of this redundancy, controlled invariants are not displayed by
default.  Note that if for some reason, the controlling invariant is not
displayed (for example, because it's unjustified), then the controlled
invariant @emph{will} be displayed.

@cindex SimplifyFilter
@item SimplifyFilter:  eliminate redundant invariants using Simplify

Daikon contains built-in test that remove most redundant (logically
implied) invariants from its output; see

Daikon can use the Simplify theorem-prover to eliminate even more
implied invariants than Daikon's built-in tests are able to eliminate.
Simplify must be installed in
order to take advantage of this filter (@pxref{Installing Simplify}).

If you don't also specify the @option{--suppress_redundant} command-line
option (@pxref{Options to control invariant detection}) to enable
Simplify processing, this filter doesn't do anything.

@cindex UnjustifiedFilter
@item UnjustifiedFilter:  suppress unjustified invariants

For every invariant, Daikon estimates the probability of that invariant
happening by chance.  If that probability is less than the limit, then
the invariant is deemed to be an actual invariant, not just a chance
occurrence.  Currently the limit is .01.  So by default, only invariants
with probabilities of less than 1% are shown.  See the @option{--conf_limit}
option (@ref{Options to control invariant detection}).


@cindex UnmodifiedVariableEqualityFilter
@item UnmodifiedVariableEqualityFilter:  suppress invariants that merely indicate that a variable was unmodified

This filter is only useful for @option{ESC} output.

@end itemize


@node    Enhancing Daikon output
@chapter Enhancing Daikon output

@menu
* Configuration options::
* Conditional invariants::
* Enhancing conditional invariant detection::
* Dynamic abstract type inference (DynComp)::
* Loop invariants::
@end menu

@node    Configuration options
@section Configuration options

@cindex configuration options
@cindex dkconfig_ variables

Many aspects of Daikon's behavior can be controlled by setting various
configuration parameters.  These configuration parameters control which
invariants are checked and reported, the statistical tests for
invariants, which derived variables are created, and more.

There are two ways to set configuration options.  You can
specify a configuration setting directly on the command line,
using the @option{--config_option @var{name}=@var{value}} option (which you
may repeat as many times as you want).
Or, you can create a configuration file and
supplying it to Daikon on the command line using the @option{--config
@var{filename}} option.  Daikon applies all the command-line arguments
in order.  You may wish to use the supplied
example configuration file
@file{daikon/java/daikon/config/example-settings.txt} as an example when
creating your own configuration files.  (If you did not download
Daikon's sources, you must extract the example from
@file{daikon.jar} to read it.)

You can also control Daikon's output via its command-line options
(@pxref{Running Daikon}) and via the command-line options to its front
ends --- such as DynComp (@pxref{DynComp for Java options}),
Chicory (@pxref{Chicory options}) or Kvasir (@pxref{Kvasir options}).

The configuration options are different from the debugging flags
@option{--debug} and @option{--dbg @var{category}}
(@pxref{Daikon debugging options}).
The debugging flags permit Daikon to produce debugging
output, but they do not affect the invariants that Daikon computes.

@menu
* List of configuration options::
@end menu

@node       List of configuration options
@subsection List of configuration options

This is a list of all Daikon configuration options.
The configuration option name contains the
Java class in which it is defined.  (In the Daikon source code, the
configuration value is stored in a variable whose name contains a
@code{dkconfig_} prefix, but that should be irrelevant to users.)
To learn more about a specific invariant or derived variable than
appears in this manual, see its source code.

@c The config options are categorized into sections by pattern-matching
@c their names.  If you are adding new options, you might want to choose
@c names similar to those of similar options.
@c Currently the categories are:
@c   daikon.inv.filter.*.enabled  -> turn filters on/off
@c   daikon.inv.*.enabled -> turn invariant detection on/off
@c   daikon.inv.* -> other invariant configuration
@c   daikon.derive.* -> turn derived parameters on/off
@c   daikon.simplify.* -> options for Simplify
@c   * -> general options
@c See ParameterDoclet.java for details.

@include config-options.texinfo


@node    Conditional invariants
@section Conditional invariants (disjunctions) and implications
@cindex splitting
@cindex splitting condition
@cindex conditional invariant
@cindex invariant, conditional
@cindex implication invariant
@cindex invariant, implication
@cindex disjunction
@cindex disjunctive invariant
@cindex invariant, disjunctive

Conditional invariants are invariants that are true only part of the time.
For instance, consider the absolute value procedure.  Its postcondition is
@example
if arg < 0
  then return == -arg
  else return == arg
@end example

@noindent
The invariant @code{return == -arg} is a conditional invariant because
it depends on the predicate @code{arg < 0} being true.  An
@emph{implication} is a compound invariant that includes both the
predicate and the conditional invariant (also called the consequent);
an example of an implication is @code{arg < 0 ==> return == -arg}.

@cindex context-sensitive invariant
@cindex call-site-dependent invariant

Another type of implication is a @i{context-sensitive} invariant --- a
fact about method A that is true only when A is called by method B, but
not true in general about A.
You can use the configuration option
@code{daikon.split.ContextSplitterFactory.granularity} to control creation
of context-sensitive invariants.
Alternately, you can use implications to construct
context-sensitive invariants:  set a variable that depends on the call
site, then compute an implication whose predicate tests that variable.
For an example, see the paper @cite{Selecting, refining, and evaluating
predicates for program analysis}
(@uref{http://plse.cs.washington.edu/daikon/pubs/predicates-tr914-abstract.html}).

Daikon must be supplied with the predicate for an implication.  Daikon has
certain built-in predicates that it uses for finding conditional invariants;
examples are which return statement was executed in a procedure and whether a
boolean procedure returns true or false.  Additionally, Daikon can read
predicates from a file called a splitter info (@file{.spinfo}) file and find
implications based on those predicates.  The splitter info file can be produced
automatically, such as by static analysis of the program using the @command{CreateSpinfo}
and @command{CreateSpinfoC} programs (@pxref{Static analysis for splitters})
or by cluster analysis of the
traced values in the data trace file.  Details of these techniques and usage
guides can be found in @ref{Enhancing conditional invariant detection}.  Users
can also create splitter info files themselves or can augment
automatically-created ones.

To detect conditional invariants and implications:
@enumerate
@item
Create the splitter info file, either automatically or by hand.
@item
Run Daikon with the @file{.spinfo} file as one of its arguments.
(The order of arguments does not matter.)
For example,
@exampleindent 1
@example
java daikon.Daikon Foo.decls Foo.spinfo Foo.dtrace
@end example
@exampleindent 4
@end enumerate

The term @dfn{splitter} comes from Daikon's technique for detecting
implications and conditional invariants.  For each predicate, Daikon
creates two conditional program points --- one for program executions
that satisfy the condition and one for those that don't --- and splits
the data trace into two parts.  Invariant detection is then performed
on the conditional program points (that is, the parts of the data
trace) separately and any invariants detected are reported as
conditional invariants (as implications).

To be precise, we say that an invariant holds exclusively if it is
discovered on one side of a split, and its negation is discovered on
the opposite side.  Daikon creates conditional invariants whose
predicates are invariants that hold exclusively on one side of a
split, and whose consequents are invariants that hold on that side of
the split but not on the unsplit program point.  If Daikon finds
multiple exclusive conditions, it will create biconditional (``if and
only if'') invariants between the equivalent conditions.  Within the
context of the program, each of the exclusive conditions is equivalent
to the splitting condition.  In particular, if both the splitting
condition and its negation are within the grammar of invariants that
Daikon detects, the splitting condition may appear as the predicate of
the generated conditional invariants.  On the other hand, if other
equivalent conditions are found, or if the splitting condition is not
expressible in Daikon's grammar, it might not appear in the generated
implications.

@cindex dummy invariant
@cindex invariant, dummy

In some cases, the default policy of selecting predicates from
Daikon's output may be insufficient.  For instance, Daikon might not
detect any invariant equivalent to the splitting condition, if the
splitting condition is
sufficiently complex or application-specific.  In such situations,
Daikon can also use the splitting condition itself, as what is called a
@dfn{dummy invariant}.
@c @c This information seems irrelevant and not useful at this point in
@c @c the manual.
@c   A ``dummy
@c invariant'' is one whose meaning is not dealt with directly by Daikon;
@c instead Daikon knows only how to print the invariant in its output.
@c When a tool or a user writes a splitter info file, the file can
@c specify a way to print the condition represented by the splitter in
@c any of Daikon's output formats.  If the use of dummy invariants is
@c enabled, invariants with the supplied output formats will be used as
@c the predicates of conditional invariants.
To use dummy invariants, set the configuration option
@option{daikon.split.PptSplitter.dummy_invariant_level} to a
non-zero value (see @ref{List of configuration options}).

@menu
* Splitter info file format::
* Indiscriminate splitting::
* Example splitter info file::
@end menu

@node       Splitter info file format
@subsection Splitter info file format
@cindex splitter info file
@cindex .spinfo file
@cindex spinfo file

A splitter info file contains the conditions that Daikon should use to
create conditional invariants.  Each section in the @file{.spinfo}
file consists of a sequence of non-blank lines; sections are separated
by blank lines.  There are two types of sections:  program point
sections and replacement sections.
@xref{Example splitter info file}, for an example splitter info file.

@menu
* Program point sections::
* Replacement sections::
@end menu

@node          Program point sections
@subsubsection Program point sections

Program point sections have a line specifying a program point name
followed by lines specifying the condition(s) associated with that
program point, each condition on its own line.  Additional information
about a condition may be specified on indented lines.  For example, a
typical entry is

@example
PPT_NAME @var{pptname}
@var{condition1}
@var{condition2}
    DAIKON_FORMAT @var{string}
    ESC_FORMAT @var{string}
@var{condition3}
...
@end example

@noindent
@var{pptname} can be any string that matches a part of the desired
program point name as printed in the @file{.decls} file.  In finding matching
program points, Daikon uses the first program point that matches
@var{pptname}.  Caution is necessary when dealing with method names
that are prefixes of other method names.  For instance, if the class
@code{List} has methods @code{add} and @code{addAll}, specifying
@samp{PPT_NAME List.add} might select either method, depending on
which was encountered first.  Instead writing @samp{PPT_NAME
List.add(} will match only the @code{add} method.

Each condition is a Java expression of boolean type.  All variables
that appear in the condition must also appear in the declaration of
the program point in the @file{.decls} file.  (In other words, all the
variables must be in scope at the program point(s) where the Splitter
is intended to operate.)  The automatically generated Splitter source
code fails to compile (but Daikon proceeds without it) if a variable
name in a condition is not found at the matching program point.

An indented lines beginning with @samp{DAIKON_FORMAT},
@samp{JAVA_FORMAT}, @samp{ESC_FORMAT}, or @samp{SIMPLIFY_FORMAT}
@c UNDONE is there a @samp{CSHARPCONTRACT_FORMAT}?
specifies how to print the condition.
These are optional; for any Daikon output format that is omitted,
the Java condition itself is used.
The alternate printed representation is used when the
splitting condition is used as a dummy
invariant; see configuration option
@option{daikon.split.PptSplitter.dummy_invariant_level}.


@node          Replacement sections
@subsubsection Replacement sections

Ordinarily, a splitting condition may not invoke user-defined methods,
because when Daikon reads data trace files, it does not have access to the
program source.  A replace section of the splitter info file can specify
the bodies of methods, permitting conditions to invoke those methods.  The
format is as follows:
@example
REPLACE
@var{procedure1}
@var{replacement1}
@var{procedure2}
@var{replacement2}
...
@end example

@noindent
where @var{replacementi} is a Java expression for the body
of @var{procedurei}.  In each condition, Daikon replaces procedure
calls by their replacements.  A replace section may appear anywhere in
the splitter info file.

@node       Indiscriminate splitting
@subsection Indiscriminate splitting

Each condition in an @file{.spinfo} is associated with a program point.
The condition can be used at only that program point
by placing the following line in a file that is
passed to Daikon via the @option{--config} flag
(@pxref{Daikon configuration options}):
@example
daikon.split.SplitterList.all_splitters = false
@end example

The default, called @dfn{indiscriminate splitting}, is to use every
condition at every
program point, regardless of where in the @file{.spinfo} file the
condition appeared.

The advantage of indiscriminate splitting is that a condition that is
useful at one program point may also be useful at another --- if the
same variables are in scope or other variables of the same name are in
scope.
The disadvantage of indiscriminate splitting is that it slows Daikon down.

Daikon uses a condition only where it can be used.  For example, the
condition @code{myArray.length == x} is applicable only at program points
that have variables named @code{myArray} and @code{x}.  To see
warnings about places a splitting condition cannot be used (reported as
failure to compile splitters at those locations), place the following line
in a file that is passed to Daikon via the @option{--config} flag
(@pxref{Daikon configuration options}):
@example
daikon.split.SplitterList.all_splitters_errors = true
@end example


@node       Example splitter info file
@subsection Example splitter info file

Below is an implementation of a simple Queue for positive integers and
a corresponding @file{.spinfo} file.  The splitter info file is like
the one that @command{CreateSpinfo} would create for that class, but
also demonstrates some other features.

@menu
* Example class::
* Resulting .spinfo file::
@end menu

@node          Example class
@subsubsection Example class

@smallexample
class simpleStack @{

  private int[] myArray;
  private int currentSize;

  public simpleStack(int capacity) @{
    myArray = new int[capacity];
    currentSize = 0;
  @}

  /** Adds an element to the back of the stack, if the stack is
    * not full.
    * Returns true if this succeeds, false otherwise.  */
  public String push(int x) @{
    if ( !isFull() && x >= 0) @{
      myArray[currentSize] = x;
      currentSize++;
      return true;
    @} else @{
      return false;
    @}
  @}

  /** Returns the most recently inserted stack element.
    * Returns -1 if the stack is empty. */
  public int pop() @{
    if ( !isEmpty() ) @{
      currentSize--;
      return myArray[currentSize];
    @} else @{
      return -1;
    @}
  @}

 /** Returns true if the stack is empty, false otherwise. */
  private boolean isEmpty() @{
    return (currentSize == 0);
  @}

  /** Returns true if the stack is full, false otherwise. */
  private boolean isFull() @{
    return (currentSize == myArray.length);
  @}
@}
@end smallexample

@node          Resulting .spinfo file
@subsubsection Resulting .spinfo file

@smallexample
REPLACE
isFull()
currentSize == myArray.length
isEmpty()
currentSize == 0

PPT_NAME  simpleStack.push
!isFull() && x >= 0
    DAIKON_FORMAT !isFull() and x >= 0
    SIMPLIFY_FORMAT (AND (NOT (isFull this)) (>= x 0))

PPT_NAME  simpleStack.pop
!isEmpty()

PPT_NAME  simpleStack.isFull
currentSize == myArray.length - 1

PPT_NAME  simpleStack.isEmpty
currentSize == 0
@end smallexample

@node    Enhancing conditional invariant detection
@section Enhancing conditional invariant detection

The built-in mechanisms (@pxref{Conditional invariants}) have
limitations in the invariants they can find.  By supplying splitting
conditions to Daikon via a splitter info file, the user can infer more
conditional invariants.  To ease this task, there are methods to
automatically create splitter info files for use by Daikon.

@menu
* Static analysis for splitters::
* Cluster analysis for splitters::
* Random selection for splitters::
@end menu


@node       Static analysis for splitters
@subsection Static analysis for splitters

@cindex splitting conditions, static analysis
@cindex static analysis for splitters
@cindex CreateSpinfo
@cindex CreateSpinfoC

In static analysis, all boolean statements in the program
source are extracted and used as splitting conditions.  The assumption is that
conditions that are explicitly tested in the program are likely to affect the
program's behavior and could lead to useful conditional invariants.
The simple heuristic of using
these conditional statements as predicates for conditional invariant
detection is often quite effective.

@menu
* Static analysis of Java for splitters::
* Static analysis of C for splitters::
@end menu


@node       Static analysis of Java for splitters
@subsubsection Static analysis of Java for splitters

The @command{CreateSpinfo} program takes Java source code as input and creates a
splitter info file for each Java file; for instance,
@example
java daikon.tools.jtb.CreateSpinfo Foo.java Bar.java
@end example

@noindent
creates the splitter info files @file{Foo.spinfo} and
@file{Bar.spinfo}.
Given an @option{-o @var{filename}} argument, @command{CreateSpinfo} puts all the
splitters in the specified file instead.
The resulting splitter info file(s) contains each
boolean expression that appears in the source code.

If you get an error such as
@example
jtb.ParseException: Encountered ";" at line 253, column 8.
Was expecting one of: "abstract" ...
@end example

@noindent
then you may have encountered a bug in the JTB library on which
@command{CreateSpinfo} is built.  It does not permit empty declarations in a
class body.  Remove the extra semicolon in your Java file (at the
indicated position) and re-rerun @command{CreateSpinfo}.


@node       Static analysis of C for splitters
@subsubsection Static analysis of C for splitters

The @command{CreateSpinfoC} program performs the same function for
C source code as @command{CreateSpinfoC} does for Java.
@command{CreateSpinfoC} can only be run on postprocessed source
files---that is, source files contain no @command{CPP} commands.  @command{CPP} commands
are lines starting with @samp{#}, such as @samp{#include}.  To
expand @command{CPP} commands into legal C, run either @command{cpp -P} or
@command{gcc -P -E}.  For instance, here is how you could use @command{CreateSpinfoC}:
@example
cpp -P foo.c foo.c-expanded
cpp -P bar.c bar.c-expanded
java daikon.tools.jtb.CreateSpinfoC \
     foo.c-expanded bar.c-expanded
@end example

@noindent
WARNING:  The names produced by @command{CreateSpinfoC} sometimes differ
from the names produced by Kvasir.  For example, suppose you have a C
file that contains a function @samp{foo}.  Then @command{CreateSpinfoC}
may create a @file{.spinfo} file that mentions a program point named
@samp{std.foo}, whereas Kvasir creates a @file{.dtrace} file that
mentions a program point named @samp{..foo}.  Such a mismatch will cause
Daikon to produce no conditional invariants for the given program point.
This is a bug that needs to be fixed!  (Patches are welcome.)  In the
meanwhile, you can edit the generated @file{.spinfo} file to conform to the
@file{.dtrace} file's naming conventions.

If you get an error such as
@example
... Lexical error at line 5, column 1.
Encountered: "#" (35), after : ""
@end example

@noindent
then you forgot to run @command{CPP} before running @command{CreateSpinfoC}@.

If you get an error such as
@example
CreateSpinfoC encountered errors during parse.
Encountered "__extension__ typedef struct @{  ...
@end example

@noindent
then your program uses non-standard C syntax.  The @samp{__extension__}
keyword is supported only by the @command{gcc} compiler, and isn't handled by
the @command{CreateSpinfoC} program.  You could extend the @command{CreateSpinfoC} program
to handle non-standard @command{gcc} extensions, or you could remove non-standard
@command{gcc} extensions from your program.  The extensions might also result from
standard libraries rather than your own program --- removing a
directives such as @samp{#include <stdio.h>} when preprocessing may also
resolve the problem.


@node       Cluster analysis for splitters
@subsection Cluster analysis for splitters

@cindex splitting conditions, cluster analysis
@cindex cluster analysis for splitters
@cindex runcluster.pl program

Cluster analysis is a statistical method that finds groups or clusters
in data.  The clusters may indicate conditional properties in the
program.  The
cluster analysis mechanism finds clusters in the data trace file,
infers invariants over any clusters that it finds, and writes these
invariants into a splitter info file.
Then, you supply the splitter info file to Daikon in order to
infer conditional invariants.

To find splitting conditions using cluster analysis, run the
@command{runcluster.pl} program (found in the @file{$DAIKONDIR/scripts}
directory) in the following way:
@example
runcluster.pl [@var{options}] @var{dtrace_file ...} @var{decls_files ...}
@end example

@noindent
The @var{options} are:
@table @option

@cindex kmeans cluster analysis
@cindex hierarchical cluster analysis
@cindex xm cluster analysis
@item -a @var{ALG}
@itemx --algorithm @var{ALG}
@var{ALG} specifies a clustering algorithm.
Current options are @samp{km} (for kmeans), @samp{hierarchical},
and @samp{xm} (for xmeans).  The default is @samp{xm}.

@item -k
The number of clusters to use (for algorithms which require
this input, which is everything except xmeans).  The default is 4.

@item --keep
Don't delete the temporary files created by the clustering
process.  This is a debugging flag.
@end table

The @command{runcluster.pl} script currently supports three clustering
programs.  They are implementations of the kmeans algorithm,
hierarchical clustering, and the xmeans algorithm (kmeans algorithm
with efficient discovery of the number of clusters).  The kmeans and
hierarchical clustering tools are provided in the Daikon
distribution.  The xmeans code and executable are publicly available at
@uref{http://www.cs.cmu.edu/~dpelleg/kmeans.html} (fill in the license
form and mail it in).

@node       Random selection for splitters
@subsection Random selection for splitters

@cindex splitting conditions, random selection
@cindex random selection for splitters
@cindex TraceSelect tool

Random selection can create representative samples of a data set with
the added benefit of finding conditional properties and eliminating
outliers.  Given trace data, the @command{TraceSelect} tool creates several
small subsets of the data by randomly selecting parts of the original
trace file.  Any invariant that is discovered in the smaller samples but
not found over the entire data is a conditional invariant.

To find splitting conditions using random selection, run the
@command{daikon.tools.TraceSelect} program in the following way:
@example
java daikon.tools.TraceSelect @var{num_reps} @var{sample_size} [@var{options}] \
    @var{dtrace_file} @var{decls_files ...} [@var{daikon_options}]
@end example

@noindent
@var{num_reps} is the number of subsets to create, and @var{sample_size} is the
number of invocations to collect for each method.

The @var{daikon_options} are the same options that can be provided to the
@command{daikon.Daikon} program.

The @var{options} for @command{TraceSelect} are:
@table @option

@item -NOCLEAN
Don't delete the temporary trace samples created by the random
selection process.  This can help for debugging or for using the tool
solely to create trace samples instead of calculating invariants over
the samples.

@item -INCLUDE_UNRETURNED
Allows random selection to choose method invocations that entered the
method successfully but did not exit normally; either from a thrown
Exception or abnormal termination.

@item -DO_DIFFS
Creates an @file{.spinfo} file for generating conditional invariants and
implications by reporting the invariants that appear in at least one
of the samples but not over the entire data set.

@end table

@node    Dynamic abstract type inference (DynComp)
@section Dynamic abstract type inference (DynComp)

Abstract types group variables that are used for related purposes in a
program.
For example, suppose that some @code{int} variables in your program
are array indices, and other @code{int} variables
represent time.  Even though these variables have the same type
(@code{int}) in the programming language, they have different abstract
types.

Abstract types can be provided as input to Daikon, so that it
only infers invariants between values of the same abstract type.
This has two benefits.
First, it improves Daikon's performance, often by over an order of magnitude,
because it reduces
the number of potential invariants that must be checked.
Second, it reduces spurious output caused by invariants over unrelated variables.
You are strongly recommended to supply abstract types when running Daikon;
Daikon does not produce satisfactory output without abstract type information.

Abstract type inference is performed by the front-ends, before Daikon runs.
The Daikon distribution includes three tools that
infer abstract types (also called comparability types) from program
executions.

@itemize
@item
The Java DynComp tool produces a comparability file that must then be
supplied to the Chicory Java front-end.  For examples of using DynComp
with Java programs, see @ref{Detecting invariants in Java programs}.  For
full details about the DynComp tool for Java, see @ref{DynComp for
Java}.

@item
The Kvasir front-end for C/C++ binaries by default uses a DynComp mode in which it
produces a separate @file{.decls} file containing comparability
information, which must be supplied to Daikon along with the
@file{.dtrace} file.  For examples of using DynComp with C programs, see
@ref{C examples}.  For full details about the DynComp
tool for C/C++, see @ref{DynComp for C/C++}.

@item
The Celeriac front-end for .NET programs can compute variable
comparability.  It does so statically by examining the program text, rather
than dynamically by running the program as DynComp does.
For full details about variable comparability in Celeriac, see
@uref{https://github.com/codespecs/@/daikon-dot-net-front-end}.

@end itemize

@node    Loop invariants
@section Loop invariants

@cindex loop invariants
@cindex local variables

Daikon does not by default output loop invariants.  Daikon can detect
invariants at any location where it is provided with variable values,
but currently Daikon's front ends do not supply Daikon with variable values
at loop heads.

You could extend a front end to output more variable values, or you
could write a new front end.

Alternately, here is a way to use the current front ends to produce loop
invariants.  This workaround requires you to change your program, but it
requires no change to Daikon or its front ends.

At the top of a loop (or at any other location in the program at which
you would like to obtain invariants), insert a call to a dummy procedure
that does no work but returns immediately.  Pass, as arguments to the
dummy procedure, all variables of interest (including local variables).
Daikon will produce (identical) preconditions and postconditions for the
dummy procedure; these are properties that held at the call site.

For instance, you might change the original code
@example
  public void calculate(int x) @{
    int tmp = 0;
    while (x > 0) @{
      // you desire to compute an invariant here
      tmp=tmp+x;
      x=x-1;
    @}
  @}
@end example

@noindent
into
@example
  public void calculate(int x) @{
    int tmp = 0;
    while (x > 0) @{
      calculate_loophead(x, tmp);
      tmp=tmp+x;
      x=x-1;
    @}
  @}

  // dummy procedure
  public void calculate_loophead(int x, int tmp) @{
  @}
@end example


@node    Front ends (instrumentation)
@chapter Front ends (instrumentation)

@cindex front end
@cindex instrumentation

The Daikon invariant detector is a machine learning tool that finds
patterns (invariants) in data.  That data can come from any source, but
Daikon is typically used to find invariants over variable values in
running programs.  A front end is a tool that converts data from some
other format into Daikon's input format.  The most common type of front
end is an instrumenter, which causes your program to output a
@file{.dtrace} file that Daikon can process, or that you can process
(@pxref{Reading dtrace files,,,developer,Daikon Developer Manual}).

This chapter describes several front ends (instrumenters) that are part
of Daikon.  It
is relatively easy to build your own front end, if these do not serve
your purpose; we are aware of a number of users who have done so.  For
more information about building a new front end, see @ref{New front
ends,,,developer,Daikon Developer Manual}.


@menu
* Chicory::
* DynComp for Java::
* Kvasir::
* Celeriac::
* dfepl::
* convertcsv.pl::
* Other front ends::
@end menu

@node    Chicory
@section Java front end Chicory

@cindex front end for Java
@cindex Java front end
@cindex instrumentation, of Java programs
@cindex Chicory (front end for Java)

The Daikon front end for Java, named Chicory, executes Java programs,
creates data trace (@file{.dtrace}) files, and optionally runs Daikon on
them.  Chicory is named after the chicory plant, whose root is sometimes
used as a coffee substitute or flavor enhancer.

While Daikon can be run using only the Chicory front end, it is highly
recommend that DynComp be run prior to Chicory. See @ref{DynComp for Java}
for more details.

To use Chicory, run your program as you normally would, but
replace the @command{java} command with @command{java daikon.Chicory}.  For
instance, if you usually run
@example
java mypackage.MyClass arg1 arg2 arg3
@end example

@noindent
then instead you would run
@example
java daikon.Chicory mypackage.MyClass arg1 arg2 arg3
@end example

@noindent
This runs your program and creates file @file{MyClass.dtrace}
in the current directory.
Furthermore, a single command can both create a trace file and run Daikon:
@example
java daikon.Chicory --daikon mypackage.MyClass arg1 arg2 arg3
@end example

@noindent
See below for more options.

That's all there is to it!  Since Chicory instruments class files
directly as they are loaded into Java,
you do not need to perform separate instrumentation and recompilation steps.
However, you should compile your program with debugging information
enabled (the @option{-g} command-line switch to @command{javac});
otherwise, Chicory uses the names @code{arg0}, @code{arg1}, @dots{} as
the names of method arguments.

Chicory must be run in a version 7 (or later) JVM, but it is
backward-compatible with older versions of Java code.  Chicory can process
class files from any version of Java.

@menu
* Chicory options::
* Static fields (global variables)::
@end menu

@node       Chicory options
@subsection Chicory options

Chicory is invoked as follows:
@example
java daikon.Chicory @var{chicory-args} @var{classname} @var{args}
@end example

@noindent
where
@example
java @var{classname} @var{args}
@end example

@noindent
is a valid invocation of Java.

This section lists the optional command-line arguments to Chicory, which
appear before the @var{classname} on the Chicory command line.

@menu
* Program points in Chicory output::
* Variables in Chicory output::
* Chicory miscellaneous options::
@end menu

@node          Program points in Chicory output
@subsubsection Program points in Chicory output

@c Perhaps explain why --trace-percent doesn't appear here:  it doesn't
@c affect the .decls structure.

This section lists options that control which program points appear in
Chicory's output.


@table @option
@item --ppt-select-pattern=@var{regexp}
Only produce trace output for classes/procedures/program points whose
names match the
given regular expression.  This option may be supplied multiple times,
and may be used in conjunction with @option{--ppt-omit-pattern}.

When this switch is supplied, filtering occurs in the following way:
for each program point, Chicory checks the fully
qualified class name, the method name, and the
the program point name against each @var{regexp} that
was supplied.  If any of these match, then the program point is included
in the instrumentation.

Suppose that method @code{bar} is defined only in class @code{C}.  Then to
traces only @code{bar}, you could match the method name (in any class)
with regular expression
@samp{bar$}, or you could match the program point name with @samp{C\.bar\(}.

@exampleindent 1
@example
java daikon.Chicory --ppt-select-pattern='bar$' ...
java daikon.Chicory --ppt-select-pattern='C\.bar\(' ...
@end example
@exampleindent 4


@item --ppt-omit-pattern=@var{regexp}
Do not produce data trace output for classes/procedures/program points
whose names match the given regular expression.  This
reduces the size of the data trace file and also may make the
instrumented program run faster, since it need not output those variables.

This option works just like @option{--ppt-select-pattern} does, except
that matching program points are excluded, not included.

The @option{--ppt-omit-pattern} argument may be supplied multiple times, in
order to specify multiple omitting criteria.  A program point is omitted
if its fully qualified class, fully qualified procedure name, or
complete program point name exactly matches one of the omitting criteria.
A regular expression matches if it matches any portion of the program
point name.  Note that currently only classes are matched, not each full
program point name.  Thus, either all of a class's methods are traced,
or none of
them are.

Here are examples of how to avoid detecting invariants over various
parts of your program.

@exampleindent 1
@itemize
@item omit a whole package:
@smallexample
java daikon.Chicory '--ppt-omit-pattern=^junit\.' ...
@end smallexample
@smallexample
java daikon.Chicory '--ppt-omit-pattern=^daikon\.util\..*' ...
@end smallexample

@item omit a single class:
@smallexample
java daikon.Chicory '--ppt-omit-pattern=HashSetLinear\$HslIterator' ...
@end smallexample

@item omit a single method:
@smallexample
java daikon.Chicory '--ppt-omit-pattern=StackAr.topAndPop()' ...
@end smallexample

@item omit a single program point:
@smallexample
java daikon.Chicory '--ppt-omit-pattern=StackAr.<init>(int):::EXIT33' ...
@end smallexample

@end itemize
@exampleindent 4

@item --sample-start=@var{sample-cnt}
@cindex sampling of program point executions
When this option is chosen, Chicory will record each program point until
that program point has been executed @var{sample-cnt} times.  Chicory will
then begin sampling.  Sampling starts at 10% and decreases by a factor
of 10 each time another @var{sample-cnt} samples have been recorded.  If
@var{sample-cnt} is 0, then all calls will be recorded.

@item --boot-classes=@var{regex}
Chicory treats classes that match the @var{regex} as boot classes.
Such classes are not instrumented.

@item --instrument-clinit
Causes Chicory to output empty dtrace records when static initializers are
entered and exited.  This is useful for clients that use Chicory to trace
method entry and exit.

@end table


@node          Variables in Chicory output
@subsubsection Variables in Chicory output

@c Perhaps explain why --trace-percent doesn't appear here:  it doesn't
@c affect the .decls structure.

This section lists options that control which variables appear in
Chicory's output.



@table @option


@item --nesting-depth=@var{n}
Depth to which to examine structure components (default 2).
This parameter determines which variables the front end causes to be output at
runtime.  For instance, suppose that a program contained the following
data structures and a method @code{foo}:
@example
class A @{
  int x;
  B b;
@}
class B @{
  int y;
  int z;
@}

class Link @{
  int val;
  Link next;
@}

void foo(A myA, Link myList) @{ ... @}
@end example

Consider what variables would be output at the entry to method @code{foo}:

@itemize @bullet
@item
If depth=0, only the identities (hash codes) of @code{myA} and
@code{myList} would be examined; those variables could be determined to
be equal or not equal to other variables.
@item
If depth=1, then in addition to the above, @code{myA.x}, the identity of
@code{myA.b}, @code{myList.val}, and the identity of @code{myList.next}
would be examined.
@item
If depth=2, then, in addition to the above, also @code{myA.b.y},
@code{myA.b.z}, the identity of @code{myList.next.next}, and
@code{myList.next.val} would be examined.
@end itemize

Values whose value is undefined are not examined.  For instance, if @code{myA}
is @code{null} on a particular execution of a program point, then
@code{myA.b} is not accessed on that execution regardless of the depth
parameter.  That variable appears in the @file{.dtrace} file, but its
value is marked as nonsensical.

@item --omit-var=@var{regex}
@cindex variables, omit
Do not include variables whose name matches the regular expression.  Variables
will be omitted from each program point in which they appear.

@item --std-visibility
@cindex private variables
@cindex variables, private
When this switch is on, Chicory will traverse exactly those fields that are
visible from a given program point.  For instance, only the public
fields of class @code{pack1.B} will be included at a program point for
class @code{pack2.A} whether or not @code{pack1.B} is instrumented.
By default, Chicory outputs all fields in instrumented classes (even
those that would not be accessible in Java code at the given program point)
and outputs no fields from uninstrumented classes (even those that are
accessible).  When you supply
@option{--std-visibility}, consider also supplying @option{--purity-file} to
enrich the set of expressions in Daikon's output.

@item --purity-file=@var{pure-methods-file}
@cindex pure methods
@cindex observer methods, as synonym for pure methods
File @var{pure-methods-file} lists the pure methods (sometimes called
observer methods; one type of observer is @nospellcheck{getter} methods)
 in a Java program.  Pure methods have no externally
side effects, such as setting variables or producing output.  For
example, most implementations of the @code{hashCode()},
@code{toString()}, and @code{equals()} methods are pure.

For each variable, Chicory adds to the trace new @dfn{fields} that
represent invoking each pure method on the variable.  (Currently,
Chicory does so only for pure methods that take no parameters, and
obviously this mechanism is only useful for methods that return a value:
a pure method that returns no value does nothing!)

Here is an example:

@example
class Point @{
  private int x, y;
  public int radiusSquared() @{
    return x*x + y*y;
  @}
@}
@end example

If @code{radiusSquared()} has been specified as pure, then for each point
@var{p}, Chicory will output the variables @code{@var{p}.x},
@code{@var{p}.y}, and @code{@var{p}.radiusSquared()}.  Use of pure
methods can improve the Daikon output, since they represent information
that the programmer considered important but that is not necessarily
stored in a variable.

Invoking a pure method at any time in an application should not change
the application's behavior.  If a non-pure method is listed in a purity
file, then application behavior can change.  Chicory does not verify the
purity of methods listed in the purity file.

The purity file lists a set of methods, one per line.  The format of
each method is given by the Sun JDK API:

@exampleindent 1
@quotation
The string is formatted as the method access modifiers, if any, followed
by the method return type, followed by a space, followed by the class
declaring the method, followed by a period, followed by the method name,
followed by a parenthesized, comma-separated list of the method's formal
parameter types.  If the method throws checked exceptions, the parameter
list is followed by a space, followed by the word throws followed by a
comma-separated list of the thrown exception types.  For example:

@example
public boolean java.lang.Object.equals(java.lang.Object)
@end example

@noindent
The access modifiers are placed in canonical order as specified by "The
Java Language Specification".  This is public, protected or private
first, and then other modifiers in the following order: abstract,
static, final, synchronized native.
@end quotation
@exampleindent 4

By convention, @var{pure-methods-file} has the suffix @file{.pure}.  If
@var{pure-methods-file} is specified as a relative (not absolute) file
name, it is searched for in the configuration directory specified via
@option{--configs=@var{directory}}, or in the current directory if no
configuration directory is specified.

One way to create a @file{.pure} file is to run the Purity Analysis Kit
(@uref{http://jppa.sourceforge.net/}).  If you supply
the @option{--daikon-purity-file} when running the Purity Analysis Kit,
it writes a file that can be supplied to Chicory.

@end table


@node          Chicory miscellaneous options
@subsubsection Chicory miscellaneous options

This section lists all other Chicory options --- that is, all options
that do not control which program points and variables appear in
Chicory's output.

@table @option
@item --help
Print a help message.

@item --debug
Produce debugging information.  For other debugging options, run Chicory
with the @option{--help} option.

@item --dtrace-file=@var{filename}
@cindex DTRACEFILE environment variable
@cindex environment variable DTRACEFILE
@cindex DTRACEAPPEND environment variable
@cindex environment variable DTRACEAPPEND
@cindex trace file name
@cindex dtrace file name
@cindex file name, for dtrace file
Specifies the default name for the trace output (@file{.dtrace}) file.
If this is not specified, then the value of the @env{DTRACEFILE}
environment variable (at the time the instrumented program runs) is
used.  If that environment variable is not used, then the default is
@file{./@var{CLASSNAME}.dtrace}.

If the @env{DTRACEAPPEND} environment
variable is set to any value, the @file{.dtrace} file will be appended to
instead of overwritten.  Compressed data trace files may not be appended
to.  In some cases you may find a single large data trace file more
convenient; in other cases, a collection of smaller data trace files may
give you more control over which subsets of runs to invoke Daikon on.

@item --comparability-file=@var{filename}
This option specifies a declaration file
(see @ref{Declarations,,,developer,Daikon Developer Manual})
that contains comparability information.  This information will be
incorporated in the output of Chicory.  Any variables not included in
the comparability file will have their comparability set so that they
are comparable to all other variables of the same type.
The DynComp tool is a common source for such a
file (see @ref{DynComp for Java} and @ref{DynComp for C/C++}).

@item --output-dir=@var{directory}
Write the @file{.dtrace} trace output file to the specified directory.
The default is the current directory.

@item --config-dir=@var{directory}
Chicory will use this location to search for configuration files.
Currently, this only includes @file{*.pure} files.

@item --daikon
After creating a data trace (@file{.dtrace}) file, run Daikon on it.
To specify arguments to Daikon use the @option{--daikon-args} option.
Also see the
@option{--daikon-online} option.

This option supplies Daikon with a single trace from one execution of
your program.  By contrast to this option (and
@option{--daikon-online}), if you invoke Daikon from the command line,
you can supply Daikon with as many trace files as you wish.

If the program that Chicory is tracing aborts with an error, then Chicory
does not run Daikon, but prints a message such as ``Warning: Did not run
Daikon because target exited with 1 status''.

@item --daikon-online
This option is like @option{--daikon}, except that no @file{.dtrace}
data trace file is produced.  Instead, Chicory sends trace information
over a socket to Daikon, which processes the information incrementally
(``online''), as Chicory produces it.

Just like with the @option{--daikon} option, Daikon is only given a
single trace from one execution of your program.

The Kvasir front end also supports online execution, via use of (normal or
named) Linux pipes (@pxref{Online execution}).

@item --daikon-args=@var{arguments}
Specifies arguments to be passed to Daikon if the @option{--daikon} or
@option{--daikon-online} options are used.

@item --premain=@var{path}
Specifies the absolute pathname to the @file{ChicoryPremain.jar} file.
Chicory requires this jar file in order to execute.  By default Chicory
looks for the jar file in the classpath and in @file{$DAIKONDIR/java}
(where @env{DAIKONDIR} is the
complete installation of Daikon).

Chicory can also use the @file{daikon.jar} file for this purpose.  If it
doesn't find @file{ChicoryPremain.jar} above, it will use @file{daikon.jar}
itself (if a file named @file{daikon.jar} appears in the classpath).  If
the Daikon jar file is not named @file{daikon.jar}, you can use this
switch to specify its name.  For example:
@example
--premain=C:\lib\daikon-5.6.7.jar
@end example

@item --heap-size=@var{max_heap}
Specifies the maximum size, in bytes, of the memory allocation pool for
the target program.  Also applies to Daikon, if the @option{--daikon}
command-line argument is given.
The size is specified in the same manner as the
@option{--Xmx} switch to @command{java}; for example: @option{--heap-size=2048m}.

@end table


@node       Static fields (global variables)
@subsection Static fields (global variables)

@cindex Static fields (global variables) in Java programs

Chicory (Daikon's front end for Java) outputs the values of static
fields in the current class, but not in other classes.  That means that
Daikon cannot report properties over static fields in other classes,
because it never sees their values.  (By contrast, Kvasir
(@pxref{Kvasir}) supplies the values of C/C++ global variables to
Daikon.)

If you need Daikon to include all static variables when processing each
class, then ask the maintainers to add that feature to
Chicory (or work with them to implement the enhancement).  In the
meanwhile, here are two workarounds.

@enumerate
@item
Add a static field whose type is the class containing the fields of
interest.  You don't have to ever assign to the new field.  A
disadvantage of this approach is that it gives you properties over the
global variables as observed by each class (which might be different).

@item
At the beginning and end of each method, add a call to a dummy method
that has access to all the globals (via adding the field mentioned above).
This produces a single formula that is valid for all global variables at
all times.
@end enumerate



@node    DynComp for Java
@section DynComp dynamic comparability (abstract type) analysis for Java

@cindex DynComp, for Java
@cindex abstract types, for Java
@cindex comparability, for Java
@cindex dynamic comparability, for Java

While Daikon can be run using only the Chicory front end, it is highly
recommend that DynComp be run prior to Chicory.
The DynComp dynamic comparability analysis tool performs dynamic type
inference to group variables at each program point into comparability sets
(see @ref{Program point declarations,,,developer,Daikon Developer Manual}
for the file representation of these sets).  All variables in each
comparability set belong to the same ``abstract type'' of data that the
programmer likely intended to represent, which is a richer set of types
than the few basic declared types (e.g., int, float) provided by the
language.

Without comparability information, Daikon attempts to find invariants
over all pairs (and sometimes triples) of variables present at every
program point.  This can lead to two negative consequences: First, it
may take lots of time and memory to infer all of these invariants,
especially when there are many global or derived variables present.
Second, many of those invariants are true but meaningless because they
relate variables which conceptually represent different types (e.g., an
invariant such as @code{winterDays < year} is true but meaningless
because days and years are not comparable).

Consider the example below:

@example
public class Year @{
    public static void main(String[] args) @{
        int year = 2005;
        int winterDays = 58;
        int summerDays = 307;
        compute(year, winterDays, summerDays);
    @}

    public static int compute(int yr, int d1, int d2) @{
        if (0 != yr % 4)
            return d1 + d2;
        else
            return d1 + d2 + 1;
    @}
@}
@end example

The three variables in @code{main()} all have the same Java
representation type, @code{int}, but two of them hold related quantities
(numbers of days), as can be determined by the fact that they interact
when the program adds them, whereas the other contains a conceptually
distinct quantity (a year).  The abstract types ``day'' and ``year'' are
both represented as @code{int}, but DynComp can differentiate them with
its dynamic analysis.  For example, DynComp can infer that
@code{winterDays} and @code{summerDays} are comparable (belong to the
same abstract type) because the program adds their values together
within the compute() function.

Without comparability information, Daikon attempts to find invariants
over all pairs (and sometimes triples) of variables present at every
program point.  This can lead to two negative consequences: First, it
may take lots of time and memory to infer all of these invariants,
especially when there are many global or derived variables present.
Second, many of those invariants are true but meaningless because they
relate variables which conceptually represent different types (e.g., an
invariant such as @code{winterDays < year} is true but meaningless
because days and years are not comparable).

To use DynComp, run your program as you normally would, but replace the
@command{java} command with @command{java daikon.DynComp}.  For instance,
if you usually run
@example
java mypackage.MyClass arg1 arg2 arg3
@end example

@noindent
then instead you would run
@example
java daikon.DynComp mypackage.MyClass arg1 arg2 arg3
@end example

@noindent
This runs your program and creates the file @file{MyClass.decls-DynComp}
in the current directory.  The @file{.decls-DynComp} file may be passed to
Chicory, as described in @ref{Detecting invariants in Java programs}.

@example
java daikon.Chicory --comparability-file=MyClass.decls-DynComp \
     mypackage.MyClass arg1 arg2 arg3
@end example

@noindent
See below for more options.

Here is part of a sample @file{.decls-DynComp} file generated by running DynComp on the example above:

@example
DECLARE
Year.compute(int, int, int):::ENTER
yr
int # isParam=true
int
3
d1
int # isParam=true
int
2
d2
int # isParam=true
int
2

DECLARE
Year.compute(int, int, int):::EXIT11
yr
int # isParam=true
int
3
d1
int # isParam=true
int
2
d2
int # isParam=true
int
2
return
int
int
2
@end example

@noindent
The declaration file format is described in
@ref{Program point declarations,,,developer,Daikon Developer Manual}.

You can
cause DynComp to create two additional representations of the comparability information.

Given the option @option{--comparability-file=@var{filename}},
DynComp outputs comparability sets as sets.  The above @file{.decls-DynComp}
output corresponds to the following comparability-file output:

@exampleindent 1
@example
Daikon Variable sets for Year.compute(int yr, int d1, int d2) enter
  [2] [daikon.chicory.ParameterInfo:d1] [daikon.chicory.ParameterInfo:d2]
  [1] [daikon.chicory.ParameterInfo:yr]
Daikon Variable sets for Year.compute(int yr, int d1, int d2) exit
  [3] [daikon.chicory.ParameterInfo:d1, daikon.chicory.ParameterInfo:
       d2, daikon.chicory.ReturnInfo:return]
  [1] [daikon.chicory.ParameterInfo:yr]
@end example

Given the option @option{--trace-file=@var{filename}},
DynComp outputs comparability sets as trees,
structured such that each variable in the tree has interacted with its
children.  The lack of a parent-child relationship between two variables
in a set does not imply anything about whether they interacted.
The above @file{.decls-DynComp} output corresponds to the following
trace-file output:

@example
Daikon Traced Tree for Year.compute(int yr, int d1, int d2) enter
daikon.chicory.ParameterInfo:d1
--daikon.chicory.ParameterInfo:d2 ()

daikon.chicory.ParameterInfo:yr


Daikon Traced Tree for Year.compute(int yr, int d1, int d2) exit
daikon.chicory.ParameterInfo:d1
--daikon.chicory.ParameterInfo:d2 (Year:compute(), 11)
--daikon.chicory.ReturnInfo:return (Year:compute(), 11)

daikon.chicory.ParameterInfo yr
@end example

@noindent
The file here shows that @code{d1}, @code{d2}, and the return value of
the @code{compute} method are in the same comparability set; this is
correct, as they are all of the abstract type ``days''.  The variable
@code{yr} is in its own comparability set; it has abstract type ``year'',
and so is not comparable to the other variables.  In addition, the structure
of the @code{[d1, d2, return]} set shows that at some point, @code{d1} interacted
with @code{d2}, and that @code{d2} interacted with @code{return}.  The absence of
a @code{d1 -- return} edge does not imply that @code{d1} and @code{return} never
interacted directly.

In addition, non-root nodes in the @file{trace} trees can indicate a list of class names,
method names, and line numbers at which values interacted, resulting in comparability
between the preceding child node and its parent.  In the above example, @code{d1}
interacted with @code{d2} on line 11 of the @code{compute} method of the @code{Year}
class.

Duplicate values in this list represent the results of separate calls to
another method which each of the relevant variables.  For example, if we modify
the sample to use global variables instead of locals and add an additional call
to @code{compute}:

@example
public class Year2 @{
    static int year = 2005;
    static int winterDays = 58;
    static int summerDays = 307;
    static int schoolDays = 180;
    static int breakDays = 185;
    public static void main(String[] args) @{
        compute(year, winterDays, summerDays);
        compute(year, schoolDays, breakDays);
    @}

    public static int compute(int yr, int d1, int d2) @{
        if (0 != yr % 4)
            return d1 + d2;
        else
            return d1 + d2 + 1;
    @}
@}
@end example

@noindent
then for @code{compute} we might see
this output:

@example
DynComp Traced Tree for Year2.compute(int yr, int d1, int d2) exit
daikon.chicory.FieldInfo:Year2.schoolDays
--daikon.chicory.FieldInfo:Year2.breakDays (Year2:compute(), 14)
--daikon.chicory.ParameterInfo:d1 (Year2:compute(), 14)
----daikon.chicory.FieldInfo:Year2.winterDays (Year2:compute(), 14)
------daikon.chicory.FieldInfo:Year2.summerDays (Year2:compute(), 14)
------daikon.chicory.ParameterInfo:d2 (Year2:compute(), 14)
------daikon.chicory.ReturnInfo:return (Year2:compute(), 14)
@end example

Empty lists indicate that no non-assignment interactions occurred in the series of
interactions connecting the two variables.

Elements of these lists are essentially parts of stack traces.  The maximum number
of stack trace levels displayed is set by @option{--trace-line-depth}, which is equal to 1 by default.

For these files, DynComp also has a @option{--abridged-vars} option that replaces text
like @code{daikon.chicory.ParameterInfo:d2} with text like @code{Parameter d2} in the comparability-file
and trace-file.  It writes @code{this} instead of
@code{daikon.chicory.ThisObjInfo:this}; and @code{return} instead of
@code{daikon.chicory.ReturnInfo:return}.  This option is off by default, but can be
turned on with @option{--abridged-vars}.

@menu
* Instrumenting the JDK with DynComp::
* DynComp for Java options::
* Instrumentation of Object methods::
* Troubleshooting DynComp for Java::
* DynComp for Java known bugs::
@end menu

@node       Instrumenting the JDK with DynComp
@subsection Instrumenting the JDK with DynComp

@cindex dcomp_rt.jar file for DynComp
@cindex instrumented JDK, for DynComp
@cindex JDK, instrumented for DynComp

If you did not already do so when installing Daikon
(@pxref{Installing Daikon}), follow the instructions here to build an
instrumented copy of the JDK@.  Use the following command:

@example
make -C $DAIKONDIR/java dcomp_rt.jar
@end example

Make sure the @env{JAVA_HOME} environment variable is set to the directory
containing your JDK@.  This command instruments the classes in the
@file{rt.jar} file of the JDK, and creates a new file,
@file{dcomp_rt.jar}, in the @file{java} directory.

On MacOSX, versions of the JDK prior to 7 were not organized in a manner
similar to the Linux versions.  Current versions of Daikon require JDK 7
(or newer); hence, this is no longer an issue on MacOSX.
The following example is typical for an install of Java 1.7 on MacOSX:

@exampleindent 0
@example
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.7.0_45.jdk/Home
@end example
@exampleindent 4

@noindent
Building @file{dcomp_rt} requires 10-30 minutes to complete and uses 1024 MB of
memory.  Regular progress indicators are printed to standard output.

You can ignore warnings issued during the instrumentation process, so
long as the make target itself completes normally.

If there are any methods in the JDK that DynComp is
unable to instrument, their names will be
printed at the end of the instrumentation process.  This is not a problem unless
your application calls one of these methods (directly or indirectly).
If one of these methods is called, a @samp{NoSuchMethodException} will
be generated when the call is attempted. As of Java 7 runtime version 1.7.0_65
all Java runtime methods are able to be instrumented.

If the instrumented JDK is in a non-standard location, use the
@option{--rt-file} switch to specify its location, or change your classpath
to include it.

One final note: if you update your JDK in any way (such as a OS upgrade),
you will need to rebuild @file{dcomp_rt.jar}.


@node       DynComp for Java options
@subsection DynComp options

DynComp is invoked as follows:
@example
java daikon.DynComp @var{dyncomp-args} @var{classname} @var{args}
@end example

@noindent
where
@example
java @var{classname} @var{args}
@end example

@noindent
is a valid invocation of Java.

This section lists the optional command-line arguments to DynComp, which
appear before the @var{classname} on the DynComp command line.

@table @option

@item --verbose
Print information about the classes being processed.

@item --debug
Dump the instrumented classes to @file{debug/bin}.

@item --debug-dir
The directory in which to dump instrumented class files (only if
@option{--debug} is specified).  Defaults to @file{debug} in the current
working directory.

@item --output-dir=@var{dir}
The directory in which to create output files.  Defaults to the current
working directory.

@item --decl-file=@var{file}
Output filename for @file{.decls} file suitable for input to Daikon.  Defaults to
@file{@var{target_program}.decls-DynComp}.

@item --comparability-file=@var{file}
Output filename for a more easily human-readable file summarizing
comparability sets.  The file is intended primarily for debugging.

@item --trace-file=@var{file}
If specified, write a human-readable file showing some of the interactions
that occurred.  The file is intended primarily for debugging.

@item --trace-line-depth=@var{n}
Controls size of the stack displayed in tracing the interactions that
occurred.  Default behavior is to only display one element in the stack ---
that is, display at most the topmost function on the stack when the
interaction occurred.  This switch has no effect if @option{--trace-file}
is not specified, or is null.

@item --abridged-vars
When this switch is on, DynComp abridges the variables printed in the files
specified by @option{--comparability-@/file} and @option{--trace-@/file}.
For example, DynComp will output
@samp{Field foo} instead of @samp{dyncomp.@/chicory.@/FieldInfo:@/MyClass.foo}.
In particular,
it replaces @samp{dyncomp.@/chicory.@/ReturnInfo:return} with @samp{return} and
@samp{dyncomp.@/chicory.@/This@/Obj@/Info:@/this} with @samp{this}.

@item --ppt-select-pattern=@var{regex}
Only emit program points that match @var{regex}.  Specifically, a
program point is considered to match @var{regex} if the fully qualified
class name, the method name, or the program point name matches
@var{regex}.  The behavior of this switch is the same as in Chicory (see
@ref{Program points in Chicory output}).

This option can be specified multiple times, and may be used in
conjunction with @option{--ppt-omit-pattern}.  If a program point matches
both a select pattern and an omit pattern, it is omitted.

@item --ppt-omit-pattern=@var{regex}
Suppress program points that match @var{regex}.  Specifically, a
program point is considered to match @var{regex} if the fully qualified
class name, the method name, or the program point name matches
@var{regex}.  The behavior of this switch is the same as in Chicory (see
@ref{Program points in Chicory output}).

This option can be specified multiple times, any may be used in
conjunction with @option{--ppt-select-pattern}.  If a program point
matches both a select pattern and an omit pattern, it is omitted.

@item --no-primitives
Don't track Java primitive values (of type @code{boolean}, @code{int},
@code{long}, etc.).  When this switch is on, DynComp only tracks
the comparability of object references; primitive values are
ignored.  Using this switch can greatly improve DynComp's runtime if
you are not interested in primitive values.

@item --rt-file=@var{jdk-jar-file}
Specifies the location of the instrumented JDK (see @ref{Instrumenting
the JDK with DynComp}).  This option is rarely necessary, because
if @option{--rt-file} is not specified, DynComp
will search for a file named @file{dcomp_rt.jar} along the classpath,
and in @file{$DAIKONDIR/java}.  Both this file and the current classpath
are placed on the boot classpath for DynComp's execution.

If the filename is @code{NONE}, then
run DynComp with an uninstrumented JDK, instead of with a
copy of the JDK that has been instrumented with DynComp.
This will improve runtime performance, but will
yield less accurate results.

@item --std-visibility
When this switch is on, DynComp traverses exactly those fields that are
visible from a given program point.  For an example, see @ref{Variables
in Chicory output}.

@item --nesting-depth=@var{n}
Depth to which to examine structure components (default 2).  This
parameter determines which variables the front end causes to be output
at runtime.  For an example, see @ref{Variables in Chicory output}.

@end table


@node       Instrumentation of Object methods
@subsection Instrumentation of Object methods

DynComp is unable to directly instrument methods of the class
@code{Object}, such as @code{clone} and @code{equals}.  DynComp uses a
few tricks, described here in brief, to track comparability in these
methods.

Calls such as @code{o1.equals(o2)} are replaced with calls to a static
method in DynComp, @code{dcomp_equals(o1, o2)}.  This static method
dynamically determines whether or not @code{o1} is an instance of a
class that has been instrumented by DynComp; every such class
implements the interface @code{DCompInstrumented}.  If so, it attempts
to invoke the instrumented version of the @code{equals} method for
@code{o1}.  If not, or if @code{o1} has not overridden the
@code{equals} method from @code{Object}, then no instrumented version
exists, so the uninstrumented version is invoked.

In either case, the references @code{o1} and @code{o2} are considered
to be comparable.  In a future release, we will provide a command-line
switch to customize this behavior.

The @code{clone} method operates in a similar manner, choosing
dynamically to invoke the instrumented method or the uninstrumented
method.  In the case of @code{clone}, the methods are invoked via
reflection.  In either case, the object being cloned and the resulting
clone are made comparable to each other.  Again, we will provide a
switch to customize this behavior in a future release.


@node       Troubleshooting DynComp for Java
@subsection Troubleshooting DynComp for Java

If DynComp crashes the JVM, then the most likely problem is that you are
running with a wrong version of the JDK@.  Re-instrument the JDK as
described in @ref{Instrumenting the JDK with DynComp}.

Examples of errors that you may obtain when using the wrong version of the
JDK include the following:

@example
Error occurred during initialization of VM
java.lang.UnsatisfiedLinkError:
@end example

@example
# A fatal error has been detected by the Java Runtime Environment:
#
#  SIGSEGV
@end example

@c This one has not been verified yet; reinstate it if it is verified.
@c @example
@c A fatal error has been detected by the Java Runtime Environment:
@c #
@c #  EXCEPTION_ACCESS_VIOLATION
@c @end example


@node       DynComp for Java known bugs
@subsection Known bugs and limitations

@itemize
@item
Java reflection finds the original, uninstrumented code.  DynComp will not
observe code that is called reflectively, and so DynComp's output will not
indicate interactions in such code.

This is relevant to frameworks such as JUnit that call code reflectively.
If you want to run tests using JUnit, then explicitly create a Suite that
contains the tests you want to run, rather than annotating methods with
@code{@@Test} and depending on JUnit to find them and call them via reflection.
If you are generating JUnit test suites with
@uref{https://randoop.github.io/randoop/, ,Randoop}, then supply the
@option{--junit-reflection-allowed=false} command-line option to Randoop.
@item
@c The manual should be more specific about how a user can know this is the
@c problem and and what the user should do about it?  Also, what is the
@c underlying problem?
Instrumentation of the @code{clone()} method may fail on particular
invocations within private classes in the JDK@.
@end itemize


@node    Kvasir
@section C/C++ front end Kvasir

@cindex Kvasir (binary front end for C)
@cindex front end for C/C++
@cindex C/C++ front end
@cindex instrumentation, of C/C++ programs

Daikon's front end for C and C++, named Kvasir, executes C and C++
programs and creates
data trace (@file{.dtrace}) files of variables and their values by
examining the operation of the binary at
runtime.  Kvasir is named after the Norse god of knowledge and beet juice.
It is built upon the Fjalar dynamic analysis framework for C and C++ programs
(available at @uref{http://pag.csail.mit.edu/fjalar/}, but already
included in the Daikon distribution).

To use Kvasir, first compile your program using the DWARF-2 debugging
format (e.g., supply the @option{-gdwarf-2} option to @command{gcc}) and
without optimizations (e.g., supply the @option{-O0} option to @command{gcc}).
Also, some versions of @command{gcc} now output position independent code by default.
You must add the @option{-no-pie} option to disable this feature.
Then, prefix your command line by @command{kvasir-dtrace}.  For example,
if you normally run your program with the command
@example
./program -option input.file
@end example

@noindent
then instead use the command
@example
kvasir-dtrace ./program -option input.file
@end example

@noindent
to run your program and create a data trace file
@file{daikon-output/program.dtrace}, which can be fed as input into
Daikon.  You can perform this step multiple times to create multiple
data trace files for Daikon.
You can also run Daikon without creating an intermediate data trace
file; see @ref{Online execution}.

For information about installing Kvasir, see @ref{Installing Kvasir}.
Kvasir only works under Linux running on an x86 or x86-64 processor; for full
details, see @ref{Kvasir limitations}.
For information about how to create an instrumenter for C that works on
non-Linux or non-x86 platforms, see @ref{Instrumenting C
programs,,,developer,Daikon Developer Manual}.

@menu
* Using Kvasir::
* Kvasir options::
* DynComp for C/C++::
* Tracing only part of a program::
* Pointer type disambiguation::
* C++ support::
* Online execution::
* Installing Kvasir::
* Kvasir limitations::
@end menu

@node       Using Kvasir
@subsection Using Kvasir

Before using Kvasir, you must compile your program compile and link your
program normally, with two exceptions:
@itemize
@item
Do not use optimization.  Remove
any optimization flags, such as @option{-O} or @option{-O2},
and any flags that affect calling conventions, such as
@option{-fomit-frame-pointer}.
@item
Include debugging information, by supplying the @option{-g} flag.
The debugging information must be in the DWARF-2 format.
DWARF-2 is the default format for debugging information in @command{gcc} 3 and later, and
otherwise is produced by supplying the @option{-gdwarf-2} command line option.
@item
Kvasir cannot properly process position independent binaries.
You must add the @option{-no-pie} option to disable this feature.
@end itemize

In the second step of using Kvasir, run your program as you normally
would, but prepend the command @command{kvasir-dtrace} to the beginning.
For instance, if you normally run your program with the command
@example
./myprogram -option input.file
@end example

@noindent
just say
@example
kvasir-dtrace ./myprogram -option input.file
@end example

@noindent
As well as running your program (more slowly than usual), this command
also creates a directory @file{daikon-output} in the current
directory containing a @file{program.dtrace} file suitable as input to Daikon.

Kvasir's first argument, the program name, should be given as a
pathname, as shown above.  If you usually just give a program name that
is not in the current directory but is found in your path, you may need
to modify your command to specify a pathname.  For example:
@example
kvasir-dtrace `which myprogram` -option input.file
@end example

@noindent
You may supply options to Kvasir
before the argument that is the name of your program (@pxref{Kvasir options}).


@node       Kvasir options
@subsection Kvasir options

To see a complete list of options, run this command: @command{kvasir-dtrace --help}

Output file format:

@table @option

@item --decls-file=@var{filename}

Write the @file{.decls} file listing the names of functions and
variables (called declarations) to the specified file name.  This forces
Kvasir to generate separate
@file{.decls} and @file{.dtrace} files instead of outputting everything to the
@file{.dtrace} file, which is the default behavior.  If only a @file{.dtrace} file is
created (default behavior), then it contains both variable declarations and a trace of
values.  If separate @file{.decls} and @file{.dtrace} files are created,
then the @file{.decls} file contains declarations and the @file{.dtrace}
file contains the trace of values.

@item --decls-only

Exit after writing the @file{.decls} file; don't run the program or
generate trace information.  Since the @file{.decls} file is the same for
any run of a program, it can be generated once and then reused on later
runs, as long as no new program points are added and each program point
has the same set of variables.

@item --dtrace-file=@var{filename}

Write the @file{.dtrace} trace file to the specified file name.  The default is
@file{daikon-output/@var{programname}.dtrace}, where @var{programname}
is the name of the program.  A filename of @file{-} may be used to
specify the standard output; in this case, the regular standard output
of the program will be redirected back to the terminal (@file{/dev/tty}), to avoid
intermixing it with the trace output.  If the given filename ends in
@file{.gz}, then @option{--dtrace-gzip} is enabled and the
@file{.dtrace} file will be compressed.

@item --dtrace-no-decls

By default, the @file{.dtrace} file contains both a list of variable
declarations followed by a trace of variable values
(@pxref{File formats,,,developer,Daikon Developer Manual}).
If this option is used, then variable declarations are not
outputted in the @file{.dtrace} file.  This option is equivalent to
@option{--decls-file=/dev/null}, except that it runs faster.  This is
useful when you want to generate one copy of the declarations in the
@file{.decls} file using @option{--decls-only}, generate many
@file{.dtrace} files from different program runs, and then feed 1
@file{.decls} and several @file{.dtrace} files into Daikon.

@item --dtrace-append

Append new trace information to the end of an existing @file{.dtrace}
file.  The default is to overwrite a preexisting @file{.dtrace} file.
When this option is used, no declaration information is written because
it is assumed that the existing @file{.dtrace} file already contains all
declarations (Daikon does not accept duplicate declarations).

@item --dtrace-gzip

Compress trace information with the @command{gzip} program before writing
it to the @file{.dtrace} file.  You must have the @command{gzip} program
available.

@item --output-fifo

Create the output @file{.dtrace} file as a FIFO (also
known as a @dfn{named pipe}).  Kvasir will then open first the @file{.decls}
FIFO and then the @file{.dtrace} FIFO, blocking until another program
(such as Daikon) reads from them.  Using FIFO files for the output of Kvasir
avoids the need for large trace files, but FIFO files are not supported by
some file systems, including the Andrew File System (AFS).

@item --program-stdout=@var{filename}
@itemx --program-stderr=@var{filename}

Redirect the standard output (respectively, standard error) stream of the
program being traced to the specified path.  By default, the standard
output and standard error streams will be left pointing to the same
locations specified by the shell, except that if @option{--dtrace-file=-}
is specified, then the default behavior is as if
@option{--program-stdout=/dev/tty} were specified, since mixing the
program's output and Kvasir's trace output is not advisable.
If the same filename is given for both options, the streams will be
interleaved in the same way as if by the @nospellcheck{Bourne} shell construction
@code{2>&1}.

Also, as in the shell, @var{filename} can be an ampersand followed by an
integer, to redirect to a numbered file descriptor.  For instance, to
redirect the program's standard output and error, and Kvasir's standard
error, to a single file, you can say @option{--program-stdout='&2'
--program-stderr='&2' 2>@var{filename}}.

@end table

Selective program point and variable tracing:

@table @option


@item --ppt-list-file=@var{filename}
@itemx --var-list-file=@var{filename}

Trace only the program points (respectively, variables) listed in the
given file.  Other program points (respectively variables) will be
omitted from the @file{.decls} and @file{.dtrace} files.  A convenient
way to produce such files is by editing the output produced by the
@option{--dump-ppt-file} (respectively, @option{--dump-var-file}) option
described below (@pxref{Tracing only part of a program}).

@item --dump-ppt-file=@var{filename}
@itemx --dump-var-file=@var{filename}

Print a list of all the program points (respectively all the variables)
in the program to the specified file.  An edited version of this file can
then be used with the @option{--ppt-list-file} (respectively
@option{--var-list-file}) option
(@pxref{Tracing only part of a program}).
Note: You must use these options with the
@option{--no-dyncomp} option because otherwise, the behavior is undefined.
Running Kvasir with these
options will initialize but not actually execute the target program, so
the dynamic comparability analysis cannot be performed in the first
place.

@item --ignore-globals

Omit any global or static variables from the @file{.decls} and
@file{.dtrace} files.  Leaving these out can significantly improve Kvasir
and Daikon's performance, at the expense of missing properties involving
them.  The default is to generate trace information for
global and static variables.

@item --ignore-static-vars

Omit any static variables but generate trace information for
global variables in the @file{.decls} and @file{.dtrace} files.

@item --all-static-vars

Output all static variables at all program points in the @file{.decls} and
@file{.dtrace} files.  By default, file-static variables are only outputted at
program points for functions that are defined in the same file (compilation unit)
as the
variable, and static variables declared within a particular function are
only outputted at program points for that function.  These heuristics decrease
clutter in the output without greatly reducing precision because functions
have no easy way of modifying variables that are not in-scope, so it is often
not useful to output those variables.  This option turns off these heuristics
and always outputs static variables at all program points.

@end table

Other options affecting the amount of output Kvasir produces:

@table @option

@item --object-ppts
Enables printing of object program points for C/C++ structs and C++
classes. See @ref{Program points} for more information.

@item --flatten-arrays
This option forces the flattening of statically-sized arrays into
separate variables, one for each element.  For example, an array
@code{foo} of size 3 would be flattened into 3 variables: @code{foo[0]},
@code{foo[1]}, @code{foo[2]}.  By default, Kvasir flattens
statically-sized arrays only after it has already exhausted the one
level of sequences that Daikon allows in the @file{.dtrace} output format
(e.g. an array of structs where each struct contains a statically-sized
array).

@item --array-length-limit=@var{N}
Only visit at most the first @var{N} elements of all arrays.  This can
improve performance at the expense of losing coverage; it is often
useful for tracing selected parts of programs that use extremely large
arrays or memory buffers.

@item --output-struct-vars
This option forces Kvasir to output @file{.decls} and @file{.dtrace} entries for
struct variables.  By default, Kvasir ignores struct variables because
there is really no value that can be meaningfully associated with these
variables.  However, some tools require struct variables to be
outputted, so we have included this option.  Struct variables are
denoted by a @samp{# isStruct=true} annotation in their declarations.

@item --nesting-depth=@var{N}

For recursively-defined structures (structs or classes with members that
are structs or classes or pointers to structs or classes of @emph{any} type),
@var{N} (an integer between 0 and 100) specifies approximately how many levels
of pointers to dereference.  This is useful for controlling the output
of complex data structures with many references to other structures.
The default is 2.

@item --struct-depth=@var{N}

For recursively-defined structures (structs or classes with members that
are pointers to the @emph{same} type of struct or class),
@var{N} (an integer between
0 and 100) specifies approximately how many levels of pointers to dereference.
This is useful for controlling the output of linked lists and trees.
The default is 4.  If you are trying to traverse deep into data
structures, try adjusting the @option{--struct-depth} and
@option{--total-depth} options until Kvasir traverses deep enough to
reach the desired variables.

@end table

@anchor{Pointer type disambiguation command-line arguments}
@ref{Pointer type disambiguation}:

@table @option

@item --disambig-file=@var{filename}
Specifies the name of the pointer type disambiguation file
(@pxref{Pointer type disambiguation}).
If this file exists, Kvasir uses it to make decisions about how
to output the referents of pointer variables.  If the file does not exist,
then Kvasir creates it.  This file may then be edited and used on
subsequent runs.  This option initializes but does not fully execute the
target program (unless it is run with the @option{--smart-disambig}
option).

@item --disambig
Tells Kvasir to create or read pointer type disambiguation
(@pxref{Pointer type disambiguation}) with the default filename,
which is @file{@var{myprog}.disambig} in the same
directory as the target program, where @var{myprog} is the name of the
target program.  This is equivalent to
@option{--disambig-file=@file{@var{myprog}.disambig}}.

@item --smart-disambig
This option should be used in addition to either the @option{--disambig}
or @option{--disambig-file} options (it does nothing by itself).  If the
@file{.disambig} file specified by the option does not exist, then Kvasir
executes the target program, observes whether each pointer refers to
either one element or an array of elements, and creates a disambiguation
file that contains suggestions for the disambiguation types of each
pointer variable.  This potentially provides more accuracy than using
either the @option{--disambig} or @option{--disambig-file} options alone,
but at the expense of a longer run time.  (If the @file{.disambig} file already
exists, then this option provides no extra functionality.)

@item --func-disambig-ptrs
By default, Kvasir treats all pointers as arrays when outputting their
contents.  This option forces Kvasir to treat function parameters and
return values that are pointers as pointing to single values.  However,
all pointers nested inside of data structures pointed-to by parameters
and return values are still treated as arrays.  This is useful for
outputting richer data information for functions that pass parameters or
return values via pointers, which happens often in practice.

@item --disambig-ptrs
By default, Kvasir treats all pointers as arrays when outputting their
contents.  This option forces Kvasir to treat all pointers as pointing to
single values.  This is useful when tracing nested structures with lots
of pointer fields which all refer to one element.

@end table

@ref{DynComp for C/C++}:

@table @option

@item --dyncomp

Run Kvasir with the DynComp dynamic
comparability analysis tool to determine which variables have the same
abstract type.  (This is the default behavior for Kvasir and it is not
necessary to specify this option.)
Variable comparability information
improves the performance of Daikon and
improves Daikon's output by filtering out irrelevant invariants.
Because it is not available until the end of execution, comparability
information is always written to a separate @file{.decls} file (in the
format specified in the
@ref{Program point declarations,,,developer,Daikon Developer Manual}),
as if the @option{--decls-file} option had been specified
(@option{--decls-file} can still be used to control the name of the
file).
This file must be provided to Daikon along with the @file{.dtrace}
file.
This option may also be used with @option{--decls-only} to only generate
a @file{.decls} file without a @file{.dtrace}.

Note that if you are running multiple runs (executions) of your
test program and you are certain that the comparability information
will not vary from run to run, you may use @option{--no-dyncomp} on the second and
subsequent runs to reduce the time required to generate the @file{.trace}
file(s).

@item --dyncomp-interactions=all
@item --dyncomp-interactions=units
@item --dyncomp-interactions=comparisons
@item --dyncomp-interactions=none

By default, DynComp considers any binary operation as an interaction
between its two operands. (@option{=all})

You may restrict this such that the only binary operations that
qualify as interactions are comparisons, addition, subtraction.
This ensures that the variables that DynComp groups together into one
set all have the same units (e.g., physics units). (@option{=units})

A tighter restriction is to stipulate that the only binary operations that
qualify as interactions are comparisons between values (e.g., @code{x <=
y} or @code{x != y}). (@option{=comparisons})

Finally, you may specify that no binary operations qualify as
interactions between values.  Thus, DynComp only tracks dataflow. (@option{=none})

@item --dyncomp-approximate-literals

This option applies an approximation for handling literal values which
greatly speeds up the performance of DynComp and drastically lowers its
memory usage, but at the expense of a slight loss in precision of the
generated comparability sets.  If you cannot get DynComp to successfully
run on a large program, even after tweaking @option{--dyncomp-gc-num-tags}, try
turning on this option.

@item --dyncomp-detailed-mode

This option runs a more detailed (but more time- and space-intensive)
algorithm for tracking variable comparability.  It takes O(n^2) time and
space, whereas the default algorithm takes roughly O(n) time and space.
However, it can produce more precise results.  Despite its name, this
mode can be used together with @option{--dyncomp-fast-mode} to run the
more precise algorithm but still use an approximation for handling
literal values.  (This mode is still experimental and not well-tested
yet.)

@item --dyncomp-separate-entry-exit

The default behavior for DynComp is to generate the same comparability
numbers for Daikon variables at each pair of function entrance and exit
program points.  If this option is used, then DynComp keeps track of
comparability separately for function entrances and exits, which can
lead to more accurate results, but sometimes generates output @file{.decls}
files that Daikon cannot accept.

@item --dyncomp-gc-num-tags=@var{N}

By default, DynComp runs a garbage collector for the tag metadata
once after every 10,000,000 tags have
been assigned.  This option tells the garbage collector to run once
after every @var{N} tags have been assigned.  Making the value of
@var{N} larger allows your program to run faster (because the garbage
collector runs less frequently), but may cause your program to run out
of memory as well.  Making the value of @var{N} too small may cause your
program to never terminate if @var{N} is smaller than the total number
of tags that your program uses in steady state.  You will probably need
to experiment with tweaking this value in order to get DynComp to work
properly.

Making the value of @var{N} equal to 0 turns off the garbage collector.
This may reduce your program's execution time; however, it is not
recommended for long program runs, because without the garbage
collector, it will likely run out of memory.

@end table

Debugging:

@table @option

@item --xml-output-file=@var{filename}

Outputs a representation of data structures, functions, and variables in
the target program to an XML file in order to aid in debugging.  These
are all the entities that Kvasir tracks for a particular run of a target
program, so if you do not see an entity in this XML file, then you
should either adjust command-line options or contact us with a bug
report.

@item --with-gdb

This pauses the program's execution in an infinite loop during
initialization.  You can attach a debugger such as @command{gdb} to the
running process by running @command{gdb} on @file{inst/lib/valgrind/x86-linux/fjalar} under
the Kvasir directory and using the @command{attach} command.

@item --kvasir-debug
@itemx --fjalar-debug
@itemx --dyncomp-debug

Enable progress messages meant for debugging problems with Kvasir, Fjalar, or
DynComp.  By default, they are disabled.  This option is intended mainly
for Kvasir's developers.

@item --dyncomp-trace
@itemx --dyncomp-trace-merge
@itemx --dyncomp-print-inc

Enables trace messages to be output to @command{stderr}. These are disabled by
default. These options are intended mainly for DynComp developers.

@c @item --gcc3
@c
@c Experimental option. This option improves Kvasir's support for @command{GCC} 3.x
@c created binaries. This option is fairly untested, but may be useful
@c for anyone attempting to run Kvasir on @command{GCC} 3.x created binaries. We
@c recommend the use of @command{GCC} 4.1 for creating binaries for use
@c with Kvasir. See @ref{Kvasir limitations} for
@c more information.

@end table

@node       DynComp for C/C++
@subsection DynComp dynamic comparability (abstract type) analysis for C/C++

@cindex DynComp, for C/C++
@cindex abstract types, for C/C++
@cindex comparability, for C/C++
@cindex dynamic comparability, for C/C++

By default, Kvasir outputs both a @file{.dtrace} file that contains value
traces, and a @file{.decls} file with variable comparability information
that was produced by the DynComp tool.  You can run Daikon on just the
@file{.dtrace} file without the DynComp variable comparability information,
but doing so is strongly discouraged.

The DynComp dynamic comparability analysis tool
performs dynamic type inference to group variables at each program point
into comparability sets.
(@xref{Program point declarations,,,developer,Daikon Developer Manual},
for the
file representation format of these sets.)  All variables in each
comparability set belong to the same ``abstract type'' of data that the
programmer likely intended to represent, which is a richer set of types
than the few basic declared types (e.g., int, float) provided by the
language.  Consider the example below:

@example
int main() @{
  int year = 2005;
  int winterDays = 58;
  int summerDays = 307;
  compute(year, winterDays, summerDays);
@}

int compute(int yr, int d1, int d2) @{
  if (yr % 4)
    return d1 + d2;
  else
    return d1 + d2 + 1;
@}
@end example

The three variables in @code{main()} all have the same C representation
type, @code{int}, but two of them hold related quantities (numbers of
days), as can be determined by the fact that they interact when the
program adds them, whereas the other contains a conceptually distinct
quantity (a year).  The abstract types ``day'' and ``year'' are both
represented as @code{int}, but DynComp can differentiate them with its
dynamic analysis.  For example, DynComp can infer that @code{winterDays}
and @code{summerDays} are comparable (belong to the same abstract type)
because the program adds their values together within the
@code{compute()} function.

Without comparability information, Daikon attempts to find invariants
over all pairs (and sometimes triples) of variables present at every
program point.  This can lead to two negative consequences: First, it
may take lots of time and memory to infer all of these invariants,
especially when there are many global or derived variables present.
Second, many of those invariants are true but meaningless because they
relate variables which conceptually represent different types (e.g., an
invariant such as @code{winterDays < year} is true but meaningless
because days and years are not comparable).

By default, Kvasir runs with DynComp to
generate a @file{.decls} file with comparability information along with
the usual value trace in the @file{.dtrace} file.  Using
@option{--decls-only} will only generate the @file{.decls} file without
the extra slowdown of writing the @file{.dtrace} file to disk (however,
because DynComp must execute the entire program to perform its analysis,
the only time saved is I/O time).
@c It would be better to cross-reference directly to the DynComp options
@c rather than to the beginning of the "Kvasir options" section, but I
@c don't see how to do that in Texinfo.
Other DynComp options are listed in the @ref{Kvasir options} section.
Running Kvasir with DynComp takes
more memory and longer time than Kvasir without DynComp, but Daikon will
run faster and produce better output.  Furthermore, it is possible to run
DynComp only once to generate a @file{.decls} file with
comparability information, and pass that one file into Daikon along
with many different @file{.dtrace} files generated during subsequent
Kvasir runs without DynComp. You may wish to verify that your @file{.decls}
file information does not vary from run to run if you choose to use
this approach. The @file{.decls-DynComp} files should be identical.

Here is part of the @file{.decls} file generated by running Kvasir with
DynComp on the above example:

@smallexample
ppt ..compute():::ENTER
  ppt-type enter
  variable yr
    var-kind variable
    rep-type int
    dec-type int
    flags is_param
    comparability 1
  variable d1
    var-kind variable
    rep-type int
    dec-type int
    flags is_param
    comparability 2
  variable d2
    var-kind variable
    rep-type int
    dec-type int
    flags is_param
    comparability 2

ppt ..compute():::EXIT0
  ppt-type subexit
  variable yr
    var-kind variable
    rep-type int
    dec-type int
    flags is_param
    comparability 1
  variable d1
    var-kind variable
    rep-type int
    dec-type int
    flags is_param
    comparability 2
  variable d2
    var-kind variable
    rep-type int
    dec-type int
    flags is_param
    comparability 2
  variable return
    var-kind variable
    rep-type int
    dec-type int
    comparability 2
@end smallexample

The abstract type of ``year'' (and its corresponding comparability set) is
represented by the number 1 while the abstract type of ``day'' is
represented by the number 2.  DynComp places two variables in the same
comparability set when their values interact via program operations such
as arithmetic or assignment.  Because the parameters @code{d1} and
@code{d2} were added together, DynComp inferred that those variables
were somehow related and put them in the same comparability set.  The
return value is also related to @code{d1} and @code{d2} because it is
the result of the addition operation.  Notice that @code{yr} never
interacts with any other variables, so DynComp places it into its own
comparability set.  With this comparability information, Daikon will
never attempt to find invariants between @code{yr} and
@code{d1}/@code{d2}, which both saves time and memory and eliminates
meaningless invariants (the savings are minuscule in this trivial
example, but they can be rather dramatic in larger examples).

@node       Tracing only part of a program
@subsection Tracing only part of a program

When Kvasir is run on a target program of significant size, often times
too much output is generated, which causes an enormous performance
slowdown of both Kvasir outputting the trace file and also Daikon trying
to process the trace file.  It is often desirable to only trace a
specific portion of the target program, program points and variables
that are of interest for a particular invariant detection application.
For instance, one may only be interested in tracking changes in a
particular global data structure during calls to a specific set of
functions (program points), and thus have no need for information about
any other program points or variables in the trace file.  The
@option{--ppt-list-file} and @option{--var-list-file} options can be
used to achieve such selective tracing.

The program point list file (abbreviated as @file{ppt-list-file})
consists of a newline-separated list of names of functions that the
user wants Kvasir to trace.  Every name corresponds to both the entrance
(@code{:::ENTER}) and exit (@code{:::EXIT}) program points for that function
and is printed out in the exact same format that Kvasir
uses for that function in the trace file. (@xref{Using Kvasir},
for the program point naming scheme.)  Here is an
example of a @file{ppt-list-file}:

@example
FunctionNamesTest.cpp.staticFoo(int, int)
..firstFileFunction(int)
..main()
second_file.cpp.staticFoo(int, int)
..secondFileFunction()
@end example

It is very important to follow this format in the @file{ppt-list-file}
because Kvasir performs string comparisons to determine which program
points to trace.  Thus, it is often easier to have Kvasir generate a
@file{ppt-list-file} file that contains a list of all program points in a
target program by using the @option{--dump-ppt-file} option, and then
either comment out (by using the @samp{#} comment character at the
beginning of the line) or delete lines in that file for program points
not to be traced or create a new @file{ppt-list-file} using the names in
the Kvasir-generated file.  This prevents typos and the tedium of
manually typing up program point names.  In fact, the @file{ppt-list-file}
presented in the above example was generated from a C++ test program named
@code{FunctionNamesTest} by using the following command:

@example
kvasir-dtrace --dump-ppt-file=FunctionNamesTest.ppts \
              ./FunctionNamesTest
@end example

@noindent
That file represents all the program points that Kvasir would
normally trace.  If the user wanted to only trace the @code{main()}
function, he could comment out all other lines by placing a single
@samp{#} character at the beginning of each line to be commented out,
as demonstrated here:

@example
#FunctionNamesTest.cpp.staticFoo(int, int)
#..firstFileFunction(int)
..main()
#second_file.cpp.staticFoo(int, int)
#..secondFileFunction()
@end example

@noindent
When running Kvasir with the @option{--ppt-list-file} option using this
as the @file{ppt-list-file}, Kvasir only stops the execution of the target program at the
entrance and exit of @code{main()} in order to output values to the
@file{.dtrace} file.  In order to reduce the file size, when running Kvasir
with the @option{--ppt-list-file} option, the @file{.decls} file only contains
program point declarations for those listed in the @file{ppt-list-file}
(@code{..main():::ENTER} and @code{..main():::EXIT} in this case) because
no other declarations are necessary.

The variable list file (abbreviated as @file{var-list-file}) contains
all of the variables that the user wants Kvasir to output.  There is one
section for global variables and a section for variables associated with
each function (formal parameters and return values).  Again, the best way to
create a @file{var-list-file} is to have Kvasir generate a file with all
variables using the @option{--dump-var-file} option and then modifying
that file for one's particular needs by either deleting or
commenting out lines (again using the @samp{#} comment character).  For example,
executing

@example
kvasir-dtrace --dump-var-file=FunctionNamesTest.vars \
              ./FunctionNamesTest
@end example

@noindent
will generate the following @file{var-list-file} named
@code{FunctionNamesTest.vars}:

@example
----SECTION----
globals
/globalIntArray
/globalIntArray[]
/anotherGlobalIntArray
/anotherGlobalIntArray[]


----SECTION----
FunctionNamesTest.cpp.staticFoo()
x
y


----SECTION----
..firstFileFunction(int)
blah


----SECTION----
..main()
argc
argv
argv[]
return


----SECTION----
second_file.cpp.staticFoo()
x
y


----SECTION----
..secondFileFunction()
@end example

The file format is straightforward.  Each section is marked by a
special string @samp{----SECTION----} on a line by itself followed
immediately by a line that either denotes the program point name
(formatted like how it appears in the @file{.decls} and @file{.dtrace} files) or the
special string @samp{globals}.  This is followed by a
newline-delimited list of all variables to be outputted for that
particular program point.  Global variables listed in the
@code{globals} section are outputted for all program points. Additional global
variables to be outputted for a particular program point can be specified
in the corresponding section entry. For clarity, one or more blank lines
should separate neighboring sections, although the @samp{----SECTION----}
string literal on a line by itself is the only required delimiter.
If an entire section is missing, then no variables for that program point
(or no global variables, if it is the special globals section) are traced.

The variables listed in this file are written exactly as they appear in
the @file{.decls} and @file{.dtrace} file. (@xref{Using Kvasir},
for the variable naming scheme.)  In the program that generated the
output for the above example, @code{int*
globalIntArray} is a global integer pointer variable.  For that
variable, Kvasir generates two Daikon variables: @code{/globalIntArray}
to represent the hashcode pointer value, and @code{/globalIntArray[]} to
represent the array of integers referred-to by that pointer.  The
latter is a derived-variable that can be thought of as the child of
@code{/globalIntArray}.  If the entry for @code{/globalIntArray} is
commented-out or missing, then Kvasir will not output any values for
@code{/globalIntArray} or for any of its children, which in this case is
@code{/globalIntArray[]}.  If a struct or struct pointer variable is
commented-out or missing, then none of its members are traced.  Thus, a
general rule about variable entries in the @file{var-list-file} is that
if a parent variable is not present, then neither it nor its children
are traced.

@example

record
record->entries[1]
record->entries[1]->list
record->entries[1]->list->head
record->entries[1]->list->head->magic

@end example

For example, if you wanted to trace the value of the @code{magic} field
nested deep within several layers of structs and arrays, it would not be
enough to merely list this variable in the @file{var-list-file}.  You
would need to list all variables that are the parents of this one, as
indicated by their names.  This can be easily accomplished by creating a
file with @option{--dump-var-file} and cutting out variable entries,
taking care to not cut out entries that are the parents of entries that
you want to trace.

In order to limit both the number of program points traced as well as
the variables traced at those program points, the user can run Kvasir
with both the @option{--ppt-list-file} and @option{--var-list-file}
options with the appropriate @file{ppt-list-file} and
@file{var-list-file}, respectively.  The @file{var-list-file} only needs
to contain a section for global variables and sections for all program
points to be traced because variable listings for program points not to
be traced are irrelevant (their presence in the @file{var-list-file}
does not affect correctness but does cause an unnecessary
performance and memory inefficiency).

If the @option{--dump-var-file} option is used in conjunction with the
@option{--ppt-list-file} option, then the only sections generated in the
@file{var-list-file} will be the global section and sections for all
program points explicitly mentioned in the @file{ppt-list-file}.  This
is helpful for generating a smaller @file{var-list-file} for use with an
already-existent @file{ppt-list-file}.

@node       Pointer type disambiguation
@subsection Pointer type disambiguation

@cindex pointer type disambiguation
@cindex disambiguation of pointer types
@cindex array type disambiguation
@cindex disambiguation of array types

Kvasir permits users (or external analyses) to specify whether pointers
refer to arrays or to single values, and optionally, to specify the type
of a pointer (@pxref{Pointer type coercion}).  For example, in
@example
void sum(int* array, int* result) @{ ... @}  // definition of "sum"
...
int a[40];
int total;
...
sum(a, &total);        // use of "sum"
@end example

@noindent
the first pointer parameter refers to an array while the second refers to
a single value.  Kvasir (and Daikon) should treat these values
differently.  For instance, @code{*array} is better printed as @code{array[]},
an array of integers, and @code{result[]} isn't a sensible array
at all, even though in C @code{result[0]} is semantically identical to
@code{*result}.
By default, Kvasir treats all pointers as referencing arrays.  For
instance, it would print @code{result[]} rather than @code{result[0]}
and would indicate that the length of array @code{result[]} is always 1.
In order to improve the formatting of Daikon's output (and to speed it
up), you can indicate to Kvasir that certain pointers refer to single
elements rather than to arrays.
For an example, see @ref{Pointer type disambiguation example}.
For a list of command-line options that are related to pointer type
disambiguation, see @ref{Pointer type disambiguation command-line arguments}.

Information about whether each pointer refers to an array or a single
element can be specified in a @dfn{.disambig file} that resides in the
same directory as the target program (by default).  The @option{--disambig}
option instructs Kvasir to read this file if it exists.  (If it does not exist,
Kvasir produces the file automatically and, if invoked along with the
@option{--smart-disambig} option, heuristically infers whether each
pointer variable refers to single or multiple elements.  Thus, users can
edit this file for use on subsequent runs rather than having to create it
from scratch.)  The @file{.disambig} file lists all the program points and user-defined
types, and under each, lists certain types of variables along with their
custom disambiguation types as shown below.
The list of disambiguation options is:

@enumerate
@item
For variables of type @code{char} and @code{unsigned char}:
@enumerate
@item
@verb{|'I'|}: an integer, signed for @code{char} and unsigned for @code{unsigned char}. (Default)
@item
@verb{|'C'|}: a single character, output as a string.
@end enumerate
@item
For pointers to (or arrays of) @code{char} and @code{unsigned char}:
@enumerate
@item
@verb{|'S'|}: a string, possibly zero-terminated. (Default)
@item
@verb{|'C'|}: a single character, output as a string.
@item
@verb{|'A'|}: an array of integers.
@item
@verb{|'P'|}: a single integer.
@end enumerate
@item
For pointers to (or arrays of) all other variable types (if invoked
along with @option{--smart-disambig}, Kvasir automatically infers a
default @verb{|'A'|} or @verb{|'P'|} for each variable during the generation
of a @file{.disambig} file):
@enumerate
@item
@verb{|'A'|}: an array.  (Default) (For an array of structs, an array will
be output for each scalar field of the struct.  Aggregate children
(arrays, other structs) will not be output.)
@item
@verb{|'P'|}: a pointer to a single element.  (For a pointer to a struct, each
field will be output as a single instance, and child aggregate types
will be output recursively.  This extra information obtained from struct
pointers is a powerful consequence of pointer type disambiguation.  This
will be the default if the @option{--disambig-ptrs} option is used.)
@end enumerate
@end enumerate

The @file{.disambig} file that Kvasir creates contains a section for each
function, which can be used to disambiguate parameter variables visible
at that function's entrance program point and parameter and return
value variables visible at that function's exit program point.  It also contains
a section for every user-defined
struct/class, which can be used to disambiguate member variables of
that struct/class.  Disambiguation information entered here will apply to all
instances of a struct/class of that type, at all program points.
There is also a section called ``globals'', which disambiguates global
variables which are output at every program point.  The entries in the
@file{.disambig} file may appear in any order, and whole entries or individual
variables within a section may be omitted.  In this case, Kvasir will
retain their default values.


@menu
* Pointer type coercion::
* Pointer type disambiguation example::
* Using pointer type disambiguation with partial program tracing::
@end menu

@node          Pointer type coercion
@subsubsection Pointer type coercion

In addition to specifying whether a particular pointer refers to one
element or to an array of elements, the user can also specify what type
of data a pointer refers to.  This type coercion acts like an explicit
type cast in C, except that it only works on struct/class types and not
on primitive types.  This feature is useful for traversing inside of
data structures with generic @code{void*} pointer fields.  Another use
is to cast a pointer from one that refers to a ``super class'' to one that
refers to a ``sub class''.  This structural equivalence pattern is often
found in C programs that emulate object orientation.  To coerce a
pointer to a particular type, simply write the name of the struct type
after the disambiguation letter (e.g., A, P, S, C, I) in the
@file{.disambig} file:

@example
----SECTION----
function: ..view_foo_and_bar()
f
P foo
b
P bar
@end example

@noindent
Without the type coercion, Kvasir cannot print out anything except for a
hashcode for the two @code{void*} parameters of this function:

@example
void view_foo_and_bar(void* f, void* b);
@end example

@noindent
With type coercion, though, Kvasir treats @code{f} as a @code{foo*} and
@code{b} as @code{bar*} and can traverse inside of them.  Of course, if
those are not the true runtime types of the variables, then Kvasir's
output will be meaningless.

Due to the use of @code{typedefs}, there may be more than one name for a
particular struct type.  The exact name that you need to write in the
@file{.disambig} file is the one that appears in that file after the
@code{usertype} prefix.  Note that if a struct does not have any pointer
fields, then there will be no @code{usertype} section for it in the
@file{.disambig} file.  In that case, try different names for the struct
if necessary until Kvasir accepts the name (names are all one word long;
you will never have to write @code{struct foo}).  There should only be
at most a few choices to make.  If the coercion if successful, Kvasir
prints out a message in the following form while it is processing the
@file{.disambig} file:

@example
.disambig: Coerced variable f into type 'foo'
.disambig: Coerced variable b into type 'bar'
@end example

One more caveat about type coercion is that you can currently only
coerce pointers into types that at least one variable in the program
(e.g., globals, function parameters, struct fields) belongs to.  It is
not enough to merely declare a struct type in your source code; you must
have a variable of that type somewhere in your program.  This is a
limitation of the current implementation, but it should not matter most
of the time because programs rarely have struct declarations with no
variables that belong to that type.  If you encounter this problem, you
can simply create a global variable of a certain type to make type
coercion work.

@node          Pointer type disambiguation example
@subsubsection Pointer type disambiguation example

This example demonstrates the power of pointer type disambiguation in creating
more accurate Daikon output.  Consider this file:

@smallexample
struct record @{
  char* name;     // Initialize to: "Daikon User"
  int numbers[5]; // Initialize to: @{5, 4, 3, 2, 1@}
@};

void foo(struct record* bar) @{
  int i;
  for (i = 0; i < 5; i++) @{
    bar->numbers[i] = (5 - i);
  @}
@}

int main() @{
  char* myName = "Daikon User";
  struct record baz;
  baz.name = myName;
  foo(&baz);
@}
@end smallexample

@noindent
In @code{foo()}, @code{bar} is a pointer to a @code{record} struct.  By inspection, it is
evident that in this program, @code{bar} only refers to one element: @code{&baz}
within @code{main}.  However, by default, Kvasir assumes that @code{bar} is an
array of @code{record} structs since a C pointer contains no information about
how many elements it refers to.  Because Kvasir must output @code{bar} as an
array and @w{@code{bar->numbers}} is an array of integers, it ``flattens''
@w{@code{bar->numbers}} into 5 separate arrays named @w{@code{bar->numbers[0]}}
through @w{@code{bar->numbers[4]}}
and creates fairly verbose output.  This is a direct
consequence of the fact that Daikon can only handle one layer of sequences
(it cannot handle arrays within arrays, i.e., multidimensional arrays).

Here is part of the Daikon output for this program:

@smallexample
======================================================================
..foo():::ENTER
bar has only one value
bar[].name == [Daikon User]
bar[].name elements == "Daikon User"
======================================================================
..foo():::EXIT
size(bar[]).numbers[0] == size(bar[]).numbers[0][0]
size(bar[]).numbers[0] == size(bar[]).numbers[1]
size(bar[]).numbers[0] == size(bar[]).numbers[1][0]
size(bar[]).numbers[0] == size(bar[]).numbers[2]
size(bar[]).numbers[0] == size(bar[]).numbers[2][0]
size(bar[]).numbers[0] == size(bar[]).numbers[3]
size(bar[]).numbers[0] == size(bar[]).numbers[3][0]
size(bar[]).numbers[0] == size(bar[]).numbers[4]
size(bar[]).numbers[0] == size(bar[]).numbers[4][0]
bar[].name == [Daikon User]
bar[].name elements == "Daikon User"
bar[].numbers[0] contains no nulls and has only one value, of length 1
bar[].numbers[0] elements has only one value
bar[].numbers[0][0] == [5]
bar[].numbers[0][0] elements == 5
bar[].numbers[1] contains no nulls and has only one value, of length 1
bar[].numbers[1] elements has only one value
bar[].numbers[1][0] == [4]
bar[].numbers[1][0] elements == 4
bar[].numbers[2] contains no nulls and has only one value, of length 1
bar[].numbers[2] elements has only one value
bar[].numbers[2][0] == [3]
bar[].numbers[2][0] elements == 3
bar[].numbers[3] contains no nulls and has only one value, of length 1
bar[].numbers[3] elements has only one value
bar[].numbers[3][0] == [2]
bar[].numbers[3][0] elements == 2
bar[].numbers[4] contains no nulls and has only one value, of length 1
bar[].numbers[4] elements has only one value
bar[].numbers[4][0] == [1]
bar[].numbers[4][0] elements == 1
size(bar[]).numbers[0] == 1
bar[].numbers[4][0] elements == size(bar[]).numbers[0]
size(bar[]).numbers[0] in bar[].numbers[4][0]
@end smallexample

@noindent
This is a bit verbose due to the fact that Kvasir treats @code{bar} like an array
by default when it actually only points to one element.  However, by running
Kvasir with the @option{--disambig} option, we create the
@file{@var{myprog}.disambig} file, which we can then edit and feed back to
Kvasir to change how the pointer is treated.  (We run Kvasir twice on the same
program, but we edit the @file{.disambig} file in between the runs.)
@example
kvasir-dtrace @var{...options...} --disambig --smart-disambig @var{myprog}
@end example

@noindent
This creates the @file{@var{myprog}.disambig} file.  It contains, at the top:

@smallexample
----SECTION----
function: ..foo()
bar
P
@end smallexample

@noindent
This means that at the program points corresponding to the entry and
exit of @code{foo()}, the variable @code{bar} is treated as a
@samp{Pointer} type.
Since we have used the @option{--smart-disambig} option,
Kvasir automatically inferred Pointer instead of Array for @code{bar}
because it observed that @code{bar} only pointed to one element during the
execution of the target program which generated the @file{.disambig} file.
This heuristic allows users to use
@file{.disambig} files more effectively with less manual editing.
Without @option{--smart-disambig}, Kvasir does not execute the program
to make such inferences, which allows @file{.disambig} files to be generated
faster, but leaves the default disambiguation types for all entries (in
this case, @code{bar} would have the default array type of
@code{'A'}).

Then, running Kvasir again with the @option{--disambig}
option causes Kvasir to open the existing
@file{@var{myprog}.disambig} file, read the definitions, and alter
the output accordingly:
@example
kvasir-dtrace @var{...options...} --disambig @var{myprog}
@end example

@noindent
This tells Kvasir to output @code{bar} as a @samp{Pointer} to a single
element, which in turn causes Daikon to generate a much more concise
set of invariants.  Notice that @w{@code{bar->numbers}} no longer has to be
``flattened'' because @code{bar} is now a pointer to one struct, so
Daikon can recognize @w{@code{bar->numbers}} as a single-dimensional
array (Daikon uses a Java-like syntax, replacing the arrow @samp{->} symbol
with a dot, so it actually outputs @code{bar.numbers}).

@smallexample
======================================================================
..foo():::ENTER
bar has only one value
bar.name == "Daikon User"
======================================================================
..foo():::EXIT
bar.name == "Daikon User"
bar.numbers has only one value
bar.numbers[] == [5, 4, 3, 2, 1]
size(bar.numbers[]) == 5
bar.name == orig(bar.name)
size(bar.numbers[]) in bar.numbers[]
size(bar.numbers[])-1 in bar.numbers[]
@end smallexample


@node          Using pointer type disambiguation with partial program tracing
@subsubsection Using pointer type disambiguation with partial program tracing

It is possible to use pointer type disambiguation while only tracing
selected program points and/or variables in a target program, combining
the functionality described in the @ref{Pointer type disambiguation} and
@ref{Tracing only part of a program} sections.  This section describes
the interaction of the @file{ppt-list-file}, @file{var-list-file}, and
@file{.disambig} files.

The interaction between selective program point tracing (via
the @file{ppt-list-file}) and pointer type disambiguation is fairly
straightforward:  If the user creates a @file{.disambig} file while running
Kvasir with a @file{ppt-list-file} that only specifies certain program
points, the generated @file{.disambig} file will only contain sections for
those program points (as well as the global section and sections for
each struct type).  If the user reads in a @file{.disambig} file while running
Kvasir with a @file{ppt-list-file}, then disambiguation information is
applied for all variables at the program points to be traced.  This can
be much faster and generate a much smaller disambiguation file, one that
only contains information about the program points of interest.

The interaction between selective variable tracing (via the
@file{var-list-file}) and pointer type disambiguation is a bit more
complicated.  This is because the @file{var-list-file} lists variables
as they appear in the @file{.decls} and @file{.dtrace} files, but using a @file{.disambig}
file can actually change the way that variable names are printed out in
the @file{.decls} and @file{.dtrace} files.  For example, consider the test program
from the @ref{Pointer type disambiguation example}.  The @code{struct
record* bar} parameter of @code{foo()} is treated like an array by
default.  Hence, the @file{.decls}, @file{.dtrace}, and @file{var-list-file} will list
the following variables derived from this parameter:

@example
----SECTION----
..foo()
bar
bar[].name
bar[].numbers[0]
bar[].numbers[0][0]
bar[].numbers[1]
bar[].numbers[1][0]
bar[].numbers[2]
bar[].numbers[2][0]
bar[].numbers[3]
bar[].numbers[3][0]
bar[].numbers[4]
bar[].numbers[4][0]
@end example

@noindent
However, if we use a disambiguation file to denote @code{bar} as a
pointer to a single element, then the @file{.decls} and @file{.dtrace} files will
instead list the following variables:

@example
----SECTION----
..foo()
bar
bar->name
bar->numbers
bar->numbers[]
@end example

@noindent
Notice how the latter variable list is more compact and reflects the
fact that @code{bar} is a pointer to a single struct.  Thus, the
flattening of the @code{numbers[5]} static array member variable is no
longer necessary (it was necessary without disambiguation because Daikon
does not support nested arrays of arrays, which can occur if @code{bar}
were itself an array since @code{numbers[5]} is already an array).

Notice that, with the exception of the base variable @code{bar}, all
other variable names differ when running without and with
disambiguation.  Thus, if you used a @file{var-list-file} generated on a
run without the disambiguation information while running Kvasir with the
disambiguation information, the names will not match up at all, and you
will not get the proper selective variable tracing behavior.

The suggested way to use selective variable tracing with pointer type
disambiguation is as follows:

@enumerate
@item First create the proper @file{.disambig} file by using either
@option{--disambig} or @option{--disambig-file}.
You can use @option{--ppt-list-file} as well to only create the
@file{.disambig} file for certain program points, but do NOT use
@option{--var-list-file} to try to create a @file{.disambig} only for certain
variables; this feature does not work yet.
Modify the variable
entries in the Kvasir-generated @file{.disambig} file to suit your needs.
@item Now create a @file{var-list-file} by using
@option{--dump-var-file} while running Kvasir with the @file{.disambig} file
that you have just created.  This ensures that the variables listed in
@file{var-list-file} will have the proper names for use with that
particular @file{.disambig} file.  Modify the Kvasir-generated
@file{var-list-file} to suit your needs.
@item Finally, run Kvasir with the @option{--var-list-file} option using
the @file{var-list-file} that you have just created and either the
@option{--disambig} or @option{--disambig-file} option with the proper
@file{.disambig} file.  This will perform the desired function: selective
variable tracing along with disambiguation for all of the traced
variables.
@end enumerate

For maximum control of the output, you can use selective program point
tracing, variable tracing, and disambiguation together all at once.

@node       C++ support
@subsection C++ support

Kvasir supports C++, but Kvasir has been tested more on C programs than
on C++ programs, so Kvasir's C++ support is not as mature as its C support.
Here is a partial list of C++ features that Kvasir currently supports:

@itemize @bullet

@item
Class member functions are traced just like regular functions, except
that their first parameter is a pointer (called @code{this}) to a single
instance of the class.  They are printed with the class name as the
prefix, followed by a period and then the full function signature.  For
example, a @code{push()} function of a @code{Stack} class might be named
@code{Stack.push(char*)}.

@item
OBJECT program points (@pxref{Program points}) are printed out in the
@file{.decls} file for each class with at least 1 member variable and 1 member
function.  No extra information besides member function traces are
required in the @file{.dtrace} file; Daikon can link together class and
function names to determine when a particular function is a member
function and generate object invariants for that class by observing the
values of the @code{this} parameter.

@item
Static member variables are currently treated just like global
variables, because they actually have static global locations.  Another
(not yet implemented) possibility is to only print them at program
points of member functions belonging to the respective variable's own
class.

@item
Inheritance is handled correctly because whenever Kvasir traverses
inside of a class to print out its member variables, it also recursively
traverses inside all superclasses (and inside their superclasses,
etc...) to print out inherited member variables.  The superclass class
names are appended onto the variable names to make them unique.  For
example, if @code{this} is an instance of a class that inherits from
another class called @code{fooClass} which has a member variable
@code{fooVar}, then Kvasir prints out @code{fooVar} as
@code{this->fooClass.fooVar}.  This correctly handles the case of
multiple inheritance as well as several layers of inheritance.  Thus,
object invariants capture properties of a class's own member variables
as well as those of its superclasses' member variables.

@item
Inheritance-based polymorphism is handled correctly without any extra
effort because when a function entrance or exit is encountered at run
time, the version that is called has already been resolved.

@item
Overloaded functions are handled correctly because Kvasir prints out the
full function signature as its name in order to prevent conflicts.  For
example, two overloaded versions of a function @code{foo()} will be
disambiguated by their signatures, such as @code{foo(int, int)} and
@code{foo(double, double)}.

@item
Kvasir handles functions that pass parameters by reference as well as
those that pass parameters by value.

@end itemize

One current C++ limitation is that Kvasir cannot print out the contents
of classes which are defined in external libraries rather than in the
user's program (e.g., it can properly output a C-string represented as
@code{char*} but not the contents of the C++ @code{string} class).  If
further support for specific C++ features are important to you, please
send email to @email{daikon-developers@@googlegroups.com}, so that we
can increase its priority on our to-do list.

@node       Online execution
@subsection Online execution

@cindex online execution, for C programs
@cindex on-the-fly execution, for C programs

The term @dfn{online execution} refers to running Daikon at the same time
as the target program, without writing any information to a file.  This
can avoid some I/O overhead, prevent filling up your disk with
files, and in the future Daikon may be able to produce partial results
as the target program is executing.  A limitation of online execution is
that, unless FIFO files, or named pipes (@pxref{Online execution with DynComp for C/C++})
are used, it runs Daikon over only a single execution, as opposed to
generalizing over multiple executions as can be done when writing to files
and supplying all the files to Daikon.
The Chicory front end for Java also supports online execution, via its
@option{--daikon-online} option (@pxref{Chicory miscellaneous options}).

@cindex pipe, as data trace file

To use regular pipes in lieu of a disk file, simply use @file{-} as the
name of the @file{.dtrace} file, and run the target program and Daikon
in a Linux pipeline.
When the @option{--dtrace-file=-} option is used to redirect
the @file{dtrace} output to @command{stdout}, the target program's @command{stdout} is redirected
to the terminal (@file{/dev/tty}) so that it does not intermix with the
@file{dtrace} output.

@example
kvasir-dtrace --dtrace-file=- ./bzip2 --help | $DAIKON -
@end example

@noindent
Of course, you could also replace @option{--help} with @option{-vv1
file.txt} to compress a text file (but start with a small one first).

@noindent
(This example assumes that you have compiled the @file{bzip2} example (in
@file{$DAIKONDIR/@/examples/@/c-examples/@/bzip2} of the distribution) by
saying @command{gcc -gdwarf-2 -no-pie bzip2.c -o bzip2}, and that
@env{$DAIKON} stands for the command that invokes Daikon, for
instance @command{java -Xmx512m daikon.Daikon --config_option
daikon.@/derive.@/Derivation.@/disable_derived_variables=true}.)

@cindex named pipe, as data trace file
@cindex FIFO, as data trace file

Instead of a regular pipe, you can use a named pipe, also known as a
FIFO, which is a special kind of file supported by most Linux-compatible
systems.  When one process tries to open a FIFO
for reading, it blocks, waiting for another process to open it for
writing (or vice-versa).  When both a reader and a writer are ready, the
FIFO connects the reader to the writer like a regular Linux pipe.

The @option{--output-fifo} option causes Kvasir to create its output
@file{.dtrace} file as a named pipe.  When Kvasir is
run with this option, Daikon needs to be run at the same time to read
from the FIFO, such as from another terminal or using the shell's
@samp{&} operator.

For instance, the following two commands have the same effect as the
pipeline above that used ordinary pipes.  The FIFO is named
@file{bzip2.dtrace}.

@example
kvasir-dtrace --output-fifo ./bzip2 --help &
$DAIKON bzip2.dtrace
@end example

@noindent
The two commands (before and after the ampersand) could also be run in
two different terminals.


@menu
* Online execution with DynComp for C/C++::
@end menu

@node          Online execution with DynComp for C/C++
@subsubsection Online execution with DynComp for C/C++

When running Kvasir with DynComp (the default),
Kvasir generates the @file{.decls} file after it generates the @file{.dtrace}
file, so it is not possible to perform online execution using one run.
The recommended way to perform online execution with DynComp is to run
it once and only generate a @file{.decls} file with comparability information,
then run Kvasir again without DynComp and pipe the @file{.dtrace} data directly
into Daikon while using the @file{.decls} file generated from the previous run:

@example
kvasir-dtrace --decls-only ./foo
@end example

@noindent
This should generate a @file{.decls} file with comparability information
named @file{daikon-@/output/@/foo.decls}.

@example
kvasir-dtrace --no-dyncomp --dtrace-no-decls --dtrace-file=- \
    ./foo | java daikon.Daikon daikon-output/foo.decls -
@end example

When you run Kvasir the second time, you don't need to run DynComp
again since you are only interested in the @file{.dtrace} file.  Notice that
the @file{.dtrace} output
is directed to standard out (@option{--dtrace-file=-}) and does not
contain any declarations (@option{--dtrace-no-decls}) because the @file{.decls}
file already contains the declarations.  You can simply
pipe that @file{.dtrace} output out to Daikon, which is invoked using the
@file{.decls} file (with comparability information) generated during your
previous run.

@node       Installing Kvasir
@subsection Installing Kvasir

@cindex installing Kvasir
@cindex Kvasir installation

@c Kvasir is the recommended C/C++ front end for use on Linux/x86.
There are two scenarios for building the Kvasir
tool:

@itemize @bullet
@item
You have downloaded a packaged release of Daikon from our website and
have followed the installation steps in @ref{Installing Daikon}.  If so,
Kvasir is already built and available for use.
@item
You wish to customize or extend Daikon and are (or will be) working
with a clone of the Daikon repository. The remainder of this section
describes this case.
@end itemize

We assume you are already familiar with the @cite{Daikon Developer Manual},
in particular @ref{Compiling Daikon,,,developer,Daikon Developer Manual}.
If that is not the case, you should read that section first.

You will need to make a clone of Fjalar's version control repository, named
@file{fjalar}, as a sibling of your Daikon clone.

@example
cd $DAIKONDIR
cd ..
git clone https://github.com/codespecs/fjalar.git
@end example

You may now build Fjalar (which includes Kvasir).  The following commands build
Fjalar, install it locally, and make a symbolic
link to it in your Daikon tree.

@example
cd $DAIKONDIR
make kvasir
@end example

You may see warnings during this process.  You can ignore these.

If you receive an error of the form:

@example
readelf.c:53:17: fatal error: bfd.h: No such file or directory
#include "bfd.h"
          ^
compilation terminated.
@end example

@noindent
then install the package @file{binutils-dev}.

If you receive an error of the form:

@example
readelf.c:72:10: fatal error: zlib.h: No such file or directory
 #include <zlib.h>
          ^~~~~~~~
compilation terminated.
@end example

@noindent
then install the package @file{zlib1g-dev}.

Once Kvasir has been installed, it can be used via the
@file{kvasir-dtrace} script in the @file{$DAIKONDIR/scripts} directory.  If
you have set up the Daikon environment according to the instructions
above, it should already be in your @env{PATH}.  For instructions on using
Kvasir, see @ref{Kvasir}.


@node       Kvasir limitations
@subsection Kvasir implementation and limitations

Kvasir is based on the Valgrind dynamic program supervision framework
(which is best known for its memory error detection tool).  Using
Valgrind allows Kvasir to interrupt your program's execution, read its
variables, and examine its memory usage, all transparently to the
program.  Also, rather than using your program's source code to find
the names and types of functions and variables, Kvasir obtains them
from debugging information included in the executable in a standard
format (DWARF-2).

@cindex AMD64 architecture, and Kvasir
@cindex Intel 64 architecture, and Kvasir
@cindex IA-32e architecture, and Kvasir
@cindex EM64T architecture, and Kvasir
@cindex 64-bit AMD64 architecture, and Kvasir

However, Kvasir has some limitations of its own.  Because Kvasir uses
Valgrind, it shares Valgrind's processor and operating system limitations.
Furthermore, of the platforms supported by Valgrind, the only one
currently supported by Kvasir is @var{amd64-linux}.
Valgrind support for @var{x86-linux} is now in maintenance mode and Kvasir
no longer supports this platform.
@var{x86-linux} refers to Intel 386-compatible processors
(the so-called IA-32 architecture) such as the Intel Pentium and the
AMD Athlon, running Linux.
@var{amd64-linux} refers to the 64-bit extension of the x86
architecture found in many newer Intel and AMD processors, also
variously referred to as x86-64, @nospellcheck{IA-32e}, EM64T, and Intel 64, when
running under a Linux kernel in 64-bit mode.
The Itanium or IA-64 architecture is not supported.

Kvasir requires that your program have debugging
information available in the DWARF-2 format, as produced by @command{gcc} version
3 and later.  For the best results, the programs used by Kvasir should be
compiled without optimization.

This subsection lists some of the known limitations of the
current Kvasir release; if you encounter any problems other than listed
here, please report them as bugs (@pxref{Reporting problems}).  The
limitations are listed roughly in decreasing order of severity.

@itemize @bullet

@item
Kvasir-traced programs take a while to start (often a good fraction of a
second).  When tracing short-lived programs, this overhead can
dominate Kvasir's per-instruction runtime overhead.  In order to make Kvasir
run faster, try the @option{--ignore-globals}
option in order to limit the amount of generated output.
However, please keep in mind that, when running simultaneously with
Daikon using the @option{--output-fifo} option (see @ref{Online execution}), Kvasir can generate
output data much faster than Daikon can process it.  Thus, it is not the
performance bottleneck in the entire invariant detection system.

@item
Kvasir's support for outputting arrays is not yet complete.
It still does not have the functionality to print out multidimensional
arrays with all of their elements or the option to flatten
multidimensional arrays into multiple single-dimensional arrays.

@item
Kvasir behaves somewhat differently with different versions of @command{gcc}@.
If feasible, we recommend that you use Kvasir with version 4.7 (or newer).
Incompatibilities
between Kvasir and the debugging information produced by older @command{gcc}
versions can lead to incorrect output and, in some cases, can cause Kvasir to crash.

@item
Kvasir with DynComp will produce different results for x86 and
x86-64 hosts. This is due to a DynComp limitation with regards to
handling the AMD64 ABI. The AMD64 ABI allows structs that are
less than 8-bytes to be passed to a function via register.
DynComp categorizes this as an interaction between all
fields of the struct and will mark all fields of the struct as
comparable to each other.

@item
Kvasir is incompatible with some compiler optimizations.  It is
definitely incompatible with the @option{-fomit-frame-pointer}
optimization, and it may have trouble with other optimizations as
well.  We recommend that you compile programs for Kvasir without
optimization.

@item
Kvasir always prints the contents of structures according to their
compile-time type.  Programs that use generic pointers and structural
equivalence to simulate object-orientation will have derived-class
fields missing when a structure is passed via a base-class pointer.
This limitation can be worked around by manually coercing a pointer to a
particular type (@pxref{Pointer type coercion}).

@end itemize


@node    Celeriac
@section .NET (C#) front end Celeriac

@cindex Celeriac (front end for .NET)
@cindex front end for .NET
@cindex .NET front end
@cindex instrumentation, of .NET programs
@cindex front end for C#
@cindex C# front end
@cindex instrumentation, of C# programs
@cindex front end for F#
@cindex F# front end
@cindex instrumentation, of F# programs
@cindex front end for Visual Basic
@cindex Visual Basic front end
@cindex instrumentation, of Visual Basic programs
@cindex front end for Basic
@cindex Basic front end
@cindex instrumentation, of Basic programs

The Daikon front end for .NET languages, named Celeriac, is distributed
separately; it currently supports the C#, F# and Visual Basic .NET languages.
Celeriac runs the .NET program, creates data trace (@file{.dtrace}) files,
and optionally runs Daikon on them.
Celeriac is named after the celeriac plant, whose root may be
used as an ingredient in soups or stews.


To use Celeriac, run your program as you normally would, but with the
Celeriac Launcher.
For instance, if you usually run
@exampleindent 1
@example
MyProgram.exe arg1 arg2 arg3
@end example

@noindent
then instead you would run
@example
CeleriacLauncher.exe celeriacArg1 celeriacArg2 MyProgram.exe arg1 arg2 arg3
@end example
@exampleindent 4

@noindent
This runs your program and creates the @file{MyProgram.dtrace}
in the current directory.
Since Celeriac instruments class files directly as they are loaded into .NET,
you do not need to perform separate instrumentation and recompilation steps.

For more details about how to download and use Celeriac, please
see @uref{https://github.com/codespecs/@/daikon-dot-net-front-end}.

It should be noted that Celeriac works under Mono as well as under the
Microsoft .NET implementation.

To insert Daikon-inferred invariants in C# source code as Code Contracts,
use Scout (previously called @nospellcheck{Contract Inserter}):
@uref{https://bitbucket.org/fmc3/scout}.


@node    dfepl
@section Perl front end dfepl

@cindex front end for Perl
@cindex Perl front end
@cindex dfepl (front end for Perl)
@cindex instrumentation, of Perl programs

This section contains details about @command{dfepl}, the Daikon front end for
Perl.  For a brief introduction to @command{dfepl}, see @ref{Perl examples} and
@ref{Instrumenting Perl programs}.

@command{dfepl} works with Perl versions 5.8 and later. (To be precise, Perl
programs instrumented with @command{dfepl} can also be run with Perl 5.6, but
the instrumentation engine, which is itself written in Perl, requires
version 5.8).  @command{dfepl} reads the source code for Perl modules or
programs, and writes out instrumented versions of that code that
keep track of function parameters, and make calls to routines in the
@file{daikon_runtime} package whenever an instrumented subroutine is
entered or exited.

The instrumentation engine recognizes parameters as those variables
that are declared with @code{my(...)} or @code{local(...)} and, in the
same expression, assigned to from a value related to the argument
array @code{@@_}, but only among the first contiguous series of such
assignments in the body of a subroutine.  This will capture the most
common assignment idioms, such as @code{my $self = shift;} (where
@code{shift} is short for @code{shift @@_}), @code{my $x = $_[0];}, and
@code{my($x, $y, @@a) = @@_;}, but the arguments to subroutines which
access them only directly through @code{@@_}, or that perform other
operations before reading their arguments, will not be recognized.

If the uninstrumented code requested warnings via the @code{use
warnings} pragma or by adding the @option{-w} flag on the @code{#!}
line, the instrumented code will also request warnings.  In this case,
or if @option{-w} is specified on the command line when running it, the
instrumented code may produce warnings that the original code did
not.  There are several situations in which the instrumented code
produced by @command{dfepl}, while functionally equivalent to the original,
generates more warnings.  The most common such problem, which arises
from code that captures the scalar-context return value of a
subroutine that returns a list, has been avoided in the current
version by disabling the warning in question.  Other warnings which
are known to be produced innocuously in this way include
@samp{Ambiguous call resolved as CORE::foo(), qualify as such or use
&} (caused by code that uses @code{CORE::} to distinguish a built-in
function from a user subroutine of the same name), and @samp{Constant
subroutine foo redefined} (caused by loading both instrumented and
uninstrumented versions of a file).  Though some such warnings
represent deficiencies in the instrumentation engine, they can be
safely ignored when they occur.

Because Perl programs do not contain static type information to
distinguish, for instance, between strings and numbers, the Perl
front end incorporates an additional dynamic analysis to infer these
types.  This type guessing, which occurs as a first pass before the
program can be instrumented to produce output for Daikon, operates in
a manner somewhat analogous to Daikon itself: watching the execution
of a program, the runtime system chooses the most restrictive type for
a variable that is not contradicted during that execution.  These
types indicate, for instance, whether a scalar value always holds an
integer, a possibly fractional numeric value, or a reference to
another object.  It should not be necessary to examine or modify this
type information directly, but for the curious, the syntax of the type
information is described in comments in the @file{Daikon::PerlType}
module.

The safest course is to infer types for variables using exactly the
same program executions (e.g., test cases) which will later be used to
generate traces for Daikon, as this guarantees that the type
information will match the actual data written to the trace file.
However, because the type-guessing-instrumented versions of programs
run fairly slowly in the current version, you may be tempted to use a
subset of the input data for type guessing.  Doing so is possible, but
it will only work correctly if the smaller tests exercise all of the
instrumented subroutines and exit points with all the types of data
they will later be used with.  If the trace runtime tries to output a
data value that doesn't match the inferred type, the value may
silently be converted according to Perl's usual conventions (for
instance, a non-numeric string may be treated as the number zero), or
it may cause an error during tracing (for instance, trying to
dereference a supposed array reference that isn't).  Also, if a
subroutine exit point is traced but was never encountered during type
guessing, the generated @file{.decls} and @file{.dtrace} files will be
incompatible in a way that will cause Daikon to abort with an error
message of the form @samp{Program point foo():::EXIT22 appears in @file{.dtrace}
file but not in any @file{.decls} file}.

@float Figure,dfepl-flow
@center @image{images/dfepl-flow,4in,}
@caption{Workflow of instrumenting Perl code with @command{dfepl}.}
@end float

@command{dfepl} works by reading one or more Perl programs
or modules, and writing out new versions of those files, instrumented
to capture information about their execution, by default to another
directory.  @command{dfepl} is used in two passes: first, before type
information is available, instrumented versions are written to a
directory @file{daikon-untyped}.  These untyped programs, when run,
will write
files containing dynamically inferred type information (with the
extension @file{.types}), by default to the @file{daikon-instrumented}
directory.  When @command{dfepl} is rerun with this type information, it
produces type-aware instrumented code in the
@file{daikon-instrumented} directory, which when run produces
execution traces in files with the extension @file{.dtrace} in the a
directory @file{daikon-output}.

@menu
* dfepl options::
@end menu

@node       dfepl options
@subsection dfepl options

@table @option
@item --absolute
@itemx --no-absolute
@option{--absolute} stores the absolute path to the output directories
(by default named @file{daikon-untyped}, @file{daikon-instrumented} or
@file{daikon-output}) in the instrumented programs, so that no matter
where the instrumented program is run, the output will go to a fixed
location.  Even if these directories are given as relative paths (as is
the default), @option{--absolute} specifies that they should always be
taken as relative to the directory that was the working directory when
@command{dfepl} was run.

@option{--no-absolute} specifies the opposite, causing the output paths
to be interpreted relative to the current working directory each time
the instrumented program is invoked.  The default, when neither option
is specified, is for @file{.types} files to use an absolute path, but
all others to use relative path, so that the @file{.types} files will
always be in the same place as the instrumented source files that
generated them, but the @file{daikon-output} directory will be created
in the current directory when the program runs.

@item --accessor-depth=@var{num}
Controls the number of nested invocations of object accessor methods
to examine.  For instance, suppose that the @code{Person} class has a
method @code{mother()} that returns another person (and has been
specified to @command{dfepl} as an accessor), and that @code{$me} is
an instrumented variable.  If the accessor depth is 1, only
@code{$me->mother()} will be examined.  If the depth is 2,
@code{$me->mother()->mother()} will also be examined.  Specifying large
accessor depths is generally not advisable, especially with many
accessor methods, as the number of variables examined can be too many
for Daikon to process efficiently.

By default, the Daikon Perl trace runtime will examine at most a
single level of accessors.

@item -A
@itemx --accessors-dir=@var{directory}
Look for files containing accessor lists in @var{directory}, or the
current directory if @var{directory} is omitted.  For a class
@code{Acme::Foo}, accessors are methods that return information about
an object but do not modify it.  @command{dfepl} cannot determine on
its own which methods are accessors, but when a list of them is
provided, it can call an object's accessors when examining a variable
of that class to obtain more information about the object.  To tell
@command{dfepl} about the accessors for @code{Acme::Foo}, make a file
listing the names of each accessor method, one per line with no other
punctuation, named @file{Acme/Foo.accessors} in the same directory as
@file{Acme/Foo.pm}.

@item --decls-dir=@var{directory}
Put generated declaration files in @var{directory} and its
subdirectories.  The default is @file{daikon-output}.

@item --decls-style=@var{style}
@var{style} should be one of @option{combined}, @option{flat}, or
@option{tree}.  A style of @option{combined} specifies that the
declarations for all packages should be merged, in a file named
@file{prog-combined.decls} where @file{prog} is the name of the
program.  A style of @option{flat} specifies that the declarations for
each package should be in a separate file named after the package, but
that these files should go in a single directory; for instance, the
declarations for @code{Acme::Trampoline} and
@code{Acme::Skates::Rocket} would go in files named
@file{Acme::Trampoline.decls} and @file{Acme::Skates::Rocket.decls}.  A
style of @option{tree} specifies that each package should have its own
declarations file, and that those files should be arranged in
directories whose structure matches the structure of their package
names; in the example above, the files would be
@file{Acme/Trampoline.decls} and @file{Acme/Skates/Rocket.decls}.

The default is @option{tree}.  Note that @option{--decls-style} and
@option{--types-style} are currently constrained to be the same; if
one is specified, the other will use the same value.

@item --dtrace-append
@itemx --no-dtrace-append
When @option{--dtrace-append} is specified, the instrumented program
will append trace information to the appropriate
@file{.dtrace} file each time it runs.  When
@option{--no-dtrace-append} is specified, it will overwrite the file
instead.

The default behavior is to overwrite.  This choice can also be
overridden, when the program is run, to always append by setting the
environment variable @env{DTRACEAPPEND} to 1.

When appending to a @file{.dtrace} file, no declaration information is
ever produced, because it would be redundant to do so and Daikon does
not permit re-declarations of program points.

@item --dtrace-dir=@var{directory}
Put generated trace files in @var{directory} and its
subdirectories.  The default is @file{daikon-output}.

@item --dtrace-style=@var{style}
@var{style} should be one of @option{combined}, @option{flat}, or
@option{tree}.  A style of @option{combined} specifies that the traces
for all packages should be merged, in a file named
@file{prog-combined.dtrace}, where @file{prog} is the name of the
program.  A style of @option{flat} specifies that the
traces for each package should be in a separate file named after the
package, but that these files should go in a single directory; for
instance, the declarations for @code{Acme::Trampoline} and
@code{Acme::Skates::Rocket} would go in files named
@file{Acme::Trampoline.dtrace} and
@file{Acme::Skates::Rocket.dtrace}.  A style of @option{tree} specifies
that each package should have its own trace file, and that
those files should be arranged in directories whose structure matches
the structure of their package names; in the example above, the files
would be @file{Acme/Trampoline.dtrace} and
@file{Acme/Skates/Rocket.dtrace}.

The default is @option{combined}.

@item --help
Print a short options summary.

@item --instr-dir=@var{directory}
@c dfec option -- do not rename (yet)
@itemx --instrsourcedir=@var{directory}
Put instrumented source files in @var{directory} and its
subdirectories.  The default is @file{daikon-untyped}, or
@file{daikon-instrumented} if type information is available.

@item --list-depth=@var{DEPTH}
Consider as many as @var{DEPTH} of the first elements of a list to be
distinct entities, for the purpose of guessing their types.  When
subroutines return a list of values, each value may have a distinct
meaning, or the list may be homogeneous.  When trying to assign types
to the elements of a list, the Daikon Perl trace runtime will try
making separate guesses about the types of the elements of a short
list, but it would be inefficient to make retain this distinction for
many elements.  This parameter controls how many elements of a list
will be examined individually; all the others will be treated
uniformly.

The default is 3.

@item --output-dir=@var{directory}
Put all of the files that are the output of the tracing process (and
therefore input to the Daikon invariant detection engine) in
@var{directory} and its subdirectories.  This option is a shorthand
equivalent to setting both @option{--decls-dir} and
@option{--dtrace-dir} to the same value.

The default behavior is as if @option{--output-dir=daikon-output} had
been specified.

@item --perl=@var{path}
Use @var{path} as the location of Perl when calling the annotation
back end (a module named @code{B::DeparseDaikon}), rather than the
version of Perl under which @command{dfepl} itself is running, which
is probably the first @command{perl} that occurs on your path.  For
instance, if the first version of @command{perl} on your path isn't
version 5.8 or later, you should this option to specify another
@command{perl} program that is.

@item --nesting-depth=@var{num}
When examining nested data structures, traverse as many as @var{num}
nested references.  For instance, suppose that @code{@@a} is the array

@example
@@a = (@{1 => [2, 3]@}, @{5 => [4, 2]@})
@end example

If the depth is 0, then when examining @code{@@a}, Daikon's Perl trace
runtime will consider it to be an array whose elements are references,
but it won't examine what those references point to.  If the depth is
1, it will consider it to be an array of references to hashes whose
keys are integers and whose values are references, but it won't
examine what @emph{those} references point to.  Finally, if the depth
is 2 or more, it will consider @code{@@a} to be an array of references
to hashes whose keys are integers and whose values are references to
arrays of integers.

The default nesting depth is 3.

When referenced objects have accessor methods, or when accessors
return references, the @option{--accessor-depth} and
@option{--nesting-depth} options interact.  Specifically, if these
depths are A and R, the behavior is as if the runtime has a budget of
1 unit, which it can use either on accessors which cost 1/A or
references which cost 1/R@.  It may thus sometimes be useful to specify
fractional values for @option{--accessor-depth} and
@option{--nesting-depth}; in fact, the default accessor depth is
1.5.

@item --types-append
@itemx --no-types-append
When @option{--types-append} is specified, the instrumented program
will append type information to the appropriate
@file{.types} file each time it runs.  When
@option{--no-types-append} is specified, it will overwrite the file
instead.

The default behavior is to append.  If @option{--no-types-append} is
specified, however, this choice can also be overridden, when the
program is run, to append by setting the environment variable
@env{TYPESAPPEND} to 1.  There is no way to use environment variables
to force the runtime to overwrite a types file, but an equivalent
effect can be obtained by simply removing the previous types file
before each run.

@item -T
@itemx --types-dir=@var{directory}
Look for @file{.types} files in @var{directory}, or
@file{daikon-instrumented} if @var{directory} is omitted.  When
instrumenting a module @code{Acme::Trampoline}, used in a program
@file{coyote.pl},  @command{dfepl} will look for
files named @file{coyote-combined.types}, @file{Acme::Trampoline.types}, and
@file{Acme/Trampoline.types}, corresponding to the possible choices of
@option{--types-style}.  Once discovered, the files are used in the
same way as for @option{-t}.

@item --types-file=@var{file}
@itemx -t @var{file}
Include type information from @var{file} when instrumenting programs
or modules.  Since Daikon needs to know the types of variables when
they are declared, useful @file{.decls} and @file{.dtrace} files can
only be produced by source code instrumented with type
information.  Since Perl programs don't include this information to
begin with, and it would be cumbersome to produce by hand, type
information must usually be produced by running a version of the
program that has itself been annotated, but without type
information.  The Daikon Perl trace runtime will automatically decide
whether to output types, or declarations and traces, depending on
whether the source was instrumented without or with types.  This option
may occur multiple times, to read information from multiple types
files (irrelevant type information will be ignored).

@item --types-basedir=@var{directory}
Put files containing type information in @var{directory} and its
subdirectories.  By default, this is whatever @option{--instr-dir}
is, usually @file{daikon-instrumented}.

@item --types-style=@var{style}
@var{style} should be one of @option{combined}, @option{flat}, or
@option{tree}.  A style of @option{combined} specifies that the types
for all packages should be merged, in a file named
@file{prog-combined.types}, where @file{prog} is the name of the
program.  A style of @option{flat} specifies that the
types for each package should be in a separate file named after the
package, but that these files should go in a single directory; for
instance, the declarations for @code{Acme::Trampoline} and
@code{Acme::Skates::Rocket} would go in files named
@file{Acme::Trampoline.types} and
@file{Acme::Skates::Rocket.types}.  A style of @option{tree} specifies
that each package should have its own trace file, and that
those files should be arranged in directories whose structure matches
the structure of their package names; in the example above, the files
would be @file{Acme/Trampoline.types} and
@file{Acme/Skates/Rocket.types}.

The default is @option{tree}.  Note that @option{--types-style} and
@option{--decls-style} are currently constrained to be the same; if
one is specified, the other will use the same value.

@item --verbose
@itemx -v
Print additional information about what @command{dfepl} is doing,
including external commands invoked.
@end table


@node    convertcsv.pl
@section Comma-separated-value front end convertcsv.pl

@cindex csv files
@cindex comma-delimited files
@cindex comma-separated-value files
@cindex tab-separated files
@cindex Excel files
@cindex spreadsheet files

Daikon can process data from spreadsheets such as Excel.  In order to
use such files, first save them in
@uref{https://en.wikipedia.org/wiki/Comma-separated_values, ,comma-separated-value format},
also known as @dfn{csv} or comma-delimited or comma-separated-list, format.
Then, convert the @file{.csv} file into a @file{.dtrace} file (and a
@file{.decls} file) to be used by Daikon by running the
@command{convertcsv.pl} program found in the @file{$DAIKONDIR/scripts}
directory.  For example,
@example
convertcsv.pl myfile.csv
@end example

@noindent
produces files @file{myfile.decls} and @file{myfile.dtrace}.

Important:  run @command{convertcsv.pl} without any arguments in order
to see a usage message.

In order to ensure all data is processed, use Daikon with the
@option{--nohierarchy} option, as follows:
@example
java daikon.Daikon --nohierarchy myfile.decls myfile.dtrace
@end example

@noindent
In a future release, the @option{--nohierarchy} option may not be necessary,
but it should always be safe to use this option.

Before running @command{convertcsv.pl}, you may need to install
@command{Text::CSV}, a Perl package that @command{convertcsv.pl} uses.
You also need the
@uref{https://raw.githubusercontent.com/plume-lib/html-tools/master/checkargs.pm,
@file{checkargs.pm}} file, which is part of the html-tools library
(@url{https://github.com/plume-lib/html-tools}).


@node    Other front ends
@section Other front ends

It is relatively easy to create a Daikon front end for another language
or run-time system.  For example, people have done this without any help
at all from the Daikon developers.  For more information about building
a new front end,
see @ref{New front ends,,,developer,Daikon Developer Manual}.

@cindex Udon front end for LLVM
@cindex front end for LLVM
@cindex LLVM front end
@cindex instrumentation, of LLVM programs

A front end for LLVM, named Udon, is distributed
separately; see @uref{https://github.com/markus-kusano/udon}.
It can be used on any programming language that can be compiled to LLVM.

@cindex Takuan front end for WS-BPEL
@cindex front end for WS-BPEL
@cindex WS-BPEL front end
@cindex instrumentation, of WS-BPEL process definitions

A front end for @nospellcheck{WS-BPEL} process definitions, named Takuan,
is distributed
separately; see @uref{http://web.archive.org/web/20160528161316/https://neptuno.uca.es/redmine/projects/takuan-website}.

@cindex CITADEL front end for Eiffel
@cindex front end for Eiffel
@cindex Eiffel front end
@cindex instrumentation, of Eiffel programs

A front end for the Eiffel programming language, named CITADEL, is distributed
separately; see @uref{http://se.inf.ethz.ch/people/polikarpova/citadel/}.

@cindex Hynger front end for Simulink/Stateflow (SLSF) block diagrams
@cindex front end for Simulink/Stateflow (SLSF) block diagrams
@cindex Simulink/Stateflow (SLSF) front end
@cindex instrumentation, of Simulink/Stateflow (SLSF) block diagrams

A front end for the @nospellcheck{Simulink/Stateflow (SLSF)} programming language, named
Hynger, is distributed separately; see
@uref{https://bitbucket.org/verivital/hynger}.

@cindex front end for IOA
@cindex front end for Input/Output Automata
@cindex IOA front end
@cindex Input/Output Automata front end
@cindex instrumentation, of IOA programs
@cindex instrumentation, of Input/Output Automata programs

A front end for the IOA (Input/Output Automata) programming language is distributed separately;
see @uref{http://groups.csail.mit.edu/tds/ioa.html}.

@cindex front end for Lisp
@cindex Lisp front end
@cindex instrumentation, of Lisp programs

An earlier version of Daikon included a Lisp front end, but it is no
longer supported.

An earlier version of Daikon provided a source-based front end for Java
named @command{dfej}.  It has been superseded by Chicory (@pxref{Chicory}).

An earlier version of Daikon provided a source-based front end for C
named @command{dfec}.  It has been superseded by Kvasir (binary-based, for
Linux/x86; @pxref{Kvasir}).


@node    Tools
@chapter Tools for use with Daikon

This chapter describes various tools that are included with the Daikon
distribution.
@menu
* Tools for manipulating invariants::
* DtraceDiff utility::
* Reading dtrace files::
@end menu

@node    Tools for manipulating invariants
@section Tools for manipulating invariants

@cindex .inv files, tools for manipulating
@cindex inv files, tools for manipulating

This section gives information about tools that manipulate invariants
(in the form of @file{.inv} files).


@menu
* Printing invariants::
* MergeInvariants::
* Invariant Diff::
* Annotate::
* AnnotateNullable::
* Runtime-check instrumenter::
* InvariantChecker::
* LogicalCompare::
@end menu


@node       Printing invariants
@subsection Printing invariants

@cindex printing invariants
@cindex PrintInvariants program

Daikon provides many options for controlling how invariants are printed.
Often, you may want to print the same set of invariants several
different ways.  However, you only want to run Daikon once, since it may
be very time consuming.  The @command{PrintInvariants} utility prints a set of
invariants from a @file{.inv} file.

@command{PrintInvariants} is invoked as follows:
@example
java daikon.PrintInvariants @i{[@var{flags}]} @var{inv-file}
@end example

@command{PrintInvariants} shares many flags with Daikon.
These flags are only briefly summarized here.
For more information about these flags, see @ref{Configuration options}.

In particular, see the configuration options whose names start with
@code{daikon.PrintInvariants}; see @ref{General configuration options}.

@table @option
@item --help
Print usage message.

@item --format @var{name}
Produce output in the given format.  See @ref{Invariant syntax}.

@item --output @var{filename}
Send output to the specified file rather than @command{stdout}.

@item --output_num_samples
Output numbers of values and samples for invariants and program points;
for debugging.

@item --ppt-select-pattern
Only outputs program points that match the specified regular expression

@item --config @var{filename}
Load the configuration settings specified in the given file.
@xref{Configuration options}, for details.

@item --config_option @var{name}=@var{value}
Specify a single configuration setting.
@xref{Configuration options}, for details.

@item --dbg @var{category}
@itemx --debug
Enable debug loggers.

@item --track @var{class}<@var{var1},@var{var2},@var{var3}>@@@var{ppt}
Track information on specified invariant class, variables and program point.
For more information,
see @ref{Track logging,,,developer,Daikon Developer Manual}.

@item --wrap_xml
Print extra info about invariants, and wrap in XML tags.
This is primarily for programmatic use and for debugging.
To add just the Java class of each invariant, use
@code{--config_option daikon.PrintInvariants.print_inv_class=true}.

@end table


@node       MergeInvariants
@subsection MergeInvariants

@cindex invariant merge
@cindex merge invariants

The @command{MergeInvariants} utility merges multiple serialized invariant files
to create a single serialized invariant file that contains the
invariants that are true across each of the input files.  The results
of merging N serialized invariant files should be the same as running
Daikon on the N original @file{.dtrace} files.

@command{MergeInvariants} is invoked as follows:
@example
java daikon.MergeInvariants @i{[@var{flags}]...} @var{file1} @var{file2}...
@end example

@noindent
@var{file1} and @var{file2} are files containing serialized invariants
produced by running Daikon.  At least two invariant files must be specified.

@command{MergeInvariants} shares many flags with Daikon.
These flags are only briefly summarized here.
For more information about these flags, see @ref{Daikon configuration options}.

@table @option
@item -h --help
Print usage message.

@item -o @var{inv_file}
Output serialized invariants to the specified file; they can later be
postprocessed, compared, etc.  If not specified, the results are written
to standard out.

@item --config_option @var{name}=@var{value}
Specify a single configuration setting.
@xref{Configuration options}, for details.

@item --dbg @var{category}
Enable debug loggers.

@item --track @var{class}<@var{var1},@var{var2},@var{var3}>@@@var{ppt}
Track information on specified invariant class, variables and program point.
For more information,
see @ref{Track logging,,,developer,Daikon Developer Manual}.
@end table


@node       Invariant Diff
@subsection Invariant Diff

@cindex invariant diff
@cindex diff, over invariants
@cindex comparing invariants

The invariant diff utility is designed to output the differences between
two sets of invariants.  Invariant diff compares invariants at program
points with the same name.

Invariant diff lets you
compare the invariants generated by two versions of the same program,
or compare the invariants generated by different runs of one program.

Invariant diff is invoked as follows:
@example
java daikon.diff.Diff @i{[@var{flags}]...} @var{file1} [@var{file2}]
@end example

@noindent
@var{file1} and @var{file2} are files containing serialized invariants
produced by running Daikon or Diff
with the @option{-o} flag.  If @var{file2} is not specified,
@var{file1} is compared with the empty set of invariants.

This section describes the optional flags.

@table @option
@item --help
Print usage message.

@item -d
Display the tree of differing invariants (default).  Invariants that are
the same in @var{file1} and @var{file2} are not printed.  At least one of the
invariants must be justified.  Does not print ``uninteresting'' invariants
(currently some @samp{OneOf} and @samp{Bound} invariants).

@item -a
Display the tree of all invariants.  Includes invariants that are the
same in @var{file1} and @var{file2}, and unjustified invariants.

@item -u
Include ``uninteresting'' invariants in the tree of differing invariants.

@item -y
@itemx --ignore_unjustified
Include (statistically) unjustified invariants.

@item -m
Compute (@var{file1} - @var{file2}).  This is all the invariants that appear in
@var{file1} but not @var{file2}.  Unjustified invariants are treated as if they
don't exist.  Output is written as a serialized @samp{InvMap} to the file
specified with the @option{-o} option.  To view the contents of the serialized
@samp{InvMap}, run @command{java daikon.diff.Diff @var{file}}.

@item -x
Compute (@var{file1} XOR @var{file2}).
This is all the invariants that appear in
one file but not the other.  Unjustified invariants are treated as if
they don't exist.  Output is written as a serialized @samp{InvMap} to the file
specified with the @option{-o} option.  To view the contents of the serialized
@samp{InvMap}, run @command{java daikon.diff.Diff @var{file}}.

@item -n
Compute (@var{file1} UNION @var{file2}).
This is all the invariants that appear in
either file.  If the same invariant appears in both files, the one with
the better justification is chosen.  Output is written as a serialized
@samp{InvMap} to the file specified with the @option{-o} option.  To view the contents
of the serialized @samp{InvMap}, run @command{java daikon.diff.Diff @var{file}}.

@item -o @var{inv_file}
Used in combination with the @option{-m} or @option{-x} option.  Writes
the output as a serialized @samp{InvMap} to the specified file.

@item -p
Examine all program points.  By default, only procedure entries and
combined procedure exits are examined.  This option also causes
conditional program points to be examined.

@item -e
Print empty program points.  By default, program points are not printed
if they contain no differences.

@item --invSortComparator1 @var{classname}
@itemx --invSortComparator2 @var{classname}
@itemx --invPairComparator @var{classname}
Use the specified class as a custom comparator.  A custom comparator can
be used for any of 3 operations: sorting the first set of invariants,
sorting the second set of invariants, and combining the two sets into
the pair tree.  The specified class must implement the Comparator
interface, and accept objects of type Invariant.

@item -v
Verbose output.  Invariants are printed using the @code{repr()} method, instead
of the @code{format()} method.

@item -s
For internal use only.  Display the statistics between two sets of
invariants.  The pairs of invariants are placed in bins according to the
type of the invariant and the type of the difference.

@item -t
For internal use only.  Display the same statistics as @option{-s}, but as a
tab-separated list.

@item -j
For internal use only.  Treat justification as a continuous value when
gathering statistics.  By default, justification is treated as
a binary value --- an invariant is either justified or it is not.  For
example, assume invariant @samp{I1} has a probability of .01, and @samp{I2} has a
probability of .5.  By default, this will be a difference of 1,
since @samp{I1} is justified but @samp{I2} is not.  With this option, this will be a
difference of .49, the difference in the probabilities.  This only
applies when one invariant is justified, and the other is unjustified.

@item -l
For debugging use only.  Prints logging information describing the state
of the program as it runs.

@end table


@node       Annotate
@subsection Annotate

@cindex Annotate tool
@cindex MergeESC tool, see Annotate tool

The Annotate program inserts Daikon-generated invariants into Java
source code as annotations in @option{DBC}, @option{ESC}, @option{Java} or @option{JML} format.
These annotations are comments that can be automatically verified or
otherwise manipulated by other tools.
The Daikon website has an example of code after invariant
insertion:  @url{http://plse.cs.washington.edu/daikon/StackAr.html}.

Invoke Annotate like this:
@exampleindent 1
@example
java daikon.tools.jtb.Annotate Myprog.inv Myprog.java Myprog2.java ...
@end example
@exampleindent 4

@noindent
The first argument is a Daikon @file{.inv} or @file{.inv.gz} file
produced by running
Daikon with the @option{-o} command-line argument.  All subsequent
arguments are @file{.java} files.  The original @file{.java} files are left
unmodified, but Annotate produces new versions of the @file{.java} files
(with names suffixed as @file{-escannotated}, @file{-jmlannotated}, or
@file{-dbcannotated}) that include the Daikon invariants as comments.

The options are:
@table @option

@item --format @var{name}
Produce output in the given format.  See @ref{Invariant syntax}.

@item --no_reflection
Do not use reflection to find information about the classes being
instrumented.  This allows Annotate to run without having access
to the class files.  Since the class files are necessary to generate @samp{also}
tags, those tags will be left out when this option is chosen.

@item --max_invariants_pp @var{count}
Output at most @var{count} invariants per program point (which ones are chosen
is not specified).

@item --wrap_xml
Each invariant is printed using the given format (@option{ESC}, @option{JML} or @option{DBC}),
but the invariant expression is wrapped inside XML tags, along with other
information about the invariant.

For example, if this switch is set, the output format is @option{ESC},
and an invariant for method @code{foo(int x)} normally prints as

@exampleindent 1
@example
/*@ requires x != 0; */
@end example

@noindent
Then the resulting output will look something like this (all
in one line; we break it up here for clarity):

@example
/*@ requires <INVINFO>
<INV> x != 0 </INV>
<SAMPLES> 100 </SAMPLES>
<DAIKON> x != 0 </DAIKON>
<DAIKONCLASS> daikon.inv.unary.scalar.NonZero </DAIKONCLASS>
<METHOD> foo() </METHOD>
</INVINFO> ; */
@end example
@exampleindent 4

@noindent
Note that the comment will no longer be a legal @option{ESC}/@option{JML}/@option{DBC}
comment.  To make it legal again, you must replace the XML tags with
the string between the @samp{<INV>} tag.

Also note the extra information printed with the invariant: the number
of samples from which the invariant was inferred, the Daikon
representation (i.e., the Daikon output format), the Java class that
the invariant corresponds to, and the method that the invariant
belongs to (@code{null} for object invariants).

@end table

@cindex Annotate warning: Daikon knows nothing about field
@cindex Daikon knows nothing about field:  warning from Annotate
If Annotate issues a warning message of the form
@example
Warning: Annotate: Daikon knows nothing about field ...
@end example

@noindent
then the Annotate tool found a variable in the source code that was
computed by Daikon.  This can happen if Daikon was run omitting the
variable, for instance due to @option{--std-visibility}.  It can also happen due
to a bug in Annotate or Daikon; if that is the case, please report it to
the Daikon developers.


@node       AnnotateNullable
@subsection AnnotateNullable

@cindex AnnotateNullable tool
@cindex NonNull type inference
@cindex Nullable type inference
@cindex @@NonNull type inference
@cindex @@Nullable type inference
@cindex type inference, Nullable
@cindex inference, of Nullable type

@command{AnnotateNullable} determines which variables in a Java program were ever
null during execution.  @command{AnnotateNullable} makes it easier to use the
@uref{https://checkerframework.org/manual/#nullness-checker, Nullness Checker}
that is part of the
@uref{https://checkerframework.org/, Checker Framework}.

The @samp{Nullness} Checker
warns the programmer about possible null dereference errors.
This is useful, but it requires the programmer to write a @code{@@Nullable}
annotation anywhere that a variable might contain null.
(An unannotated reference is assumed to never be
null at run time.)

The @command{AnnotateNullable} tool automatically and soundly determines a subset of the
proper @code{@@Nullable} annotations, reducing the programmer's burden.
Each annotation that @command{AnnotateNullable} infers is
correct.  The programmer may need to write some additional
@code{@@Nullable} annotations, but that is much easier than writing them all.

To insert @code{@@Nullable} annotations in your program,
follow these steps:

@enumerate
@item
Run your application one or more times to create a trace file.
(It is not necessary to run DynComp.)
The more thorough your test runs, the larger number of
@code{@@Nullable} annotations @command{AnnotateNullable} will produce.

@smallexample
java daikon.Chicory --dtrace-file=an.dtrace.gz @emph{mypackage.MyClass arg1 arg2 ...}
@end smallexample

@item Run Daikon on the resulting @file{.dtrace} file:

@smallexample
java daikon.Daikon an.dtrace.gz --no_text_output \
    --config @var{daikondir}/java/daikon/annotate_nullable.config
@end smallexample

@c The example uses the @file{annotate_nullable.config} configuration file
@c that is included in the Daikon distribution.
@c You may use any configuration file, or none, as long as the NonZero
@c invariant is enabled.  The @file{annotate_nullable.config} enables
@c @emph{only} the NonZero invariant.  This makes Daikon run much faster,
@c but the resulting @file{.inv} file is useful only for the
@c AnnotateNullable tool.

@c This is an implementation detail, so leave it out of the manual.
@c AnnotateNullable determines which variables have seen null values by
@c looking at the NonZero invariant.  If NonZero is @emph{not} present for
@c a variable @code{v}, then during the program execution, @code{v} must
@c have been null at least once.

@item
Run the @command{AnnotateNullable} tool to create an annotation index file.
@command{AnnotateNullable} writes its output to standard out, so you should
redirect its output to a @file{.jaif} file.

@smallexample
java daikon.AnnotateNullable an.inv.gz > nullable-annotations.jaif
@end smallexample

@item
Use the
@uref{https://checkerframework.org/annotation-file-utilities/,
Annotation File Utilities} to insert the annotations in your
@file{.class} or @file{.java}
file.

@smallexample
# To insert in class files:
insert-annotations @var{mypackage.MyClass} nullable-annotations.jaif
# To insert in source files:
insert-annotations-to-source nullable-annotations.jaif \
    mypackage/MyClass.java annotated/mypackage/MyClass.java
@end smallexample

@end enumerate


@command{AnnotateNullable} is invoked as follows:
@smallexample
java daikon.AnnotateNullable @i{[@var{flags}]} @var{inv-file}
@end smallexample

@noindent
The flags are:
@table @option

@item -n --nonnull-annotations
Adds @samp{NonNull} annotations as well as @samp{Nullable} annotations.  Unlike @samp{Nullable}
annotations, @samp{NonNull} annotations are not guaranteed to be correct.

@end table


@node       Runtime-check instrumenter
@subsection Runtime-check instrumenter (runtimechecker)

@cindex runtime-check instrumenter
@cindex runtimechecker instrumenter

The runtimechecker instrumenter inserts, into a Java file,
instrumentation code that checks invariants as the program executes.
For a full list of options, run:

@example
java daikon.tools.runtimechecker.Main help
@end example

@noindent
The @code{instrument} command to runtimechecker creates a new directory
@file{instrumented-@/classes} containing a new version of the
user-specified Java files, instrumented to check invariants at runtime
and to record a list of invariant violations in a Java data structure.
You can compile and run the instrumented version of your program.

@c This is discussed below:
@c If you wish to check invariants at run time, you should either
@c use the @option{--make_all_fields_public} option to runtimechecker.Main, or
@c alternately you should use the @option{--std-visibility} option when you
@c run Chicory (@pxref{Variables in Chicory output}).

Here is an example of using the runtime-check instrumenter to
create a version of file
@file{ubs/BoundedStack.java} that checks the invariants in
invariant file @file{BoundedStack.inv.gz}:

@exampleindent 1
@example
java daikon.tools.runtimechecker.Main instrument BoundedStack.inv.gz \
    ubs/BoundedStack.java
@end example
@exampleindent 4

@noindent
The instrumented Java code references classes in the
@code{daikon.tools.runtimechecker} package, so those classes must be
present in the classpath when the instrumented classes are compiled and
executed.

Invariants are evaluated at the program points at which they should
hold.  Three things can happen when evaluating an
invariant:

@itemize @bullet
@item
It evaluates to true, which means that the invariant holds.
Program execution continues normally.

@item
It evaluates to false, which means that the invariant doesn't
hold.  In this case the corresponding
@code{daikon.@/tools.@/runtimechecker.@/Property} is added to a list in the
class @code{daikon.@/tools.@/runtimechecker.@/Runtime}.  A programmer can
obtain the growing list of violated invariants through the method
@code{daikon.@/tools.@/runtimechecker.@/Runtime.@/getViolations()}. (See
that class for other useful methods.)

@item
A @code{Throwable} (exception) is thrown when evaluating the
invariant.  In this case, the throwable is added to the list
@code{daikon.tools.runtimechecker.Runtime@/.internalInvariantEvaluationErrors}.
The throwable is not rethrown.

@end itemize

Note that the instrumented program does not do anything with the list of
violations; it merely creates the list.  You will need to write your own
code to process that list; see @ref{How to access violations}.


@menu
* How to access violations::
* Problems compiling instrumented code::
@end menu

@node          How to access violations
@subsubsection How to access violations

The instrumented class handles violations silently:
it simply adds them to a list in the class
@code{daikon.tools.runtimechecker.Runtime.}
No ``invariant violation'' exceptions are thrown, and the violated
invariants can only be obtained dynamically (while the program is running)
by calling @code{daikon.tools.runtimechecker.Runtime.getViolations()}.

@cindex WriteViolationFile tool
To obtain a file of all the violations for a program execution, you can use
program @code{daikon.@/tools.@/runtimechecker.@/WriteViolationFile}.
For example, if you usually run
@example
java MyProg arg1 arg2
@end example

@noindent
then instead you would run
@example
java daikon.tools.runtimechecker.WriteViolationFile MyProg arg1 arg2
@end example

This will create a file called @file{violations.txt} in the
current directory, immediately before the program exits normally.
If the program under test calls @code{System.exit}, then no
@file{violations.txt} file is created.  (@command{JUnit} is an example of a program
that calls @code{System.exit}.)

@c Here are two possible ways to handle System.exit:
@c 1. Change the instrumentation so that it rewrites calls to
@c System.exit(1) to do end-of-execution processing.  This might not work
@c if only part of the program is being instrumented; for example, you
@c would ordinarily instrument your tests rather than JUnit itself where
@c the call to System.exit() appears.
@c 2. Change the instrumentation to produce file output (rather than just
@c storing data in a list) and to flush the file as each element is added to it.


@c TODO: in the future, it would be nice to have a tool that throws an exception when any violation occurs.


The following code snippet contains a method @code{callMethod()} which
presumably calls one of the methods in the instrumented class.
The code detects if any violations occurred, and if so, prints
a message.

@exampleindent 1
@example
daikon.tools.runtimechecker.Runtime.resetViolations();
daikon.tools.runtimechecker.Runtime.resetErrors();

callMethod();

List<Violation> vs = daikon.tools.runtimechecker.Runtime.getViolations();

if (!vs.isEmpty())
  System.out.println("Violations occurred.");
@end example
@exampleindent 4

@noindent
In addition, the instrumenter adds the following two methods to the
instrumented class:

@itemize @bullet
@item
@code{isDaikonInstrumented()}.  Returns true (you could calling
this method to see if the class has been instrumented).

@item
@code{getDaikonInvariants()}.  Returns the array of properties being checked.
@end itemize


@node          Problems compiling instrumented code
@subsubsection Problems compiling instrumented code

When compiling the instrumented code, the Java compiler might emit an error
such as:

@example
  error: longitude has private access in GeoPoint
@end example

If you receive the error above, then a variable in an invariant
(@var{longitude} in this case) has been declared @code{private}.

There are two ways to fix this.  To check invariants that mention private
variables, supply the @option{--make_all_fields_public} command-line option
when running @samp{java daikon.tools.runtimechecker.Main instrument ...}.
To ignore invariants that mention private variables, rebuild the
@file{.dtrace} file by rerunning Chicory using the
@option{--std-visibility} command-line option.

Another error the Java compiler might emit is:

@example
  error: code too large for try statement
@end example

You get the above error if the combined size of the original source code,
plus the instrumentation code, is larger than the JVM's limit of 65536
bytes of bytecode per method.

You can correct the problem by using a smaller number of invariants when
instrumenting.  @xref{Too much output}.

(Eventually, it might be nice for the instrumenter to place its code in one or more separate methods so that no one of them is too large.)


@node       InvariantChecker
@subsection InvariantChecker

@cindex InvariantChecker tool

The @command{InvariantChecker} program takes a set of invariants found by Daikon
and a set of data trace files.  It checks each sample in the data trace
files against each of the invariants.  Any sample that violates an invariant
is noted, via a message printed to standard output or to a specified
output file.

@command{InvariantChecker} is invoked as follows:

@exampleindent 1
@example
java daikon.tools.InvariantChecker [@var{options}] @var{invariant-file} @var{dtrace-files}
@end example
@exampleindent 4

@noindent
The @var{invariant-files} are invariant files (@file{.inv}) created by
running Daikon.  The @var{dtrace-files} are data trace (@file{.dtrace})
files created by running the instrumented program.  The files may appear
in any order; the file type is determined by whether the file name
contains @file{.dtrace}, or @file{.inv}.

The options are:
@table @option

@item --help
Print usage message.

@item --output @var{output-file}
Write any violations to the specified file.

@item --conf
Checks only invariants that are above the default confidence level.

@item --filter
Checks only invariants that are not filtered by the default filters.

@item --verbose
Print all samples that violate an invariant.  By default only the totals
are printed.

@item --dir @var{directory-name}
Processes all invariant files in the given directory and reports the
number of invariants that failed on any of the @file{.dtrace} files in that
directory.  We only process invariants above the default confidence
level and invariants that have not been filtered out by the default
filters.

@item --config_option @var{name}=@var{value}
@itemx --dbg @var{category}
@itemx --track @var{class}<@var{var1},@var{var2},@var{var3}>@@@var{ppt}
These switches are the same as for Daikon.  They are described in
@ref{Running Daikon}.

@end table

@node       LogicalCompare
@subsection LogicalCompare

@cindex LogicalCompare tool
@cindex implication checking tool
@cindex comparison tool, logical

Suppose you have two sets of invariants describing the operation of a software
module or describing two implementations of a module with the same
interface.  Roughly, one set of invariants is ``stronger'' than
another if in any situation where the ``stronger'' invariants
hold, the ``weaker'' invariants also hold.  The @command{LogicalCompare} tool
checks whether two sets of invariants satisfy this relationship.

In order to use @command{LogicalCompare}, Simplify must be installed
(@pxref{Installing Simplify}).

An invocation of @command{LogicalCompare} has the following form:

@example
java daikon.tools.compare.LogicalCompare [@var{options}] \
    @var{weak-invs} @var{strong-invs} [@var{enter-ppt} [@var{exit-ppt}]]
@end example

The @command{LogicalCompare} program takes two mandatory arguments, which are
@file{.inv} files containing invariants.  @command{LogicalCompare}
checks whether the invariants in the first file are weaker
(implied by) the invariants in the second file.
@command{LogicalCompare} prints any exceptions to this implication,
preceded by the text ``Invalid:''.

To be precise, for each
pair of program points representing a single method or function,
@command{LogicalCompare} will check that each precondition (@code{:::ENTER} point
invariant) in the ``stronger'' invariant set is implied by some
combination of invariants in the ``weaker'' invariant set, and that
each postcondition (@code{:::EXIT} point invariant) in the ``weaker'' invariant
set is implied by some combination of postconditions in the
``stronger'' set and preconditions in the ``weaker'' set.

If no other regular arguments besides the two @file{.inv} files are supplied,
all the method or function program points that exist in both files
will be compared, with a exception message reported for each method
that exists in the ``weaker'' set but not the ``stronger''.
Alternatively, one or two additional arguments may be supplied, which name an
@code{:::ENTER} program point and an @code{:::EXIT} program point to examine
(if only an @code{:::ENTER} program point is supplied,
the corresponding combined @code{:::EXIT} point
is selected automatically).

@command{LogicalCompare} accepts the following options:

@table @option
@item --assume @var{file}
Read additional assumptions about the behavior of compared routines
from the file @var{file}.  The assumptions file should consist of lines
starting with @samp{PPT_NAME}, followed by the complete name of an
@code{:::ENTER} program point, followed by lines each consisting of a Simplify
formula, optionally followed by a @code{#} and a human-readable
annotation.  Blank lines and lines beginning with a @code{#} are
ignored.  The assumption properties will be used as if they were
invariants true at the strong @code{:::EXIT} point when checking
weak @code{:::EXIT} point invariants.

@item --config_option @var{option}=@var{value}
Specify a single configuration setting.  The available settings are the
same as can be passed to Daikon's @option{--config_option} option,
though because the invariants have already been generated, some will
have no effect.  For a list of
available options, see @ref{Configuration options}.

@item --config-file=@var{file}
Read configuration options from the file @var{file}.  This file should
have the same format as one passed to Daikon's @option{--config}
option, though because the invariants have already been generated,
some will have no effect.

@item --debug
@itemx --dbg @var{category}
These options have the same effect as the @option{--debug} and
@option{--dbg} options to Daikon, causing debugging logs to be
printed.

@item --filters=[bBoOmjpi]
Control which invariants are removed from consideration before
implications are checked.  Note that except as controlled by this
option, @command{LogicalCompare} does not perform any of the filters that
normally control whether invariants are printed by Daikon.  Also,
invariants that cannot be formatted for the Simplify automatic theorem
prover will be discarded in any case, as there would be no other way
to process them.  Each letter controls a filter: an invariant is rejected
if it is rejected by any filter (or, equivalently, kept only if it
passes through every filter).

@table @option
@item b
Discard upper-bound and lower-bound invariants
(such as @samp{x <= c} and @samp{x >= c} for a
constant c), when Daikon considers the constant to be uninteresting.
Currently, Daikon has a configurable range of interesting constant: by
default, -1, 0, 1, and 2 are interesting, and no other numbers are.

@item B
Discard all bound invariants, whether or not the constants in them are
considered interesting.

@item o
Discard @samp{one-of} invariants (which signify that a variable always
had one of a small set of values at runtime), when the values that the
variable took are considered uninteresting by Daikon.

@item O
Discard all @samp{one-of} invariants, whether or not the values involved
are interesting.

@item m
Discard invariants for which it was never the case that all the
variables involved in the invariant were present at the same time.

@item j
Discard invariants that Daikon determines to be statistically
unjustified, according to its tests.

@item p
Discard invariants that refer to the values of pass-by-value
parameters in the postcondition, or to the values of objects pointed
to by parameters in postconditions, when the pointer is not
necessarily the same as at the entrance to the method or function.
Usually such invariants reflect implementation details that would not
be visible to the caller of a method.

@item i
Discard implication invariants when they appear in @code{:::ENTER} program
points.
@end table

The default set of filters corresponds to the letters @option{ijmp}.

@item --help
Print a brief summary of available command-line options.

@item --no-post-after-pre-failure
If implication is not verified between two invariant sets after
examining the preconditions, do not continue to check the implication
involving postconditions.  Because the postconditions aren't formally
meaningful outside the domain specified by the preconditions, this is
the safest behavior, but in practice trivial precondition mismatches
may prevent an otherwise meaningful postcondition comparison.  See also
@option{--post-after-pre-failure}.

@item --proofs
For each implication among invariants that is verified, print a
minimal set of conditions that establish the truth of the conclusion.
The set is minimal, in the sense that if any condition were removed,
the conclusion would no longer logically follow according to Simplify,
but it is not the least such set: there may exist a smaller set of
conditions that establish the conclusion, if that set is not a subset
of the set printed.  Beware that because this option uses a naive
search technique, it may significantly slow down output.

@item --post-after-pre-failure
Even if implication is not verified between two invariant sets after
examining the preconditions, continue to check the implication
involving postconditions.  This is somewhat dangerous, in that if the
implication does not hold between the preconditions, the invariant
sets may be inconsistent, in which case reasoning about the
postconditions is formally nonsensical, but the tool will attempt to
ignore the contradiction and carry on in this case.  This is now the
default behavior, so the option has no effect, but it is retained for
backward compatibility.  See also @option{--no-post-after-pre-failure}.

@item --show-count
Print a count of the number of invariants checked for implication.

@item --show-formulas
For each invariant, show how it is represented as a logical formula
passed to Simplify.

@item --show-sets
Rather than testing implications among invariants, simply print the
sets of weak and strong @code{:::ENTER} and @code{:::EXIT} point invariants that would
normally be compared.  The invariants are selected and filtered as
implied by other options.

@item --show-valid
Print invariants that are verified to be implied (``valid''), as well
as those for which the implication could not be verified (``invalid''
invariants, which are always printed).

@item --timing
For each set of invariants checked, print the total time required for
the check.  This time includes both processing done by @command{LogicalCompare}
directly, and time spent waiting for processing done by Simplify, but
does not include time spent deserializing the @file{.inv} input
files.

@end table


@node    DtraceDiff utility
@section DtraceDiff utility

@command{DtraceDiff} is a utility for comparing data trace (@file{.dtrace}) files.
It checks that the same program points are visited in the same order in
both files, and that the number, names, types, and values of variables
at each program point are the same.  The differences are found using a
content-based, rather than text-based, comparison of the two files.

@command{DtraceDiff} stops by signaling an error when it finds a difference
between the two data trace files.  (Once execution paths have
diverged, continuing to emit record-by-record differences is likely to
produce output that is far too voluminous to be useful.)  It also
signals an error when it detects incompatible program point
declarations or when one file is shorter than the other.

@command{DtraceDiff} is invoked as follows:
@example
java daikon.tools.DtraceDiff [@var{flags}] \
   [@var{declsfiles1}] @var{dtracefile1}  [@var{declsfiles2}] @var{dtracefile2}
@end example

Corresponding declarations (@file{.decls}) files can optionally be
specified on the command line before each of the two @file{.dtrace}
files.  Multiple @file{.decls} files can be specified.  If no
@file{.decls} file is specified, @command{DtraceDiff} assumes that the
declarations are included in the @file{.dtrace} file instead.

@command{DtraceDiff} supports the following Daikon command-line flags:

@table @option
@item --help
Print usage message.

@item --config @var{filename}
Load the configuration settings specified in the given file.
@xref{Configuration options}, for details.

@item --config_option @var{name}=@var{value}
Specify a single configuration setting.
@xref{Configuration options}, for details.

@item --ppt-select-pattern=@var{ppt_regexp}
Only process program points whose names match the regular expression.

@item --ppt-omit-pattern=@var{ppt_regexp}
Do not process program points whose names match the regular expression.
This takes priority over the @option{--ppt-select-pattern} argument.

@item --var-select-pattern=@var{ppt_regexp}
Only process variables (whether in the trace file or derived) whose
names match the regular expression.

@item --var-omit-pattern=@var{var_regexp}
Ignore variables (whether in the trace file or derived) whose names
match the regular expression, which uses Perl syntax.  This takes
priority over the @option{--var-select-pattern} argument.

@end table

@command{DtraceDiff} uses appropriate comparisons for the type of the variables in
each program point being compared.  In particular:

@itemize @bullet
@item Hashcode (pointer or address) values may differ from one run of
the same program to the next, and there may not be a one-to-one mapping
of hashcode values between different program executions, so the
comparison function only looks for null versus non-null pointer values.

@item Floating-point values are subject to roundoff error from printing and
reading, so they are compared with a ``fuzzy'' rather than exact equality test.
@end itemize


@node    Reading dtrace files
@section Reading dtrace files

If you wish to write a program that manipulates @file{.dtrace} files, then
see @xref{Reading dtrace files,,,developer,Daikon Developer Manual}.


@node    Troubleshooting
@chapter Troubleshooting

@cindex troubleshooting
@cindex warning messages
@cindex error messages

This chapter gives solutions for certain problems you might have with
Daikon.  It also tells you how to report bugs in a useful manner.

If, after reading this section and other parts of the manual, you are
unable to solve your problem, you may wish to send mail to one of the
mailing lists (@pxref{Mailing lists}).

@menu
* Daikon problems::
* Large dtrace files::
* Chicory problems::
* Reporting problems::
* Further reading::
@end menu


@node    Daikon problems
@section Problems running Daikon

You may find the debugging flags @option{--debug} and @option{--dbg
@var{category}} useful if you wish to track down bugs or better
understand Daikon's operation; @pxref{Daikon debugging options}.
@xref{Configuration options}, for another way to adjust Daikon's output.


@menu
* Can't run Daikon::
* File input errors::
* decl format errors::
* Too much output::
* Missing output invariants::
* True invariants are not reported due to output filters::
* No samples::
* No return from procedure::
* Unsupported class version::
* Out of memory::
* Simplify errors::
* Contradictory invariants::
* Method needs to be implemented::
* Daikon runs slowly::
* Bigger traces cause invariants to appear::
@end menu

@c set reduced indent for all examples
@exampleindent 1

@node       Can't run Daikon
@subsection Can't run Daikon: could not find or load main class, or NoClassDefFoundError

Either of these errors:
@example
Error: Could not find or load main class daikon.Chicory
Exception in thread "main" java.lang.NoClassDefFoundError: daikon/Chicory
@end example

@noindent
means that you have not put @file{daikon.jar} on your classpath;
@pxref{Installing Daikon}.

More generally, an error such as one of these:
@example
Error: Could not find or load main class mypackage.MyClass
Exception in thread "main" java.lang.NoClassDefFoundError: mypackage/MyClass
@end example

@noindent
means that Java did not find the class @file{mypackage.MyClass} on your
classpath.  To correct the problem, you need to make sure that the
directory or jar file that contains file @file{mypackage/MyClass.class}
is on your classpath.
The classpath is passed as a command-line argument such as @option{-cp} or
@option{-classpath}; if no such command-line argument is passed, the
classpath is determined from your @env{CLASSPATH} environment variable.

When investigating such a problem, you should verify that you can run your
program when not using Daikon; for example, if you are trying to run
@command{java daikon.Chicory mypackage.MyClass arg1 arg2 arg3}, then make
sure that the identical command without @command{daikon.Chicory} works, in
this case @command{java mypackage.MyClass arg1 arg2 arg3}.  In most
cases, both commands issue the same error, which is unrelated to Daikon.
If the two commands behave differently, that is a bug in Daikon.


@node       File input errors
@subsection File input errors
@cindex file input errors

If Daikon terminates with an error such as
@example
Error at line 530 in file test.dtrace
@end example

@noindent
and inspection of the indicated file at the indicated line number does
not help you to discern what is wrong, you may wish to re-run Daikon with
the @option{show_stack_trace} option.  The exact syntax for this is:
@example
--config_option daikon.Debug.show_stack_trace=true
@end example
The additional information in the resulting exception stack trace
should indicate where the problem is occurring.


@node       decl format errors
@subsection decl format errors
@cindex decl format errors

If Daikon terminates with an error such as
@smallexample
decl format '2.0' does not match previous setting at line 4 in file test.dtrace
@end smallexample

@noindent
it means you are using multiple @file{.dtrace} and/or @file{.decls} files
and they are not all in the same format.
(See @ref{Declaration version,,,developer,Daikon Developer Manual}
for information about how to determine a data file's format.)

The most probable cause is you are using at least one
Java-DynComp-generated @file{.decls} file
(which defaults to version 1) and at least one @file{.dtrace} file (which
defaults to version 2) as input to Daikon.
(Note that the C/C++ front end Kvasir generates a version 2 file @file{.decls}.)
The way to
avoid this problem is to use your Java-DynComp-generated @file{.decls} files
as input to Chicory. The resulting @file{.dtrace} file will contain the
comparability values from the @file{.decls} file(s) and can then be used
as input to Daikon.
Passing a @file{.decls} file to Chicory is
described in @ref{Detecting invariants in Java programs}, for example:

@example
java daikon.Chicory --comparability-file=MyClass.decls-DynComp \
     mypackage.MyClass arg1 arg2 arg3
@end example


@node       Too much output
@subsection Too much output

@cindex too much output from Daikon
@cindex useless output from Daikon
@cindex irrelevant output from Daikon

Sometimes, Daikon may produce a very large number of seemingly
irrelevant properties that obscure the facts that you were hoping to
see.  Which properties are irrelevant depends on your current task, so
Daikon provides ways for you to customize its output.  See Daikon's
command-line options (@pxref{Running Daikon}), and the techniques for
enhancing its output (@pxref{Enhancing Daikon output}), including its
configuration options (@pxref{Configuration options}).  The options for
the front ends --- such as DynComp (@pxref{DynComp for Java options}),
Chicory (@pxref{Chicory options}) and Kvasir
(@pxref{Kvasir options}) --- give additional control.

Some irrelevant properties are over unrelated variables, like comparing
an array index to elements of the array.  You should always use the
DynComp tool (see @ref{DynComp for Java}, @ref{DynComp for C/C++}) to
avoid producing such properties.

Some irrelevant properties are not relevant to the domain (e.g., bitwise
operations).  You can exclude whole classes of unhelpful invariants from
Daikon's output (@pxref{Options to enable/disable specific invariants}).

Some irrelevant properties are over variables you do not care about, or
are in parts of the program that you do not care about.  You can exclude
certain variables or procedures from Daikon's output (see
@ref{Processing only part of the trace file} and @ref{Options to
enable/disable derived variables}).

Some irrelevant properties are logically redundant --- multiple
properties express the same facts in different ways.  You can eliminate
such properties from Daikon's output (@pxref{Options to control
invariant detection}).

Some irrelevant output indicates a deficiency in your test suite:
your test suite is so small that many arbitrary properties hold over it.
This happens when the test suite does not execute the code with a broad
distribution of values, but only executes the code with a few specific
values.  This problem disappears if you augment your test suite so that
it exercises the code with more different values.

More generally, each property that Daikon produces is a true fact about
how the target
program behaved.  However, some of these facts would be true for any
execution of the target program, and others are accidents of the
particular executions that Daikon observed.  Both types of facts may be
useful, but for different reasons:  the former tell you about your program,
and the latter tell you
about your test suite (and how to improve it!).


@node       Missing output invariants
@subsection Missing output invariants

Daikon may sometimes fail to output invariants that you expect it to output.
Here are some reasons why this may happen:

@itemize
@item There is a sample that violates the invariant
@item The invariant is true, but does not pass one of the output filters
(@pxref{True invariants are not reported due to output filters}).
@item One or more of the variables in the invariant always has the same
value as another variable.  Daikon only prints invariants over one
variable (the leader) from the set of equal variables (@pxref{Equal variables}).
@item The program point had no samples (@pxref{No samples}).
@end itemize

There are two command-line options (@option{--disc_reason} and @option{--track}) that
will display information about invariants that are not printed.  The
@option{--disc_reason} option will indicate why a particular invariant
was discarded in most cases.  If it does not provide enough
information, try the @option{--track} option which traces the invariant
through all of Daikon's processing steps.  See @ref{Daikon debugging
options} for more information.

Note that in each case the description (class, variables, program
point) of the invariant must be entered carefully.  It may be helpful
to try the option on a similar invariant that is printed to make sure
that each is specified correctly.


@node       True invariants are not reported due to output filters
@subsection True invariants are not reported due to output filters

Sometimes, Daikon does not report an invariant, even though Daikon has
computed that the invariant is true throughout the sample data. Daikon
only reports invariants that satisfy all the output filters
(@pxref{Invariant filters}).

Here, we discuss two common reasons for filtering:
statistical justification, and implication.

Daikon only reports a property if it is statistically justified, and
Daikon needs to see enough samples for the statistical test to work.
So, there may be a property that is true, but if too few samples were
seen, then Daikon will not report it.  In a longer trace, Daikon would
report the property.  You can adjust Daikon's confidence limit so that
the property is reported even in the short executions; see the
command-line option @option{--conf_limit}.  For instance, supplying
@option{--conf_limit 0} causes all properties that have not been falsified
to be printed.

Daikon does not report redundant, or implied, invariants
(@pxref{Redundant invariants}).  The purpose
of this is to avoid cluttering the output with facts that add no new
information.  Here are a few examples:
@itemize
@item
Suppose that both @code{i < j} and
@code{i <= j} are true.  Daikon would report
only @code{i < j}; Daikon would not report @code{i <= j}, which is
implied by what Daikon has reported.  Further suppose that a longer
execution had a sample containing @code{i=22, j=22}.  Only @code{i <= j}
would be true in the second execution, and Daikon would report it.
(The invariant @code{i < j} is an example of a false positive or
overfitting in the first execution.)
@item
If two or more variables are found to be equal, then Daikon chooses one
of them (the leader) and only prints invariants over the leader, not the
other variables (@pxref{Equal variables}).
@end itemize


@node       No samples
@subsection No samples and no output

@cindex no output from Daikon

When Daikon produces no output, that is usually a result of it having no
samples from which to generalize.  Use the @option{--output_num_samples}
flag to Daikon to find out how many samples it is observing.  This
section tells you how to debug your problem if the
answer is 0, but you believe that there are samples in the file you are
feeding to Daikon.

Using the normal dataflow hierarchy, Daikon explicitly processes
@code{:::EXIT} and @code{:::EXCEPTION} program points only. Other program points, such as
@code{:::ENTER} program points, are processed indirectly when their
corresponding @code{:::EXIT} or @code{:::EXCEPTION} points are encountered.
(You can disable this behavior with the
@option{--nohierarchy} switch to Daikon;
see @ref{Options to control invariant detection}.)
If no @code{:::EXIT} or @code{:::EXCEPTION} program points are present (perhaps every
execution threw an exception, you filtered out all the
@code{:::EXIT} and @code{:::EXCEPTION} program points, or the data trace is obtained from
spreadsheet data instead of from a program execution),
then Daikon will not process any of the other program points, such as
the @code{:::ENTER} program points.  You can make Daikon print information
about unmatched procedure entries
via the @samp{daikon.FileIO.unmatched_procedure_entries_quiet}
configuration option (@pxref{General configuration options}).

Another way to increase the number of invariants printed
out is to lower the confidence bound cutoff.  Daikon
only prints invariants whose confidence level is greater than
the bound specified by the @option{--conf_limit} option
(@pxref{Options to control invariant detection}).  In order to maximize
the number of invariants printed, use @option{--conf_limit 0} to see all
invariants Daikon is considering printing.

To try to determine why an invariant is not printed, use the
@option{--track} to determine why Daikon does not print an invariant
(@pxref{Daikon debugging options}).


@node       No return from procedure
@subsection No return from procedure

@cindex no return from procedure, warning
@cindex return from procedure, warning

Daikon sometimes issues a warning that a procedure in the target program
was entered but never exited (that is, the target program abnormally
terminated).  In other words, the @file{.dtrace} file contains more
entry records
than exit records for the given procedure.  Some procedures that were
entered were never recorded to have exited: either they threw an
exception, skipping the instrumentation code that would have recorded
normal termination, or the target program's run was interrupted.
When this happens, the entry sample is ignored; the rationale is that
the particular values seen led to exception exit, were probably
illegal, and so should not be factored into the method preconditions.

@cindex invocation nonce
@cindex nonce, invocation
@cindex this_invocation_nonce

In some cases, exceptional exit from a procedure can cause procedure
entries and exits (in the trace file) to be incorrectly matched up; if
they are incorrectly matched, then the @code{orig(@var{x})} values may
be incorrect.  Daikon has two techniques for associate procedure exits
with entries --- the nonce technique and the stack technique.  If a
@file{.dtrace} file uses the nonce technique, @code{orig(@var{x})}
values are guaranteed to be correct.  If a @file{.dtrace} file uses
the stack technique, then incorrect @code{orig(@var{x})} values are
likely to occur.  You can tell which technique Daikon will use by
examining the @file{.dtrace} file.  If the second line of each entry
in the @file{.dtrace} file is @samp{this_invocation_nonce}, then Daikon
uses the nonce technique.  Otherwise, it uses the stack technique.
Which technique is used is determined by the front end, which creates
the @file{.dtrace} file, and typically cannot be controlled by the
user.


@node       Unsupported class version
@subsection Unsupported class version

@cindex UnsupportedClassVersionError
@cindex java.lang.UnsupportedClassVersionError
@cindex major.minor version error

Daikon requires a Java 7 (or newer) JVM (@pxref{Requirements}).
An error such as
@example
Exception in thread "main" java.lang.UnsupportedClassVersionError:
daikon/Daikon (Unsupported major.minor version 51.0)
@end example

@noindent
indicates that you are trying to run Daikon on an older JVM.  You need to
install a newer version of Java in order to run Daikon.


@node       Out of memory
@subsection Out of memory

@cindex out of memory error
@cindex java.lang.OutOfMemoryError
@cindex memory exhaustion
@cindex HotSpot JVM
@cindex JVM memory management
@cindex permanent generation (in HotSpot JVM)

If Daikon runs out of memory, generating a message like
@example
Exception in thread "main" java.lang.OutOfMemoryError
    <<no stack trace available>>
@end example

@noindent
then it is likely that it has created more invariants than will fit
in memory.  The number of invariants created depends on the number of
program points and the number of variables at each program point.
In addition to the solutions discussed in @ref{Reducing program points},
you can try increasing the amount of memory available to Java
with the @option{-Xmx} argument to @command{java}.  (This flag is
JVM-specific; see your JVM documentation for details.  For instance,
its name in JDK versions 1.2 and earlier is @option{-mx}.)
However, the value you use should be less than your system's total amount
of physical memory.
Some implementations of Java use a surprisingly small default, such as 64
megabytes; to permit use of up to 2048
megabytes, you would run Java like so:
@example
java -Xmx2048m ...
@end example
@noindent
though you can use much more depending on the limitations of your JVM.

If you are using Chicory's @option{--daikon} command-line argument to
run Daikon, then you must separately indicate the amount of memory
available to Chicory and to Daikon (the latter with Chicory's
@option{--heap-size} command-line argument).  For example:
@example
java -Xmx256m daikon.Chicory --comparability-file=MyClass.decls-DynComp \
     --heap-size=1600m --daikon mypackage.MyClass arg1 arg2 arg3
@end example

When using the Java @command{HotSpot} JVM, an additional parameter may need to
be increased.  @command{HotSpot} uses a separately-limited memory region, called
the @dfn{permanent generation}, for several special kinds of allocation,
one of which (interned strings) Daikon sometimes uses heavily.  It may
be necessary to increase this limit as well, with the
@option{-XX:MaxPermSize=} option.  For instance, to use 512 megabytes,
of which at most 256 can be used for the permanent generation, you
would run Java like so:
@example
java -Xmx512m -XX:MaxPermSize=256m
@end example

Another possible problem is the creation of too many derived variables.
If you supply the @option{--output_num_samples} option to Daikon
(@pxref{Options to control Daikon output}), then it will list all
variables at each program point.  If some of these are of no interest,
you may wish to suppress their creation.  For information on how to do that,
see @ref{Options to enable/disable derived variables}.  Also see
@ref{Reducing variables} for other techniques.

Any output generated before the out-of-memory error is perfectly valid.


@node       Simplify errors
@subsection Simplify errors

@cindex Simplify, could not utilize
@cindex Simplify, couldn't start

The warning @samp{Could not utilize Simplify}
and/or @samp{Couldn't start Simplify} indicates that the Simplify
theorem-prover could not be run; this usually indicates that the
Simplify binary was not found on the user's path.

If Simplify is not used, certain redundant (logically implied)
invariants may appear in Daikon's output.  The output is
correct, but more verbose than it would be if you used Simplify.

@menu
* Installing Simplify::
@end menu


@node          Installing Simplify
@subsubsection Installing Simplify

@cindex Simplify, installing

@c File http://www.hpl.hp.com/downloads/crl/jtk/simplify.tar.z
@c is dated Nov 16 2004 (as of Mar 30 2015).

Obtain Simplify from
@uref{http://kindsoftware.com/products/opensource/archives/Simplify-1.5.5-13-06-07-binary.zip},
and unzip the zip file.

Either place the appropriate binary on your path, named @command{Simplify},
or set set the @code{simplify.path} property to its absolute pathname.

Note:  Older versions of the @command{Z3} theorem
prover (@uref{https://archive.codeplex.com/?p=z3})
can replace Simplify, but more recent versions do not support the Simplify
syntax.  In the future, it would be nice to rewrite Daikon's theorem-prover
interface to use the @nospellcheck{SMT-LIB2} language, so that a compatible
solver like @command{Z3} or @command{CVC4} could be used.
The main challenge to this is writing the
boilerplate code to output each different kind of invariant in
@nospellcheck{SMT-LIB2} format.


@node       Contradictory invariants
@subsection Contradictory invariants

@cindex contradictory invariants
@cindex inconsistent invariants
@cindex invariants, inconsistent
@cindex invariants, contradictory

The invariants Daikon produces are all true statements about the
supplied program executions, so they should be mutually consistent.
Sometimes, however, because of a bug or a limitation in Daikon,
contradictory invariants are produced.

One known problem involves object invariants.  Daikon infers object
invariants by observing the state of an object when its public methods
are called.  However, if an object has publicly accessible fields that
are changed by code outside the class, after which no public methods
are called, invariants about the state of the object as seen by other
code can contradict the class's object invariants.  A workaround is to
allow changes to an object's state from outside the class only by
way of public methods.

Besides confusing the user, contradictory invariants also cause
trouble for the Simplify theorem prover that implements the
@option{--suppress_redundant} option.  When the invariants at a
particular program point contradict each other or background
information (such as the types of objects), Simplify becomes unable to
distinguish redundant invariants from non-redundant ones.

The best solution in such cases is to fix the underlying cause of the
contradictory invariants, but since that is sometimes not possible,
Daikon will try to work around the problem by avoiding the invariants
that cause a contradiction.  Daikon will attempt to find a small subset
of the invariants that aren't mutually consistent, and remove one,
repeating this process until the remaining invariants are consistent.
(Note that the invariants are removed only for the purposes of
processing by Simplify; this does not affect whether they will be
printed in the final output).  While this technique can allow
redundant invariants to be found when they otherwise wouldn't be, it
has some drawbacks: the choice of which invariant to remove is
somewhat arbitrary, and the process of finding contradictory subsets
can be time consuming.  The removal process can be disabled with the
@option{daikon.simplify.LemmaStack.remove_contradictions}
configuration option.

@node       Method needs to be implemented
@subsection Method needs to be implemented

@cindex method needs to be implemented warning
@cindex needs to be implemented warning

Daikon may produce output like the following (but all on one line):
@example
method daikon.inv.binary.twoSequence.SubSequence.format_esc()
needs to be implemented:
this.theArray[0..this.topOfStack] is a subsequence of
orig(this.theArray[0..this.topOfStack])
@end example

@noindent
This indicates that a particular invariant (shown on the last two lines
above) cannot be formatted using the current formatting.  In this example,
the invariant can be formatted using Daikon's default
formatting (which is how it is shown above), but (as of April 2002)
Daikon cannot output it in @option{ESC} format, so Daikon prints the above
message instead.  The message also shows exactly what Java method needs
to be implemented to correct the problem.  You can ignore such messages,
or else use an output formatting that can handle those invariants.
Annotate (@pxref{Annotate}) automatically ignores unformattable invariants.


@node       Daikon runs slowly
@subsection Daikon runs slowly

@cindex slow operation, of Daikon
@cindex runtime, of Daikon

If Daikon runs slowly, there are three general possible reasons:
@itemize
@item
You did not use the DynComp tool to generate comparability sets.
Without DynComp, Daikon typically runs more than an order of magnitude slower.

@item
The front end, such as DynComp or Chicory, took a long time to collect, then output,
large amounts of data about your program execution.

@item
It took a long time to analyze that data trace and infer invariants over
it.
@end itemize

To understand which part is the bottleneck, you might want to separate the
creation and analysis of the trace file, so you can compare the time of
each part.
The next two sections address each of these issues.

You may find command-line arguments like the following useful when
debugging Daikon's performance:
@example
   --config_option daikon.Daikon.progress_delay=100
   --show_progress --dbg daikon.init
@end example

For additional details on improving Daikon's performance, see @ref{Out of
memory}.


@subsubsection Slow creation of large trace files
@cindex large trace files, creating

Creating a trace can take a long time, because of the time to traverse and
print the values of many variables.  Reducing the number of program points
or variables can speed up both creation and analysis of trace files.  For
instance, you might configure your front end to skip certain procedures
(helper procedures, libraries) or not to output certain variables (large
arrays or static variables).
For details, see @ref{Large dtrace files}.


@subsubsection Slow inference of invariants
@cindex large trace files, creating

Daikon's runtime and space depend on the particular data that it analyzes.
Informally, invariant detection time can be characterized as
@example
O((@var{vars}^3 * @var{falsetime} + @var{trueinvs} * @var{testsuite}) * @var{procedures})
@end example

@noindent
where @var{vars} is the number of variables @emph{at a program point},
@var{falsetime} is the (small constant)
time to falsify a potential invariant,
@var{trueinvs} is the (small) number of
true invariants at a program point,
@var{testsuite} is the size of the test
suite, and
@var{procedures} is the number of instrumented program points.  The first
two products multiply a number of invariants by the time to test each
invariant.

If there are many true invariants over an input, then Daikon continues
to check them all over the entire input.  By contrast, if not many
invariants are true, then Daikon need no longer check them once they
are falsified (which in practice happens quickly).  Daikon processes
each procedure independently.

Another important factor affecting Daikon's runtime is the number of
variables.  Because invariants involve up to three variables each, the
number of invariants to check is cubic in the number of variables at a
single program point.  Derived variables (such as @code{a[i]},
introduced whenever there is both an array @code{a} and an integer
@code{i}) can increase the number of variables substantially.
The @option{daikon.derive.Derivation.disable_derived_variables} and individual
@option{daikon.derive.*.*.enabled} configuration variables
(@pxref{Options to enable/disable derived variables}) may be used
to disable derived variables altogether or selectively, at the cost of
detecting fewer invariants, especially over sequences.


@node       Bigger traces cause invariants to appear
@subsection Bigger traces cause invariants to appear

Suppose that you run Daikon twice.  The first time, you supply Daikon
with traces @i{T}.  The second time you supply Daikon with traces
@i{T+T@quoteright{}}:  either more files, or file(s) that are supersets of the
original one(s).  The second Daikon execution may report fewer
invariants, more invariants, or a mix.

The second execution may report @strong{fewer} invariants, because the
additional data has eliminated overfitting (false positives).  There may
have been some accidental property of the shorter executions that is not
true in the longer ones.

Even though fewer invariants are true on the second execution, Daikon may
report invariants that it did not report on the first execution.
The invariants were true on the first execution, but were not reported
by Daikon.  @ref{True invariants are not reported due to output filters} describes why this
might happen.


@node    Large dtrace files
@section Large data trace (.dtrace) files


@cindex data trace files, too large
@cindex large data trace files

Running instrumented code can create very large @file{.dtrace} files.
This can be a problem because writing the large files can slow the
target programs substantially, or because the large files may fill up
your disk.

This section describes ways to work around this problem.


@menu
* Compression::
* Scratch directory::
* Run Daikon online::
* Multiple smaller files::
* Less information per file::
@end menu


@node       Compression
@subsection Compressed .dtrace files

You can reduce file size by specifying a trace file name that includes
@file{.gz} at the end.  See the @option{--dtrace-file=FILENAME} argument
to Chicory or Kvasir, or the @env{DTRACEFILE} environment variable.
(Compression is the default if you don't specify a filename.)


@node       Scratch directory
@subsection Save large files in a scratch directory

Sometimes, the problem is just filling up your user account with large
files.  You can instead create @file{.dtrace} files in a temporary directory.
Under Linux, this is often called @file{/scratch}.  Typically you should
create a subdirectory called @file{/scratch/$USER/}.


@node       Run Daikon online
@subsection Run Daikon online

The term @dfn{online execution} refers to running Daikon at the same time
as the target program.  The front end supplies information to Daikon
directly over a socket or pipe, without writing any information to a
file.  This can avoid some I/O overhead, and it prevents filling up your
disk with files.

The Chicory front end supports online execution via use of the
@option{--daikon-online} option (@pxref{Chicory miscellaneous options}).
The Kvasir front end supports online execution via use of (normal or
named) Linux pipes (@pxref{Online execution}).

In the future, Daikon may be able to output partial results as the
target program is executing.


@node       Multiple smaller files
@subsection Create multiple smaller data trace files

It is usually possible to create an @file{.inv} file equivalent to
the one that Daikon would have computed, had Daikon been able to
process your entire program over its full test suite.  First, use the
techniques below (@pxref{Reducing program points}) to split your
@file{.dtrace} file into parts.  Next, run Daikon on each resulting
@file{.dtrace} file.  Finally, use the @command{MergeInvariants} tool
to combine the resulting @file{.inv} files into one.


@node       Less information per file
@subsection Record or read less information in the data trace file

You can record less information from each program execution, or you can
make Daikon read less information from the trace files.  It's usually
most efficient to do the pruning as early in the process as possible.
For example, it is better to have the front end output less information,
rather than have Daikon ignore some of the information.


@menu
* Reducing program points::
* Reducing variables::
* Reducing executions::
@end menu


@node       Reducing program points
@subsubsection Reducing program points (functions)

Here are ways to compute invariants over a subset of the program
points (functions) in your program.
@enumerate
@item
Make your front end instrument fewer files.  This is often most
applicable if you are using a source-based front end.

@item
You can instrument fewer procedures.
@itemize
@item With Chicory, use the @option{--ppt-omit-pattern} or
@option{--ppt-select-pattern} options (see @ref{Processing only part of
the trace file}, or @ref{Chicory options}) to
restrict which program points are traced.  Running the
instrumented program will result in a smaller @file{.dtrace} file that
contains fewer records.
@item With Kvasir, use the @option{--ppt-list-file} option to specify a list
of program points that should be traced (@pxref{Tracing only part of a
program} section for more details).
@c @item With dfec, split your program into multiple files, then
@c instrument only some of them (see below).

@item
@cindex trace-purge-fns.pl script
You can remove some program points (functions) from your
@file{.dtrace} file.  The @command{trace-purge-fns.pl} script takes as
arguments a (Perl) regular expression and a list of files.  It
modifies each file in place, removing every program point (function)
whose name matches the regular expression.  The @option{-v} flag means
to retain rather than discard matching program points.  For instance,
to create two subparts of a @file{.dtrace} file --- one containing the
getters and setters, and the other containing all other functions ---
use the following commands:
@example
cp myprog.dtrace myprog-setters.dtrace
trace-purge-fns.pl -v 'set|get' myprog-setters.dtrace
cp myprog.dtrace myprog-non-setters.dtrace
trace-purge-fns.pl 'set|get' myprog-non-setters.dtrace
@end example

@item
You can make Daikon ignore some program points.  With the
@option{--ppt-select-pattern@/=@var{ppt_regexp}}
flag (@pxref{Processing only part of the trace file}),
only program points matching
the regular expression are processed.  Likewise, the
@option{--ppt-omit-pattern=@var{ppt_omit_regexp}} option causes program points
matching the regular expression to be ignored.

Also, the configuration variable @option{daikon.Daikon.ppt_perc}
allows a percentage of the program points to be processed.
@xref{General configuration options}, for details.

@end itemize

@end enumerate

@node       Reducing variables
@subsubsection Reducing variables

Here are ways to compute invariants over a subset of the variables in
your program.  This changes the resulting invariants, because
invariants over the missing variables (including any relationship
between a missing variable and a retained variable) are not detected
or reported.  For instance, you might remove uninteresting variables
(or ones that shouldn't be compared to certain others) or variables
that use a lot of memory (such as some arrays).

@enumerate

@item
You can reduce the number of variables that are output by instrumented
code --- for instance, output @samp{a} and @samp{a.b} but not
@samp{a.b.c}.  Do this by reducing the class/structure instrumentation
depth.
@itemize
@item With Chicory, use the @option{--nesting-depth=@var{N}} option.
@item With Kvasir, use the @option{--struct-depth=@var{N}} or the
@option{--nesting-depth=@var{N}} option.
@end itemize

@item
With Kvasir, you can either ignore all global and/or static variables with the
@option{--ignore-globals} and @option{--ignore-static-vars} options or manually
specify a subset of variables to trace using the
@option{--var-list-file} option (@pxref{Tracing only part of a program}
for details)

@item
You can pare down an existing @file{.dtrace} file using the
@command{trace-purge-vars.pl} script.  Analogously to the
@command{trace-purge-fns.pl} script, it removes certain variables from
all program points in a function (or retains them, with the
@option{-v} flag).  After running this command, you will need
to edit the corresponding @file{.decls} file by hand to remove the
same variables.

@item
You can make Daikon ignore certain variables rather than modifying
the @file{.dtrace} file directly.  Analogously with the
@option{--ppt-select-pattern} and @option{--ppt-omit-pattern} flags, the
@option{--var-select-pattern} and @option{--var-omit-pattern} flags
restrict which variables Daikon processes.
(@xref{Processing only part of
the trace file}, and @ref{Chicory options}).

@end enumerate

@node       Reducing executions
@subsubsection Reducing executions

Here are ways to run Daikon over fewer executions of each program
point.  (You cannot combine the resulting invariants in order to
obtain the same result as running Daikon over all the executions.)

@enumerate
@item
If you have multiple @file{.dtrace} files (perhaps resulting from
multiple program runs), you can run Daikon on just some of them.

@item
@cindex trace-untruncate program
You can terminate the instrumented program when it has created a
sufficiently large @file{.dtrace} file.  If you interrupt the program
while it is in the middle of writing a record to the @file{.dtrace}
file, the last record may be only partially written.  Use the
@command{daikon/scripts/trace-untruncate} program to remove the last,
possibly partial, record from the file:
@example
trace-untruncate myfile.dtrace
@end example

@noindent
modifies @file{myfile.dtrace} in place to remove the last record.

Alternately, you can use the
@command{daikon/scripts/trace-untruncate-fast} program.  It operates much
faster on very large files.  In order to use
@command{trace-untruncate-fast}, you must have already compiled it
(@pxref{Installing Daikon}).

@item
You can cause the front end to record only a subset of executions of a
given procedure,
rather than every execution.  For example, Chicory's
@option{--sample-start} command-line option does this (@pxref{Chicory
miscellaneous options}).

@end enumerate


@node    Chicory problems
@section Problems with Chicory

Before reporting or investigating a problem with Chicory, always check
that the program executes properly when not being run under Chicory's
control.

For example, if a command such as
@example
java daikon.Chicory DataStructures.StackArTester
@end example

@noindent
fails with an error, then first try
@example
java DataStructures.StackArTester
@end example

@itemize
@item
If the latter command also fails, the problem is not with Chicory.
First solve your Java problem,
then once again attempt to use Chicory.
@item
If the latter command does not fail, then you have found a bug in
Chicory; please report it if it is not already explained in this manual.

(If the error is ``couldn't find or load main class'' and the
class that cannot be found is in Chicory itself, then there is not a bug in
Chicory.  Rather, you have failed to put @file{daikon.jar} on the classpath
when running Chicory, as described in @ref{Installing Daikon}.)
@end itemize


@menu
* BCEL must be in the classpath::
* VerifyError constant pool index error::
* ClassFormatError LVTT entry does not match::
* Attempted duplicate class definition error::
@end menu

@node       BCEL must be in the classpath
@subsection BCEL must be in the classpath
@cindex BCEL error, when running Chicory

If Chicory throws an error such as the following:
@smallexample
BCEL must be in the classpath.  Normally it is found in daikon.jar.
@end smallexample

@noindent
then the problem is most likely that your classpath does not contain
daikon.jar.  If you are running a Daikon version after 5.2.20, then it
could be caused by your classpath containing a previous version of
daikon.jar.

@node       VerifyError constant pool index error
@subsection VerifyError constant pool index error

@cindex VerifyError, when running Chicory
@cindex java.lang.VerifyError, when running Chicory
@cindex illegal constant pool index error, when running Chicory
@cindex constant pool index error, when running Chicory

If Chicory throws an error such as the following:
@smallexample
Exception in thread "main" java.lang.VerifyError:
  (class: ps1/PublicTest, method: <init> signature: (Ljava/lang/String;)V)
  Illegal constant pool index
@end smallexample

@noindent
then the problem is most likely that your classpath contains a version
of the BCEL library that is not compatible with Java 7.  The
incompatible version might appear in @file{bcel.jar}, in Java's
@file{rt.jar}, or elsewhere.  You should either remove that version of
BCEL from your classpath, or you should ensure that it appears after
@file{daikon.jar}, which contains the correct version of BCEL@.  (If you
are running Daikon from sources rather than from @file{daikon.jar}, then
ensure that @file{$DAIKONDIR/java/lib/bcel.jar} is the first version of
BCEL on your classpath.)

@node       ClassFormatError LVTT entry does not match
@subsection ClassFormatError LVTT entry does not match

@cindex ClassFormatError, when running Chicory
@cindex java.lang.ClassFormatError, when running Chicory
@cindex LVTT entry does not match

If Chicory throws an error such as the following:
@smallexample
Exception in thread "main" java.lang.ClassFormatError:
  LVTT entry for 'v' in class file javautil/ArrayList17 does not match any LVT entry
@end smallexample

@noindent
then the problem is most likely that your classpath contains a version
of the BCEL library that is newer than the 6.0 Release.  A modification
was made to Apache BCEL after the 6.0 release that causes this problem.
The incompatible version might appear in @file{bcel.jar}, in Java's
@file{rt.jar}, or elsewhere.  You should either remove that version of
BCEL from your classpath, or you should ensure that it appears after
@file{daikon.jar}, which contains the correct version of BCEL@.  (If you
are running Daikon from sources rather than from @file{daikon.jar}, then
ensure that @file{$DAIKONDIR/java/lib/bcel.jar} is the first version of
BCEL on your classpath.)

@node       Attempted duplicate class definition error
@subsection Attempted duplicate class definition error

@cindex LinkageError, when running Chicory
@cindex java.lang.LinkageError, when running Chicory
@cindex attempted duplicate class definition error, when running Chicory

If Chicory throws an error such as the following:
@smallexample
Exception in thread "main" java.lang.LinkageError:
java.lang.LinkageError: loader (instance of  sun/misc/Launcher$AppClassLoader):
attempted duplicate class definition for name: "SquarePanel"
@end smallexample

@noindent
then the problem is most likely that some method in your program uses
Java runtime services to set up an additional thread that can get
invoked asynchronously. One example is using the @code{java.lang.SecurityManager}
class to set up a @code{SecurityManager} via @code{System.setSecurityManager}.  The easiest
way to work around this is to use the @option{--ppt-omit-pattern} option to Chicory.
After you have located the problem method, rerun Chicory with the additional
option:
@smallexample
--ppt-omitpattern=MyPackage.MyProblemMethod
@end smallexample


@c @node    Eclipse plug-in problems
@c @section Problems with Eclipse plug-in
@c
@c @cindex Eclipse plug-in, troubleshooting
@c
@c If you have trouble with the Eclipse plug-in, one good way to debug the
@c difficulty is to run the command-line tools (because the plug-in does
@c nothing more than run those tools for you).  If the command-line
@c versions work properly, then you have isolated the bug to the plug-in.
@c If the command-line versions do not work properly, then you can submit a
@c more specific bug report that is easier for the developers to reproduce
@c and correct.


@node    Reporting problems
@section Reporting problems

@cindex reporting bugs
@cindex bugs, reporting
@cindex reporting problems
@cindex problems, reporting

If you have any questions, can suggest ways to improve the
documentation, find bugs in the system, or have suggestions for its
improvement, please file a bug report at
@uref{https://github.com/codespecs/daikon/issues} or send email to
@email{daikon-developers@@googlegroups.com}.  (If you can't figure
out how to do something or do not understand why Daikon works the way it
does, that is a bug, too --- in the Daikon documentation.  Please report
those as well.)
We will try to assist you and to correct any
problems, so please don't hesitate to ask for help or report
difficulties.  Additionally, if you can contribute enhancements or bug
fixes, those will be gratefully accepted.

In order for us to assist you, please provide a complete and useful bug
report.  Your bug report must provide all the information that is
required in order to replicate the bug and verify that our fix corrects
the problem.  If you do not provide complete information, we will not be
able to assist you.

Your bug report should include:
@itemize @bullet
@item
the version of Daikon, which appears in the file @file{daikon/README.txt}
and is also printed when you run Daikon.
@c ; also, whether you are running
@c from the @file{.class} files or from the @file{.jar} file.
If you are not using the most recent version, download a newer version
from @uref{http://plse.cs.washington.edu/daikon/} to see whether your problem
has already been corrected.
If you are using a modified version of Daikon, you should verify that
the problem exists in Daikon as distributed.
@item
a description of exactly what you did (in sufficient detail for others
to reproduce the problem), exactly what happened, and what
you expected to happen instead.
One good way to describe what you did is a list of
commands that, if executed, reproduces your error.  A good way to show
what happened is a transcript of execution of all of the commands.  (A
list of commands and a transcript are @strong{much} more useful than a
vague description; please don't give vague English when you can supply a
more precise specification instead.  Also, please don't give screenshots
of a command terminal, which are hard to read and reproduce; instead, cut
and paste the contents.)
It is crucial that you not omit
steps in your report.  For example, include instructions for installing
your software and all customizations to the software or your
environment, including all relevant environment variables.  Please do
not force the
developers to speculate about what you did; that would be a waste of their
time, since you already have the knowledge.
@item
input files that permit the problem to be replicated (by following the
detailed steps in your bug report).  The
most important thing is the original, uninstrumented source files (e.g.,
@file{.java}), and any inputs/tests used when you ran the program.
It is also helpful to include instrumented source files,
@file{.decl} files, and @file{.dtrace} files.
You may include @file{.inv} files, but as an adjunct rather than a
replacement for other files:  @file{.inv} files are binary in
format, hard to inspect, and the format may change from one version of
Daikon to another.
@item
the JDK or JRE version (e.g., the complete output of @samp{java
-version}), and operating system and revision you are using (e.g.,
Debian stable, Windows @nospellcheck{XP} service pack 2, etc)
@item
any other information that you consider relevant.
@end itemize

When users provide an inadequate bug report,
it is frequently more difficult for us to reproduce an error than to correct
it.  If you make it easy for us to reproduce and verify the problem, then it is
much more likely to be corrected.  Thanks for helping us to help you!

You may also wish to take advantage of the Daikon mailing lists
(@pxref{Mailing lists}).


@node    Further reading
@section Further reading

More information on Daikon can be found in the @cite{Daikon Developer Manual}
(@pxref{Top, , Introduction, developer, Daikon Developer Manual}).
For instance, the @cite{Daikon Developer Manual} indicates how to extend
Daikon with new invariants, new derived variables, and front ends for
new languages.  It also contains information about the implementation
and about how to debug.

You may find discussions on the mailing lists (@pxref{Mailing lists})
helpful.  The mailing list archives may contain helpful information, but
we strive to incorporate that information in this manual so that you
don't have to search the archives as well.

For further reading, see the list of publications at the
Daikon homepage, @uref{http://plse.cs.washington.edu/daikon/pubs/}.


@node    Details
@chapter Details

The Daikon invariant detector is named after an Asian radish.
``Daikon'' is pronounced like the combination of the two one-syllable
English words ``die-con''.

More information on Daikon can be found in the @cite{Daikon Developer Manual}
(@pxref{Top, , Introduction, developer, Daikon Developer Manual}).
For instance, the @cite{Daikon Developer Manual} indicates how to extend
Daikon with new invariants, new derived variables, and front ends for
new languages.  It also contains information about the implementation
and about debugging flags.


@menu
* History::
* License::
* Mailing lists reminder::
* Credits::
* Citing Daikon::
@end menu

@node    History
@section History
@cindex history of Daikon

This manual describes Daikon version 5.6.7, released July 2, 2018.
A more detailed list of revisions since mid-2001 can be found in file
@url{CHANGES,,@file{doc/CHANGES}}
in the distribution; this section gives a
high-level view of the package's history.

There have been four major releases of Daikon, with different features
and capabilities.  User experiences and technical papers should be
judged based on the version of Daikon current at the time of use.

@cindex Lisp front end
@cindex front end for Lisp
@c @cindex loop heads, instrumenting
@c @cindex instrumenting loop heads
@cindex Python implementation of Daikon
@cindex Daikon version 5.6.7

Daikon 1 was written in the Python programming language in 1998.  It included
front ends for C, Java, and Lisp.  The C front end was extremely limited
and failed to operate correctly on all C programs:  sometimes it
suffered a segmentation fault while instrumenting a target program, and even
when that did not happen, sometimes the instrumented program
segmentation-faulted while running.  The Lisp front end operated
correctly on all Lisp programs, but only instrumented certain common
constructs, leaving other language features uninstrumented.  The Java front
end was reasonably reliable.  The Lisp front end instrumented procedure
entries, exits, and loop heads; the C front ends instrumented only
procedure entries and exits; and the Java front end instrumented program
points for object invariants as well as procedure entries and exits.
Daikon 1 and its Lisp front end were only removed from Daikon version
control repository in November 2010, though they had long been obsolete.

Daikon 2 was a complete rewrite in the Java programming language and was
the first version to contain a substantive manual.  Daikon 2 uses the
same source-based Java front end as did Daikon 1, though with certain
enhancements.  Its C front end was rewritten from scratch; it
instruments only procedure entries and exits.  A front end also exists
for the Input Output Automaton programming language, but is not included in the Daikon
distribution.

Daikon 3 is a redesign of the invariant detection engine to work
incrementally --- that is, to examine each sample (execution of a
program point) once, then discard it.  By contrast, Daikon 1 and
Daikon 2 made multiple passes over the data.  This simplified their
algorithms but required storing all the data in memory at once, which
was prohibitive, particularly since data trace files may be gigabytes
in size.  Daikon 3 also introduces the idea of a @emph{dataflow
hierarchy}, a way to relate and connect program points based on their
variables.

Daikon 4 includes new binary front ends for Java and for C@.  These front
ends make Daikon much easier to use.  Daikon 4 makes @file{.decls} files
optional; program point declarations are permitted to appear in
@file{.dtrace} files.  Daikon 4 is released under more liberal licensing
conditions that place no restrictions on use.

Daikon 5 adds a new front end (Celeriac) for .NET languages (C#, F#,
and Visual Basic).  The underlying Valgrind was updated and much work done
to ensure Daikon works properly on the latest versions of Linux.  The
Chicory front end for Java was modified to support Java 7.  Daikon
releases were moved from MIT to the University of Washington.
The bug tracker was moved to Google Code, and mailing lists moved to Google
Groups.


@node    License
@section License

@cindex license

Copyright @copyright{} 1998-2008 Massachusetts Institute of Technology

Copyright @copyright{} 2008-2014 University of Washington

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
``Software''), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

The names and trademarks of copyright holders may not be used in
advertising or publicity pertaining to the software without specific prior
permission. Title to copyright in this software and any associated
documentation will at all times remain with the copyright holders.

THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NON INFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE@.

@menu
* Library licenses::
* Front end licenses::
@end menu


@node    Library licenses
@subsection Library licenses

@menu
* getopt license::
* JUnit license::
@end menu


@c @node    Guava license
@c @subsubsection Guava license
@c
@c Daikon uses the Google Guava library, which is licensed under
@c the Apache License Version 2.0.  A copy of this license is included
@c with the Daikon distribution as the file
@c @file{doc/apache-license-2.txt}.


@node    getopt license
@subsubsection getopt license

Daikon uses the Java port of the GNU @file{getopt} library, which is
copyright 1998 @nospellcheck{Aaron M. Renn}.
The @file{getopt} library is free software, and
may be redistributed or modified under the terms of the GNU Library
General Public License version 2.  A copy of this license is included
with the Daikon distribution as the file
@file{doc/gnu-gpl-2.txt}.


@node    JUnit license
@subsubsection JUnit license

Daikon's unit tests use the @command{JUnit} testing framework, which is governed
by the Common Public License, version 1.0.  @command{JUnit} is provided on an
``as is'' basis, without warranties or conditions of any kind, either
express or implied including, without limitation, any warranties or
conditions of title, non-infringement, merchantability or fitness for
a particular purpose.  Neither the Daikon developers nor the authors of
the @command{JUnit} framework shall have any liability for any direct, indirect,
incidental, special, exemplary, or consequential damages (including
without limitation lost profits), however caused and on any theory of
liability, whether in contract, strict liability, or tort (including
negligence or otherwise) arising in any way out of the use or
distribution of @command{JUnit} or the exercise of any rights granted in
the Common Public License, even if advised of the possibility of such
damages.  Those portions of @command{JUnit} that appear in the Daikon
distribution may be redistributed under the same terms as Daikon
itself; this offer is made by the Daikon developers exclusively and
not by any other party.  The Common Public License is included with the
Daikon distribution as the file @file{java/junit/cpl-v10.html}.



@node    Front end licenses
@subsection Front end licenses

Note that the front ends discussed in this manual are separate
programs, and some are made available under different licenses.
@c All
@c of the software in the main Daikon distribution is made available
@c under the same license as the Daikon tool proper, or a less
@c restrictive license.  However,
Because the front ends are separate
programs not derived from the Daikon invariant detection tool, you are
neither required nor entitled to use the Daikon invariant detector
itself under these other licenses.

@menu
* dfepl license::
* Kvasir license::
* Celeriac license::
@end menu


@node    dfepl license
@subsubsection dfepl license

The Daikon Perl front end @command{dfepl} may be used and distributed under the
regular Daikon license or, at your option, either the GNU General
Public License or the Perl Artistic License (that is, under the same
terms as Perl itself).


@node    Kvasir license
@subsubsection Kvasir license

The Daikon C/C++ front end Kvasir is based in part on the Valgrind
dynamic program supervision framework, copyright 2000-2004
@nospellcheck{Julian Seward}, the Sparrow Valgrind tool, copyright 2002
@nospellcheck{Nicholas Nethercote}, the @command{MemCheck} Valgrind tool,
copyright 2000-2004 @nospellcheck{Julian Seward}, the
@command{readelf} program of the GNU @nospellcheck{Binutils}, copyright 1998-2003 the Free
Software Foundation, Inc., the GNU C Library, copyright 1995, 1996,
1997, 2000  the Free Software Foundation, Inc., and the Diet @file{libc},
copyright @nospellcheck{Felix von Leitner et al}.  Kvasir is free software; you can
redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
Kvasir is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE@.  See the GNU General Public License
for more details.  You should have received a copy of the GNU General
Public License along with Kvasir, in the file @file{kvasir/COPYING};
if not, write to the
@nospellcheck{Free Software Foundation, Inc., 51 Franklin St., Fifth Floor, Boston, MA
02110-1301, USA}.


@node    Celeriac license
@subsubsection Celeriac license

The Daikon .NET front end Celeriac is Copyright (c) 2012 by
@nospellcheck{Kellen Donohue}.
Portions of Celeriac are covered by the Microsoft Public License,
this is at the top of every such file. Otherwise the following license
is in effect:

@exampleindent 1
@quotation
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
@end quotation
@exampleindent 4


@node    Mailing lists reminder
@section Mailing lists reminder

If you use Daikon, please subscribe to the @samp{daikon-announce} and
@samp{daikon-discuss} mailing lists (@pxref{Mailing lists}).  The
@samp{daikon-announce} list will inform you of new versions, enhancements,
and bug fixes.  On the @samp{daikon-discuss} mailing list, you can obtain
help from, and offer help to, other users.  We would also appreciate a
brief description of how you are using Daikon, sent to
@email{daikon-developers@@googlegroups.com}.  We are curious about how
users exploit Daikon, and we are eager for anecdotes about its
successes and failures, so that we can make Daikon more effective for
its users.


@node    Credits
@section Credits

@cindex contributors to Daikon

The following individuals have contributed to Daikon:
@nospellcheck{
Yuriy Brun,
Jake Cockrell,
David Cok,
Forrest Coward,
Adam Czeisler,
Brian Demsky,
Alan Donovan,
Nii Dodoo,
Kellen Donohue,
Alan Dunn,
Michael Ernst,
Eric Fellheimer,
Antonio Garcia-Dominguez,
William Griswold,
Florian Gross,
Philip Guo,
Melissa Hao,
Michael Harder,
Philipp Hirch,
Dieter von Holten,
Greg Jay,
Josh Kataoka,
Lee Lin,
Allen Liu,
Sandra Loosemore,
Vikash Mansinghka,
Stephen McCamant,
Samir Meghani,
Benjamin Morse,
Jelani Nelson,
Ryan Newton,
Jeremy Nimmer,
Toh Ne Win,
David Notkin,
Carlos Pacheco,
Jeff Perkins,
Jaime Quinonez,
Mark Roberts,
Robert Rudd,
Alexandru Salcianu,
Todd Schiller,
Kathryn Shih,
Eric Spishak,
Laure Thompson,
Matthew Tschantz,
Iuliu Vasilescu,
Chen Xiao,
Tao Xie,
Jeff Yuan.
}

@nospellcheck{Craig Kaplan} carved the Daikon logo.

The feedback of Daikon users has been very valuable.  We are
particularly grateful to
@nospellcheck{
B. Thomas Adler,
Rich Angros,
Tadashi Araragi,
Seung Mo Cho,
Christoph Csallner,
Dorothy Curtis,
Juan Pablo Galeotti,
Diego Garbervetsky,
Mangala Gowri,
Madeline Hardojo,
Engelbert Hubbers,
Nadya Kuzmina,
Scott McMaster,
Charles O'Donnell,
Alex Orso,
Rodric Rabbah,
Manos Renieris,
Rosie Wacha.
}
Many others have also been generous with their feedback, for which we
are also grateful.

If your name has been inadvertently omitted from this section, please
let us know so we can correct the oversight.

Financial support has been provided by:
@nospellcheck{
National Science Foundation (NSF),
Defense Advanced Research Projects Agency (DARPA),
ABB,
Edison Design Group,
IBM,
NTT,
MIT Oxygen Project,
Raytheon,
Toshiba.
}

@node    Citing Daikon
@section Citing Daikon

If you wish to cite Daikon in a publication, we recommend that you
reference one of the scholarly papers listed at
@uref{http://plse.cs.washington.edu/daikon/pubs/#invariant-detection} in lieu
of, or in addition to, referencing this manual and the Daikon website
(@uref{http://plse.cs.washington.edu/daikon/}).




@node       General Index
@unnumbered General Index

@printindex cp


@bye

@c  LocalWords:  texinfo setfilename daikon settitle MDE texi html daikonurl sp
@c  LocalWords:  inlined makeinfo daikonemail setchapternewpage ifinfo hboxes
@c  LocalWords:  finalout titlepage titlefont eps pdf txt png jpg vskip pt img
@c  LocalWords:  filll src alt ifnothtml dir ifnottex GUIs ifhtml detailmenu pl
@c  LocalWords:  Cygwin StackAr Diff orig dfepl CSV convertcsv dfej dfec gcc cd
@c  LocalWords:  applets EDG spinfo InvariantChecker LogicalCompare dtrace inv
@c  LocalWords:  runtimechecker javac Lackwit pptname uref abs lst treenode IOA
@c  LocalWords:  myArray PathFinder pxref cindex samp classpath xref var wget
@c  LocalWords:  daikonparent zxvf noindent csh tcsh cshrc setenv zxf DAIKONDIR
@c  LocalWords:  DAIKONCLASS bashrc java cpp daikonenv HKEY AutoRun pathlists
@c  LocalWords:  CompletionChar PathCompletionChar subsubsection MYDOCU ENV arg
@c  LocalWords:  DataStructures dotfiles ActiveState mypackage MyClass emph Xmx
@c  LocalWords:  StackArTester PrintInvariants theArray topOfStack Ljava gdwarf
@c  LocalWords:  kvasir decls Valgrind config Rijndael rijndaeltest perl bday
@c  LocalWords:  dtype standalone decl asis noversion num conf nohierarchy ppt
@c  LocalWords:  dbg mem stat postprocessed itemx mux pre val classname regexp
@c  LocalWords:  ListImplementors dataflow getLogger JML jml hashcode DBC Jtest
@c  LocalWords:  Parasoft's Quant ESC pre-state int seq elt Javadoc JVML param
@c  LocalWords:  DerivedParameterFilter ObviousFilter args ParentFilter isEmpty
@c  LocalWords:  OnlyConstantVariablesFilter SimplifyFilter UnjustifiedFilter
@c  LocalWords:  UnmodifiedVariableEqualityFilter diff OneOf InvMap repr gui td
@c  LocalWords:  invSortComparator invPairComparator daikonHelp ifnotinfo gif
@c  LocalWords:  InvariantsDisplay Ctrl ControlPanel checkbox kbd JDE prj jde
@c  LocalWords:  autoload myA myList hashcodes MyA HashSetLinear HslIterator IA
@c  LocalWords:  topAndPop init util DTRACEFILE DTRACEAPPEND Valgrind's AMD gz
@c  LocalWords:  Athlon fomit Kvasir's programname vars gzip fifo AFS csv rec
@c  LocalWords:  stdout stderr disambig myprog Debian libfoo inst pragma prog
@c  LocalWords:  workflow accessor instr instrsourcedir TYPESAPPEND basedir cp
@c  LocalWords:  myfile dfej's classfiles jikes QueueAr QueueArTester ln nn gdb
@c  LocalWords:  classhier decldir instrdir uninst csal apdir cpdir Mangel's va
@c  LocalWords:  ComparablePairsDescFileReader runnables dumpdir rm isprint cmd
@c  LocalWords:  DTRACELIMIT DTRACELIMITTERMINATE DDTRACELIMIT applet xargs mv
@c  LocalWords:  DDTRACELIMITTERMINATE javaPolicy appletviewer MyProgram exe lw
@c  LocalWords:  datatypes intValue ListNode theElement precompiled Solaris cc
@c  LocalWords:  libw LDFLAGS xname textfile nogui daikonarg nocleanup tarfile
@c  LocalWords:  TODO DFECDIR exefile tracefilename stdc dfec's preprocessed wc
@c  LocalWords:  ctype sed declsfiledir declsfiledirflat searchpath includepath
@c  LocalWords:  GNUG disambigfilename mdas memset subarrays lackwit unsetting
@c  LocalWords:  postprocessing structs pcc gzipped zlib baz ints std min rray
@c  LocalWords:  ointer ifdef endif SmartPointer SmartArray malloc tex toc
@c  LocalWords:  mystring strcpy strcat smartpointers basemap namespace ansi eq
@c  LocalWords:  protoize fallback fixups const asm inline typeid typename bool
@c  LocalWords:  bitand bitor compl wchar xor unportable enums enum stdlib env
@c  LocalWords:  getenv bitfields bitfield realloc memcpy textutils pos lseek
@c  LocalWords:  fd Linux's GNUC mkdir tmp gunzip xf li dkconfig CreateSpinfo
@c  LocalWords:  ParameterDoclet CreateSpinfoC un biconditional addAll isFull
@c  LocalWords:  smallexample simpleStack currentSize jtb ParseException kmeans
@c  LocalWords:  runcluster xm ALG xmeans TraceSelect NOCLEAN DIFFS MergeESC pp
@c  LocalWords:  escannotated jmlannotated dbcannotated Annnotate xml INVINFO
@c  LocalWords:  ubs Throwable throwable rethrown WriteViolationFile MyProg
@c  LocalWords:  callMethod isInstrumented getInvariants INVS ijmp exin wp
@c  LocalWords:  bBoOmjpi de iconv undefine DHAVE Xie Ast rt MyPackage jre
@c  LocalWords:  superdirectory SOURCEPATH InvalidClassDataError strace lstat
@c  LocalWords:  RuntimeException IFLNK interconvert interconvertible strdup ld
@c  LocalWords:  lwpp ine runtime's malloced MaxPermSize JVM's MyVector perc vv
@c  LocalWords:  falsetime trueinvs testsuite MergeInvariants fns untruncate mx
@c  LocalWords:  subsubheading bzip fontspecific sublicense NONINFRINGEMENT Cok
@c  LocalWords:  getopt Renn Nethercote MemCheck readelf Binutils Yuriy Brun ps
@c  LocalWords:  Cockrell Czeisler Demsky Nii Dodoo Fellheimer Griswold Guo Hao
@c  LocalWords:  Kataoka Loosemore Vikash Mansinghka Samir Meghani Jelani Toh
@c  LocalWords:  Nimmer Shih Iuliu Vasilescu Xiao Kaplan Angros Tadashi Araragi
@c  LocalWords:  Seung Cho Hardojo Engelbert Hubbers McMaster Orso Manos Wacha
@c  LocalWords:  Renieris NTT varname VarInfoName hasDuplicates hasOrder len gc
@c  LocalWords:  hasNull nullTerminated isParam hashCode VarComparability IDE
@c  LocalWords:  makeEmpty topLevel bottomLevel pptInfo MyInteger printindex mw
@c  LocalWords:  cygwin basename globalVar staticVar funcStaticVar myName foo
@c  LocalWords:  TerminationMessage HotSpot daikonPrintArrayMissing javacc invs
@c  LocalWords:  sourcing toString struct uninstrumented Garbervetsky classfile
@c  LocalWords:  UnsupportedClassVersionError DtraceDiff VerifyError procedurei
@c  LocalWords:  replacementi junit declsfiles dtracefile PublicTest BCEL bcel
@c  LocalWords:  Mangel Wurzel premain ChicoryPremain configs radiusSquared vol
@c  LocalWords:  dyncomp DynComp metadata comp firstFileFunctioni ppts argc Dva
@c  LocalWords:  firstFileFunction secondFileFunctionv secondFileFunction argv
@c  LocalWords:  FunctionNamesTest globalIntArray anotherGlobalIntArray diffs
@c  LocalWords:  mangel wurzel Wurzel's libpurify inputfile frontend logfile dM
@c  LocalWords:  tmpdir regex namespaces fieldname microsoft Christoph Csallner
@c  LocalWords:  isspace xvzf toplevel bottomlevel AUTOEXEC getClass decs func
@c  LocalWords:  ptrs Misc isStruct winterDays summerDays usertype fooClass pty
@c  LocalWords:  fooVar CPATH mangelrc Dsetjmp setjmp lstdc libgcc GCC's cpp's
@c  LocalWords:  ifndef preinclude XTerm cl dirname cnt mwdefines url linux von
@c  LocalWords:  libc Leitner Quinonez Rodric Rabbah DDTRACEAPPEND createItem
@c  LocalWords:  maxPhase largestlet anag adjacentdups specfirstword DynComp's
@c  LocalWords:  maxdepthspec jdk dcomp BuildJDK FIFOs EXIT75 clinit VM
@c  LocalWords:  amd Itanium Yuan schoolDays breakDays DCompInstrumented OSTYPE
@c  LocalWords:  AnnotateNullable instrumenter toolset JHP pm PptMap loophead
@c  LocalWords:  instrumenters NoSuchMethodException myprogram glibc NonNull XP
@c  LocalWords:  Nullable Nullness daikondir nullable NonZero jaif nonnull Rudd
@c  LocalWords:  Holten McCamant Alexandru Salcianu Tschantz Nadya Kuzmina dec
@c  LocalWords:  readibility subexit dups rel birthyear preprocess ifset
@c  LocalWords:  nospellcheck tableindent paragraphindent exinenum ifclear
@c  LocalWords:  firstparagraphindent codequotebacktick exampleindent dfn
@c  LocalWords:  evenheading thispage thischaptername thischapternum hfuzz
@c  LocalWords:  oddheading thissectionnum thissectionname everyfooting d1
@c  LocalWords:  QuickTime QTSystem QTJava cygpath arg1 arg2 arg3 MyMain
@c  LocalWords:  originalclasspath grep EXIT79 EXIT32 prepend Xmx256m var1
@c  LocalWords:  prepended computeConfidence numsamples getName var2 var3
@c  LocalWords:  jcc Java2 seq1 CSharpContract myString otherString EXIT48
@c  LocalWords:  unsplit if'' condition1 condition2 condition3 procedure1
@c  LocalWords:  replacement1 procedure2 replacement2 arg0 EXIT33 pack1 d2
@c  LocalWords:  pack2 online'' EXIT11 o1 o2 SIGSEGV O0 fjalar gcc3 EXIT0
@c  LocalWords:  I' C' S' A' P' superclasses vv1 bzip2 Xmx512m bfd dev ABI
@c  LocalWords:  binutils AMD64 EM64T amd64 CeleriacLauncher celeriacArg1
@c  LocalWords:  celeriacArg2 EXIT22 checkargs Takuan WS BPEL file1 file2
@c  LocalWords:  readlink Hynger HYbrid iNvariant GEneratoR SLSF Bak Udon
@c  LocalWords:  Drager MacOSX I1 I2 invSortComparator1 invSortComparator2
@c  LocalWords:  Myprog2 isDaikonInstrumented getDaikonInvariants GeoPoint
@c  LocalWords:  valid'' deserializing declsfiles1 dtracefile1 declsfiles2
@c  LocalWords:  dtracefile2 NoClassDefFoundError overfitting Xmx2048m ps1
@c  LocalWords:  LIB2 CVC4 unformattable LinkageError SquarePanel Donohue
@c  LocalWords:  SecurityManager setSecurityManager omitpattern Software''
@c  LocalWords:  MyProblemMethod Liu Galeotti Mangala Gowri ABB LVTT LVT
@c  LocalWords:  ClassFormatError javautil ArrayList17 Simulink Stateflow
@c  LocalWords:  untyped splitter filename substring boolean splitters CVC
@c  LocalWords:  dimensionality consequents UNRETURNED getter globals
@c  LocalWords:  typedefs celeriacArg Inserter comparator roundoff bitwise
@c  LocalWords:  Kellen Florian Laure Raytheon