sxt.doc

Graphically Assisted Programming Interface

        programming languages.

        The following packages are currently available:

        * CXT - C Exploration Tools:
          CFT - C Function Tree Generator
             Tool to analyse and display the function call  relationships
             within the source code of C/C++ programs.
          CST - C Structure Tree Generator
             Tool    to   analyse   and   display   the   structure/class
             relationships within the source code of C/C++ programs.

        * DXT - DBASE Exploration Tools:
          DFT - DBASE Function Tree Generator
             Tool to analyse and display the function call  relationships
             within the source code of DBASE,  CLIPPER, FOXBASE and other
             XBASE-like programs.

        * FXT - FORTRAN Exploration Tools:
          FFT - FORTRAN Function Tree Generator
             Tool to analyse and display the function call  relationships
             within the source code of FORTRAN programs.

        * LXT - LISP Exploration Tools:
          LFT - LISP Function Tree Generator
             Tool  to analyse and display the function call relationships
             within the source code of LISP and SCHEME programs.

        Each  of  these  packages  consists  of  the   analysis   program
        ("Analyser")  and  a recall program ("Navigator") to retrieve the
        analysis  results  which  can  be  stored  in  a  database,  plus
        documentation and additional macros to integrate these tools into
        popular editors like BRIEF, QEDIT or MicroEMACS.

        Each of these packages is available for the following systems:

             * DOS real mode               (shareware release)
             * DOS 386 protected mode      (registered users only)
             * WINDOWS NT text mode        (registered users only)
             * OS/2 text mode              (registered users only)
             * Windows 3.1                 (shareware release)
             * Windows 32 bit (Win32s)     (registered users only)

        There  are  no  differences  in  the  functionality  between  the
        versions for the different systems.

        There are no plans to port the SXT programs to other platforms or
        operating systems like Apple MacIntosh, UNIX (SCO, Solaris,  AIX,
        HP-UX,  Linux,  ...),  Atari or Amiga. The source code of the SXT
        programs is not available.




                                      - 6 -


        IMPORTANT NOTICE

        Although this document is mainly based on the description for the
        CXT programs CFT and CST (which were up to version 2.13 the  only
        public  available SXT programs) and therefore very C/C++ related,
        the description  applies  in  the  same  way  to  all  other  SXT
        packages.  The  names  CXT/CXTWIN  resp.  CFT/CST,  CFTN/CSTN and
        CFTWIN/CSTWIN can  be  simply  exchanged  by  the  similar  other
        product  names  DXT,  FXT or LXT.  Where necessary,  the specific
        differences of the SXT packages are described.  I  have  done  it
        this  way  to ensure an overall consistency,  to keep all related
        things together  and  to  reduce  the  efforts  for  writing  and
        maintaining this document.













































                                      - 7 -


        2    GENERAL INTRODUCTION

        The  SXT  programs are powerful program development,  maintenance
        and  documentation  tools.   They  are  primarily  intended   for
        analysing  large  programs,   where  it  is  difficult,   if  not
        impossible, for the programmer to find the structure of the whole
        program.   They  allow  the  analysis  of  the  source  code   of
        applications,  no  matter  how  big or complex they are.  The SXT
        programs are also very useful to explore unknown source code  and
        to  get  complete  overview  about  its  internal structure.  The
        re-engineering of old and/or undocumented source code becomes  an
        easy  task with these programs.  The tools help the programmer to
        analyse,  identify,  locate and  access  all  parts  of  a  large
        software  system.  They  are  designed to support software reuse,
        maintenance and reliability.

        By preprocessing,  scanning  and  analysing  the  entire  program
        source  code  as a single unit,  these programs build an internal
        representation of the function call  hierarchy  (CFT,  DFT,  FFT,
        LFT)  and  of  the data structure relations (CST).  The resulting
        output shows from a global perspective the interdependencies  and
        hierarchical structure between the functions or data types of the
        whole, multi file, software project. Several features and options
        allow  the  user  to customise the generated hierarchy tree chart
        output and to get a large set of useful  informations  about  the
        source code. The hierarchy structure is always up-to-date because
        it  relies  on  the original source code as the primary source of
        information.  Written software documentation often  differs  from
        that what really has been coded, so the source code itself is the
        ultimate documentation.

        An  important  feature is the database generation.  It allows the
        recalling of informations without reprocessing the  source  code.
        The  database  can  again  be  read  in by CFT and CST to produce
        different outputs or to add new files to  the  database.  Special
        recall  programs  called  CFTN  and CSTN allow fast searching for
        items in the database.  These programs can  be  used  within  any
        environment,  for  example on the DOS command line or from inside
        editors like BRIEF,  QEDIT or MicroEMACS (DOS  and  WINDOWS),  to
        provide  a full software project management system with access to
        all functions  and  data  types  with  just  a  keystroke.  These
        features  make  a  comfortable "hypertext source code browser and
        locator" system out of  your  editor.  A  project  consisting  of
        several   files  appears  to  the  developer  as  if  it  were  a
        'whole-part' of software. The developer can walk through programs
        and trace the logic without having to  memorize  the  directories
        and files where functions or data types are defined and called.

        Displaying   and  printing  a  graphical  representation  of  the
        analysis results as a call graph is not  supported  bye  the  SXT
        programs  but  owners  of  RATIONAL  ROSE,  a  powerful  software
        development  case  tool  supporting  the  Booch   Object-Oriented
        Analysis  and  Design  (OOAD) method,  can use this tool for such
        purposes.  The SXT programs can generate compatible output  which
        can  be  imported  by  Rational Rose.  See option -RATIONAL for a
        detailed description.


                                      - 8 -



        Listings of all functions/data types  and  source  files  can  be
        written  as  formatted  ASCII text files and can be used as input
        for  other  programs  like   word   processors   or   spreadsheet
        calculators.

        A  useful  option  of CST is the possibility to generate a source
        file  with  which  size  and   byte   offset   calculations   for
        structures/unions and their members can be performed. This option
        is  useful  especially  to support any kind of error searching or
        hardware  debugging,  for  example  with  an  ICE,   or  if  data
        structures  have  to  be  exchanged  between  different  hardware
        platforms.

        CFT can also be used to analyse "C"-like languages  as  they  are
        used  by  several  commercial  programs.  The  macro  programming
        languages of the BRIEF, EPSILON and ME editors are such languages
        and can be handled by CFT.

        The resulting output files can be used for various purposes  like
        development  or documentation.  For registered users there are no
        restriction limits in using them for their own work.

        CFT and CST have been used  and  tested  since  1989  in  several
        projects  with applications ranging from single source files over
        medium sized projects (like CFT,  CST and  the  other  SXT  tools
        themselves)  up  to very large software projects with hundreds of
        source and include files (mixed C and assembler code),  more than
        6 MB of source code,  more than 210000 lines,  2300 functions and
        700 data types.

        A lot of public available C/C++  sources  (e.g.  GNU-C  compiler,
        GNU-C library,  GNU-EMACS,  MicroEMACS, NCSA TCP/IP communication
        software package, SUIT - The Simple User Interface Toolkit, NIHCL
        - The  National  Institute  of  Health  C++  class  library,  F2C
        Fortran-to-C translator,  several projects from Dr. Dobbs Journal
        (DFLAT,  BOB),  Microsoft sample code (MFC  1.0  and  2.0))  were
        processed   (with   sometimes  surprising  results!)  during  the
        development and have been used to test and improve the  features,
        reliability,  correctness, robustness and execution speed of CFT,
        CST and their related utilities.

        Although the other SXT packages are much newer than CFT and  CST,
        they all are closely related.  The CXT tools are used as the base
        for all other packages.













                                      - 9 -


        3    PROGRAM DESCRIPTION

        CFT builds a hierarchy tree chart  of  every  function  with  the
        called functions in it's own function block.  These functions are
        again used as a starting point for  subsequent  function  blocks.
        Starting  the tree chart with the "main"-function it will display
        the complete function  flow  chart  and  the  function  hierarchy
        dependency  of  the  whole  application  with  all  user  defined
        functions and the called library functions.  Prototyped but never
        defined or called functions are also detected. Recursive calls of
        functions  are  recognised and displayed,  even over several call
        levels.  Repeated calls of previously displayed functions in  the
        output tree chart are detected and a message will be given with a
        reference to their first appearance.  This prevents the output of
        complete subtrees displayed earlier. Overloaded C++ functions and
        operators  are  recognised  and  displayed  with  the  number  of
        overloadings.

        CST  acts  similar  to  CFT but it works on data types like basic
        types,  structures,  unions,  enumerations and C++  classes.  CST
        builds  a  hierarchy tree chart of every structure and union data
        type with their internal elements and their related  data  types.
        If these data types are again structures,  unions or classes, the
        substructures will again be displayed.  CST recognises data types
        defined by 'typedef' and derived from other data types.  The type
        names corresponding to the same basic type are displayed  in  the
        output  file  as  'alias'  names for their common basic data type
        name.  Every feature of  CFT  like  the  detection  of  recursive
        declared   structures   and  unions,   references  to  previously
        displayed data types and others are available and act similar.

        Every function (CFT) and data type (CST) can  be  displayed  with
        the  name  of  the  source  file  and the line number where it is
        defined.  The output can be customised to display the tree  chart
        as a call-tree ("CALLER-CALLEE"-relation: "WHO CALLS WHOM") or as
        a   caller-tree  ("CALLEE-CALLER"-relation:  "WHO  IS  CALLED  BY
        WHOM"). This feature allows the user to determine which functions
        are called from  a  specific  function  or  which  functions  are
        callers of a specific function.

        The  function  and  data  type extraction from the source code is
        done by scanning and parsing the source.  There is absolutely  no
        need  for  the  programmer  to  mark  functions  or data types of
        interest,  for  example  with  special  keywords,   starting  the
        definitions  at  the  beginning  of  a  line  or  to use comments
        containing special marks,  as it is necessary  for  other  source
        code analysers and browsers.  CFT, CST and the other SXT programs
        do not need these work-arounds,  any source code can be processed
        without previous work.  These tools are also compiler independent
        because they can be customised to support any kind of compiler.

        Since the SXT programs always  make  a  static  analysis  of  the
        program  source code,  they are not able to detect references due
        to the expansion of a macro definition during runtime.  This  has
        to  be  considered  for  DBASE and LISP programs which allow such
        dynamic features.  The same restrictions apply also to the use of


                                     - 10 -


        function   pointers  for  C/C++  and  function  names  as  formal
        parameters in FORTRAN which cannot be  resolved  for  call  graph
        generation.

        Several  useful  informations  and  software  metrics  about  the
        processed source code and the included  files  can  be  generated
        like

        -    file size and comment size in bytes for every file,
        -    number of source code lines for every file,