Instructions
------------

The package includes the application binary "thor" and a few example
C files.  Each .c file contains several functions which can be
independently analyzed.  To run thor, type

thor -f func_name filename.c

This will analyze the given function in the C file "filename.c".
During the proving process, progress is displayed by means of a stack
of numbers.  The numbers indicate how many states at that depth remain
unexplored.

For a list of options, type

thor -help

When run, thor creates a directory called "thord". This is where it
writes the results of the analysis.  When analyzing the function
"func", thor will create the following files:

	thord/func.html
	thord/func-tree.html
	thord/func-arith.c

The first file is an annotated version of the program.  The inferred
invariants are given for each program cut-point.  The invariants are
conjunctive in nature and each invariant is printed on its own line. A
disjunction is represented by printing more than one invariant between
two source commands.

The file "func-tree.html" gives the execution tree that was
constructed while proving the program in a C-style format.  This gives
more insight into the results, as it contains the exact path which led
to each invariant.  Errors in the program are noted by the presence of
"Abort" commands.

The file "func-arith.c" is a C program which contains the result of
the arithmetic translation. If shape analysis alone was unable to
prove that the program is memory-safe, then this program can be used
to complete the proof. If an arithmetic analysis is able to show that
the error location in "func-arith.c" is unreachable, then this implies
that the original program is memory safe.

The HTML outputs can be further enhanced by providing the -dot
argument to thor.  This turns the invariants into links, which, when
clicked, display graphically the pointer structure that the invariant
represents.  They can be clicked again to return to the text-based
view.  Running the tool in the mode substantially increases the time
taken due to the time taken to render all the graphics (which is done
by making many calls to the DOT program during the proving process).

Command line flags are also given to tailor the arithmetic program
output for use with different arithmetic tools.  The -blast and -fast
options generate output in the thord/ directory that is suitable for
the associated tool.  The -armc option is currently a no-op as the
standard func-arith.c file generated by thor can be converted to ARMC
format using the C-to-ARMC conversion tool from the ARMC website.

Legal
-----
Thor is provided solely for non-commercial, academic use.  Any other
use requires the express permission of the authors.
