Program Database Toolkit (PDT)
Version 1.3

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

Description
-----------

The Program Database Toolkit (PDT) is a tool infrastructure that provides
access to the high-level interface of source code for analysis tools and
applications.  Currently, the toolkit consists of the C++ IL (Intermediate
Language) Analyzer, and DUCTAPE (C++ program Database Utilities and
Conversion Tools APplication Environment).  The EDG C++ Front End first
parses a source file, and produces an intermediate language file.  The IL
Analyzer processes this IL file, and creates a "program database" (PDB)
file consisting of the high-level interface of the original source.  Use of
the DUCTAPE library then makes the contents of the PDB file accessible to
applications.

See http://www.acl.lanl.gov/pdtoolkit/ for more information on PDT.
See doc/converter.txt for a complete listing of what has been implemented
in this release of PDT, as well as notes and caveats.

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

Summary
-------

This directory contains the Program Database Toolkit software.

Subdirectories in this PDT directory include the following.

doc             documentation
ductape		DUCTAPE
ductape/doc	DUCTAPE documentation
ductape/inc	DUCTAPE include files
ductape/lib	DUCTAPE library source files
ductape/src	tools that use the DUCTAPE library
hmtl            documentation
include		ductape (to be copied from ductape/inc) and KAI include files

The following architecture-specific subdirectories are also included.
These directories have bin and lib subdirectories for the PDT shell
script, executables, and library.

hp9000s700
linux
rs6000
sgi32
sgin32
sgi64
solaris2
t3e

The files in the architecture-specific bin and lib directories include,
or will include, the following.  The bin and lib directories may be in
a user-specified subdirectory.  (See Installation below.)

bin/cxxparse    shell script that executes edgcpfe and taucpdisp
bin/edgcpfe     EDG C++ Front End executable
bin/taucpdisp   C++ IL Analyzer executable
bin/pdbconv     DUCTAPE application
bin/pdbhtml	DUCTAPE application
bin/pdbmerge    DUCTAPE application
bin/pdbtree     DUCTAPE application
lib/libpdb.a    DUCTAPE library

The binaries are built for the following platforms.

-----------------------------------------------------
Architecture 	Platform 	   Operating System  
-----------------------------------------------------
hp9000s700 	HP PA-RISC 1.1     HP-UX 10.20	  
linux		Intel i686	   RedHat Linux 6.1  
rs6000	        IBM SP-2	   AIX 4.2.1	  
sgi32		SGI R4400 IP22	   IRIX 6.5.4	  
sgin32		SGI R10000 IP25    IRIX 6.5.4	  
sgi64		SGI R10000 IP25	   IRIX 6.5.4	  
solaris2	SUN sun4m 	   Solaris SunOS 5.6 
t3e		SGI Cray T3E       Unicos MK 2.0.4.61

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

Installation
------------

In order to use PDT, you will need to perform configuration.  ./configure
will use cxxparse.proto as the prototype for cxxparse in the architecture-
appropriate bin.  bin/cxxparse is the shell script that should be used to
execute the PDT.

(1) Run ./configure.  This scans your system for usable C++ compilers and
automatically configures the makefiles and cxxparse.

If you prefer, you can specify a C++ compiler as a command line option to
./configure. The following switches are understood:

    -KAI or -KCC    Use KAI's KCC
    -GNU            Use EGCS or GNU C++ under the name "g++"
    -EGCS           Use EGCS C++ under the name "eg++"
    -CC             Use SGI's CC

It is not necessary to specify an architecture, unless you are using PDT
on SGI, where you might want to choose among IRIXO32, IRIXN32, and IRIX64.
Use one of the following command line options:

    -arch=IRIXO32
    -arch=IRIXN32
    -arch=IRIX64

Normally, source files are compiled for optimization (i.e., +K2 for KCC, 
-O2 otherwise). If you want other compiler options, you can pass these to 
configure via the -useropt=... command-line switch.
E.g.,

    ./configure -useropt='-g'

If you are using older (pre-7.3.0) versions of the SGI CC compiler, you
must use the -enable-old-headers option, e.g.,

    ./configure -enable-old-headers

If you want multiple versions of the DUCTAPE library (to support use of
multiple compilers), you must do multiple installations.  During each,
specify a different compiler via the command-line option -compdir=...
for ./configure, e.g.,

    -compdir=KCC-3.4f

This will create a subdirectory named "KCC-3.4f" that will contain the
bin and lib directories for the current architecture and the specified
compiler.

(2) Type "make"

(3) Type "make install" to install binaries in bin and lib subdirectories

(4) [Optional] Type "make clean" to free up disk space

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

Description of the Tools in the bin Directory
---------------------------------------------

