Program Database Toolkit (PDT)
Version 2.0

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

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/C++ and Fortran 77/90
IL (Intermediate Language) Analyzers, and DUCTAPE (C++ program Database 
Utilities and Conversion Tools APplication Environment) library and applica-
tions.  The EDG C++ (or Mutek Fortran 90) Front End first parses a source 
file, and produces an intermediate language file.  The appropriate 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		files copied from ductape/inc
include/kai	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.

alpha
apple
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 for C++ apps
bin/cparse      shell script that executes edgcpfe and taucpdisp for C apps
bin/edgcpfe     EDG C++ Front End executable
bin/taucpdisp   C++ IL Analyzer executable
bin/f90parse	shell script that executes f90fe and pdtf90disp
bin/f90fe	Mutek Fortran 90 Front End executable
bin/pdtf90disp	Fortran 90 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  
-----------------------------------------------------
alpha           Compaq Alpha       Tru64 OSF1 v5.1  
apple           Apple G4           Darwin MacOS X 10.1
hp9000s700      HP PA-RISC 1.1     HP-UX 10.20 *
linux           Intel PIII/ia64    RedHat Linux 6.1/6.2/7.0/7.1
rs6000          IBM SP-2           AIX 4.3
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.8
t3e             Cray T3E           Unicos MK 2.0.4.61 *

*: Under HP-UX and Unicos, F90 support is not available.

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

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

In order to use PDT, you will need to perform configuration.  ./configure
will setup the Makefiles so they work with the selected compilers and
operating system.

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

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++"
    -CC             Use SGI's CC
    -CXX            Use Tru64's cxx
    -C++            Use Apple's c++
    -XLC or -IBM    Use IBM's xlC

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

(5) [Optional] Generate a browsable HTML index of the DUCTAPE interface.
This can be done by the following commands (after you extended your $PATH
environment variable as described by the output of the configure script):

    cd ductape/inc
    ./MakeHtmlDocu

The HTML index will be placed in the directory ductape/html.

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

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

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

            See http://www.edg.com/ for further information.
 
taucpdisp : C++ and 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.

f90fe     : Mutek Fortran 90 Front End. This parses Fortran 77 and 90
            source code, and produces an intermediate language (IL) file
            that is processed by the Fortran IL analyzer.

pdtf90disp: Fortran 90 IL Analyzer executable

cxxparse  :
cparse    :
f90parse  : Shell scripts that executes the right parsers and IL analyzers.
            Usage:

              cxxparse <c++ file> <c++ flags>
              cparse   <c file>   <c flags>
              f90parse <f90 file> <f90 flags>

            <### 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 ### file and the suffix ".pdb".

            <### flags> are additional flags necessary for your program to
            compile.  The configure script will determine most, if not all,
            flags and incorporate these in ###parse.  Local options, such as
            an application include directory, can be specified here.
             
            cxxparse and cparse scripts accept -I<dir> and -D<define> flags
            for include directory and defines respectively.

            f90parse accepts the following flags:

            -F : Fixed form for source. By default, the form is free. In fixed
                 form positions (columns) 1-5 can be used only for lables, 
                 position 6 is for continuation and a "C" or "*" is for comment 
                 lines. The main program must fall in positions 7-72.

            -I<dir> : Adds a directory dir to the list of directories searched
                 for INCLUDE statements.
           
            -M<dir> : Specifies a list of directories for searching module 
                 definition files. Members of the list must be separated by 
                 semicolon. While modules are defined or used this option is 
                 mandatory.
 
            -R : Suppress folding constant expressions but those that either are
                 public constant values of modules or define parameters of type.

            -r : Issue remarks, which are diagnostic messages even milder than 
                 warnings.
 
            -U : Case sensitivity for identifiers.

            -u : Disable implicit typing of identifiers. This has the same
                 effect as IMPLICIT NONE statement as applied to the file.

            -A : Warn about use of non-F90 features, disable features that 
                 conflict with F90. 

            -Llfile: Generate raw listing information in the file lfile. This
                 information is used to generate a formatted listing where each
                 line begins with a key character that identifies the type:
                 N  - Normal line
                 S  - Comment line
                 R  - Remark diagnostics
                 W  - Warning diagnostics
                 E  - Error diagnostics
                 C  - Catastrophic error diagnostics.
 
  IMPORTANT NOTE: The Fortran 90 parser included in PDT adheres very strictly
  *************** to the F90 language specification and does not comply with 
                  extensions to the language typically implemented by vendors.
                  This includes real*8 or integer*8 types, kind parameters,
                  and some continuation fields in fixed form. In some cases, 
                  the source must be modified to comply with the standard before
                  the PDT front-end can parse the program. 
                
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>

            Only works for C and C++ sources for now.

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 yet.

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 a lot of documentation about writing
applications exists yet. A first draft of a DUCTAPE Primer can be
found in ductape/html/primer.html.

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

If you have already developed PDT Version 1.3 applications, the
ductape/doc/porting-1.o-to-2.0.txt document gives an overview
about the main changes and things which need to be changed so your
application can make use of version 2.0 features.

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

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

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

Edison Design Group (EDG) 
Mutek Solutions, Ltd.
    We would like to thank EDG and Mutek for the use of their respective
    C++ and Fortran 90 Front Ends, as well as their support, throughout the 
    development of PDT. 

KAI Software, A Division of Intel Americas, Inc.
    We would also like to thank KAI for letting us distribute their
    C++ header files with the PDT release. 
    

