WIP towards parallel parsing
[dyninst.git] / parseThat / README.md
1 # parseThat
2
3 ## Introduction
4
5 parseThat is an application that provides a rigorous and robust test of
6 DyninstAPI on arbitrary binaries.  Geared mainly for debugging purposes,
7 parseThat generates copious output for each dyninstAPI feature it uses.
8
9 These output logs can be used to quickly locate the source of parsing or
10 instrumentation bugs, in the rare instance when they occur.
11
12 ## Configuration
13
14 Autoconf scripts are used to gather information about the target platform
15 before building.  The top level Makefile, however, will issue configure commands.
16 If a custom configuration is desired, first do a top-level build (to ensure that 
17 the build directory is created).  Then "cd $PLATFORM" and issue the command:
18
19         ../configure <custom config options here>
20
21 By default, the parseThat binary will be placed in the build directory.
22 Use the --prefix flag to install it somewhere else.  For example, to
23 install parseThat in /usr/local/bin:
24
25         ./configure --prefix=/usr/local/bin
26
27 There are a few variables which allow you to control how parseThat is
28 built.
29
30         PLATFORM
31         The configuration scripts will attempt to guess your target
32         platform, but it's sometime helpful to specify your build
33         platform manually.  See the documentation for DyninstAPI in
34         dyninst/dyninstAPI/README for valid values of this variable.
35
36         DYNINST_ROOT
37         The various headers and libraries for DyninstAPI may not be
38         installed in a standard location.  Use this environment
39         variable to manually specify where you placed a source or
40         binary distribution of DyninstAPI.
41
42 ## Building and Installing
43
44 To build parseThat from scratch, issue the make command.  This will create
45 a platform-specific build directory, configure the Makefile, and build 
46 parseThat.  The top level Makefile (not platform specific) just relays make
47 commands to the platform specific Makefile in the $PLATFORM directory.
48
49 Once successfully built, invoking GNU make with the "install" target will
50 copy the binary to its final destination.
51
52 ## Running
53
54 Documentation on running parseThat is encoded within the binary itself.
55 It can be viewed by simply running parseThat with the --help flag.