edgcpfe  : Edison Design Group (EDG) C++ Front End.  This parses source 
	   code, and produces an intermediate language (IL) file that is
	   processed by the IL Analyzer.

           See http://www.edg.com/ for further information.

taucpdisp: C++ IL Analyzer from PDT.  This processes an IL file produced
	   by the EDG Front End, and creates a program database (PDB) file.
	   The PDB file contains the language interface of the original
	   source code.  The DUCTAPE library libpdb.a makes this high-level 
	   program information available to applications.

	   See http://www.acl.lanl.gov/pdtoolkit/ for further information.

cxxparse : Shell script that executes edgcpfe and taucpdisp. Usage:

             cxxparse <c++ file> <c++ flags>

           <c++ file> is the source file for which a program database (PDB)
           file is generated. The filename of the PDB file will have the
           basename of the C++ file and the suffix ".pdb".

           <c++ flags> are additional flags necessary for your program to
           compile.  The configure script will determine most, if not all,
           flags and incorporate these in cxxparse.  Local options, such as
           an application include directory, can be specified here.

pdbconv  : Simple tool that checks the consistency/correctness of a PDB file
           and converts it to a more verbose, human-readable format.
           Usage:

             pdbconv [-c | -o <outfile>] [-AGMNRSTY] <pdbfile>

           Called without any options, pdbconv reads the PDB file <pdbfile>
           checks it for correctness, and prints it out again in a standard
           form.  The following options are available:

           -c            Check for correctness only

           -o <outfile>  Write output to file <outfile>

           -A            Convert (A)ll item output to verbose format

           -G            Print only (G)roup items (in verbose format)

           -M            Print only (M)acro items (in verbose format)

           -N            Print only (N)amespace items (in verbose format)

           -R            Print only (R)outine items (in verbose format)

           -S            Print only (S)ource file items (in verbose format)

           -T            Print only (T)emplate items (in verbose format)

           -Y            Print only t(Y)pe items (in verbose format)

pdbhtml  : Produces "htmlized" versions of all source and header files
           contained in the program database file <pdbfile>. It also
           produces an HTML index of Classes, Templates, Namespaces,
           and Functions called "index.html". Usage:

             pdbhtml <pdbfile>

pdbmerge : Takes a set of program database files and merges them into one,
           eliminating duplicate items from different files, in the process.
	   Usage:

             pdbmerge [ [-v] -o <outfile>] <pdbfiles>...

           -v            Verbose.

           -o <outfile>  Write merged database to file <outfile> instead of
                         cout.

           Note:  Namespace definitions spread over several files are
           not merged correctly.

pdbtree  : Prints the source file inclusion tree, class hierarchy (IS-A +
           HAS-A), and function call graph. Usage: 

             pdbtree [-CRS] pdbfile

           -C            Print only the (C)lass hierarchy

           -R            Print only the (R)outine call graph

           -S            Print only the (S)ource file inclusion tree

           Note: Class hierarchy is a DAG, not a tree, and therefore display
           is bad.

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

Typical use of the Binaries
---------------------------

(1) Generate a PDB file for each compilation unit of your application:

    cxxparse srcfile1.cc -DMY_DEFINES=1 -I../my_includes ...
    cxxparse srcfile2.cc -DMY_DEFINES=1 -I../my_includes ...
    cxxparse srcfile3.cc -DMY_DEFINES=1 -I../my_includes ...
    ...

(2) Generate a PDB file for the whole application:

    pdbmerge -o myapp.pdb srcfile1.pdb srcfile2.pdb srcfile3.pdb ...

(3) Use the htmlizer or tree display:

    pdbhtml myapp.pdb
    pdbtree myapp.pdb

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

Writing your own PDT applications
---------------------------------

The DUCTAPE library, lib/libpdb.a, can be used to develop your own PDT
application.  Unfortunately, no documentation about writing applications
exists yet, besides some slides of a DUCTAPE presentation available at

    http://www.fz-juelich.de/zam/RD/coop/acl/ductape.ps.

See the example programs in the ductape/src directories (especially
pdbconv.cc and pdbtree.cc) on how to use the DUCTAPE library API.  ("Use 
the source, Luke!")  To compile your programs use:

    -I$(PDT_HOME)/include -L$(PDT_HOME)/$(ARCH)/lib -lpdb

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

Acknowledgements
----------------

The Program Database Toolkit development team would like to thank the
following companies for their help: 

Edison Design Group (EDG) 
    We would like to thank EDG for the use of their C++ Front End,
    as well as their support, throughout the development of PDT. 

Kuck & Associates, Inc. (KAI) 
    We would also like to thank KAI for letting us distribute their
    C++ header files with the PDT release. 

