README for common Paradyn/DyninstAPI directory hierarchy
          =========================================================

This directory contains the "dyninst" source code for both the Paradyn
parallel performance tools and the distinct DyninstAPI library for building
tools based on dynamic instrumentation.  It is divided into subdirectories
that represent major functional units of the system -- DyninstAPI-only
releases contain only those source subdirectories actually required by it.

Each of these directories contain source code that gets compiled into a single
executable:

        igen            - interface generator
        paradyn         - Paradyn GUI/controller
        paradynd        - Paradyn daemon (i.e. instrumentation manager)
        visiClients     - Paradyn visi clients (and tclVisi):
                          barchart, histVisi, phaseTable, tableVisi, terrain

There are also several libraries that get used in building the executables:

        pdutil          - Paradyn utility library (see also "common")
        rtinst          - runtime instrumentation (loaded into the application) 
        thread          - the thread package used by Paradyn
        visi            - external visualization interface

One directory contains source for utilities common to both Paradyn & DyninstAPI.

        common          - common utilities (e.g., Vector, String, Dictionary)

Two more directories contain the libraries that make up the DyninstAPI:

        dyninstAPI      - the DyninstAPI library
        dyninstAPI_RT   - runtime instrumentation (loaded into the application)

An additional directory contains the "dyner" DyninstAPI-based scripting tool:

        dyner           - the dyner Tcl-scripting interface to DyninstAPI.

There is also a Makefile and several make configuration files at this level:
        
        Makefile        - A top level GNU Makefile to build the entire system
                          for Unix systems *only*
                          (make scripts for WindowsNT are found in ../scripts)

        make.config     - A Makefile that defines global lists, flags, etc. that
                          are included into all other Makefiles in the system.
        make.library.tmpl - make configuration rules for libraries
        make.program.tmpl - make configuration rules for executables
        make.platform.tmpl - platform-specific make customizations

        nmake.config    - These three files are for WindowsNT nmake, and
                          they mimic the GNU make configuration files
        nmake.library.tmpl
        nmake.program.tmpl

The top-level Makefile has targets defined to build Paradyn ("make Paradyn"),
the DyninstAPI ("make DyninstAPI") or both (the default, "make").
Remember to read the section of the Developer's Guide describing build
configuation and appropriately edit make.config before building.
See the README file in the dyninstAPI subdirectory for further information
about building/installing the API library.

Subdirectories of the "dyninst" directory are organized to promote 
modularity and support compiling the system for multiple platforms 
in a single source tree.

Each directory contains the following files:
        h       - a directory describing the exported interface of this 
                  component.  This typically consists of one or more C++ header
                  files, and one or more interface generator specifications
                  (files ending in .I).

        src     - a directory containing the source files for the component.
                  Header files that are not part of the exported interface
                  are in this directory.

        docs    - a directory containing the documentation for this component
                  of the system.  This generally consists of several man pages
                  and a README file.

        tests   - a directory containing any tests for that module
                  (typically for library modules only)

        build directories: <arch>-<vendor>-<os>
                  There is one of these for each supported platform.  The 
                  contents of this directory consist of a Makefile and the 
                  machine derived files that are built as part of the process 
                  of building the component.  These might includes .C and .h 
                  files generated by igen, flex, and bison as well as object 
                  files (.o's).

==============================================================================