Added parseThat feature to automatically binary search through instrumentation points...
[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 generates copious output for each dyninstAPI feature it uses.
6
7 These output logs can be used to quickly locate the source of parsing or
8 instrumentation bugs, in the rare instance when they occur.
9
10 CONFIGURATION
11
12 Autoconf scripts are used to gather information about the target platform
13 before building.  Run the script "configure" to initiate the process:
14
15         ./configure
16
17 Building outside of the source tree is possible as well:
18
19         mkdir ${OBJ_DIR}; cd ${OBJ_DIR}
20         /path/to/parseThat/configure
21
22 By default, the parseThat binary will be placed in the build directory.
23 Use the --prefix flag to install it somewhere else.  For example, to
24 install parseThat in /usr/local/bin:
25
26         ./configure --prefix=/usr/local/bin
27
28 There are a few variables which allow you to control how parseThat is
29 built.
30
31         PLATFORM
32         The configuration scripts will attempt to guess your target
33         platform, but it's sometime helpful to specify your build
34         platform manually.  See the documentation for DyninstAPI in
35         core/dyninstAPI/README for valid values of this variable.
36
37         DYNINST_ROOT
38         The various headers and libraries for DyninstAPI may not be
39         installed in a standard location.  Use this environment
40         variable to manually specify where you placed a source or
41         binary distribution of DyninstAPI.
42
43 BUILDING & INSTALLING
44
45 Once configured, you can build parseThat by simply invoking GNU make in the
46 base directory.  To build parseThat for multiple platforms simultaneously
47 with the same source tree, you must create a seperate object directory for
48 each platform.  See instructions under CONFIGURATION for details on building
49 outside the source tree.
50
51 Once successfully built, invoking GNU make with the "install" target will
52 copy the binary to its final destination.
53
54 RUNNING
55
56 Documentation on running parseThat is encoded within the binary itself.
57 It can be viewed by simply running parseThat with the --help flag.