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 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". 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 [-o ] [-ACMNRSTY] Called without any options, pdbconv reads the PDB file checks for correctness, and prints it out again in a standard form. The following options are available: -o Write output to file -A Convert (A)ll item output to verbose format -C Print only (C)lass 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 . It also produces an HTML index of Classes, Templates, Namespaces, and Functions called "index.html". Usage: pdbhtml Note: the current version doesn't handle situations very well where the source files are distributed over more than one directory (some hyperlinks are bogus). pdbmerge : Takes a set of program database files and merges them into one, eliminating duplicate items from different files, in the process. Usage: pdbmerge [-o ] ... -o Write merged database to file 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.