Introductory parseThat commit. - - - - - - - - - - - - - - - - - - - - -
[dyninst.git] / parseThat / README
1 INTRODUCTION
2
3 parseThat is an application that provides a rigorous and robust test of
4 DyninstAPI on arbitrary binaries.  Geared mainly for debugging purposes,
5 parseThat has many features which ultimately allow DyninstAPI developers
6 to quickly find the source of parsing or instrumentation errors in the
7 rare instance when they occur.
8
9 CONFIGURATION
10
11 There are a few variables which allow you to control how parseThat is
12 built.  These variables can either be set in your shell's environment,
13 as a parameter to the build command, or within the Makefile itself:
14
15         PLATFORM
16         This variable must be defined.  See the documentation for DyninstAPI
17         in core/dyninstAPI/README for valid values of this variable.
18
19         OPENSSL_DIR
20         parseThat depends upon OpenSSL for its message digest routines.  If
21         your system has OpenSSL installed in a non-standard location, you may
22         set this variable to aid the linker find the appropriate libraries.
23         OPENSSL_INC and OPENSSL_LIB are derived from this variable, but both
24         can be overridden for more complex installations.
25
26         DYNINST_DIR
27         This variable is used similarly to OPENSSL_DIR.  If not specified,
28         it uses the environment DYNINST_ROOT, if available.
29
30         DYNINST_VER
31         parseThat is backwards compatible with DyninstAPI through version
32         4.x.  However, due to an interface change between versions 4.x and
33         5.x,  there is a need to specify which version you will be using.
34         If not specified, it assumes you are using the latest version.
35
36 BUILDING
37
38 Once configured, you can build parseThat by simply invoking GNU make in the
39 base directory.  To organize building for multiple platforms within the same
40 directory, a subdirectory based on PLATFORM is created to hold all compiled
41 objects and binary files.
42
43 For the user's convenience, a symbolic link is created in the base directory
44 pointing to the newly built binary.
45
46 RUNNING
47
48 Instructions for parseThats use are encoded within the binary itself.
49 To retrieve them, simply run parseThat with no arguments.