sxt.doc

Graphically Assisted Programming Interface

        function/subroutine.  The  indirect  call  of functions which are
        given as formal parameters to subroutines or  functions  are  not
        referenced  correct.  Implicit  typing  for  function definitions
        without return type will not be recognised,  the function will be
        displayed without a return type.


        3.5  LISP SOURCE CODE

        LFT  can process LISP and SCHEME source code.  The development of
        LFT was mainly based on the GNU-EMACS LISP dialect as it is  used
        in  the  GNU-EMACS macro extension language and its functionality
        was tested mainly with these macro files.  LISP  functions/macros
        are  recognised  by  the  DEFUN  and  DEFMACRO  keywords.  SCHEME
        functions are recognised by the DEFINE keyword, SCHEME processing
        is enabled by option -XSCHEME.  Unnamed functions  declared  with
        the   LAMBDA   keyword   can  be  recognised  optionally  (option
        -XLAMBDA).  Tokens  are  assumed  case-sensitive.   Comments  are
        recognised for ';' until end-of-line and between '#|' and '|#' as
        multi line comment blocks.

        The  source  code  analysis is performed in two passes: The first
        pass detects function/macro  declarations  and  the  second  pass
        analyses  the relationships.  Function calls via (funcall <fcn>),
        (function  <fcn>),  (apply  <fcn>),   (mapc  <fcn>)  and  similar
        constructs   may   not   be  correctly  evaluated  if  fcn  is  a
        function-symbol (e.g.  given as a function parameter) and  not  a
        valid  function  name.  System  builtin  functions/macros  can be
        specified by option -E.

        LFT was designed to work with different types of LISP source code
        (as there are XLISP,  CLOS,  GNU-EMACS LISP,  ...),  although the
        large  number  of  dialects  may  lead  sometimes  to  unexpected
        problems.








                                     - 16 -


        3.6  ASSEMBLER SOURCE CODE

        As an additional feature,  CFT  and  FFT  can  process  assembler
        source  code for the Intel 80x86 processors (MASM 5.1,  TASM) and
        for the Intel 80960 RISC processors (or any other "AT&T UNIX-like
        assembler"  like  GNU)  to  get   information   about   assembler
        procedures  and  functions being called from the assembler source
        files. The assembler source code scanner also detects and handles
        calls of include files. This feature is useful for mixed language
        programming. The processing of assembler macros, however,  is not
        supported, the preprocessing option (-P) works only with C source
        code.  Assembler  source  files  are  recognised  by  their  file
        extensions '.ASM' and '.S', there is no other way to force a file
        being processed as an assembler file.

        The following naming convention is  used:  For  '.ASM'  assembler
        files  (MASM,  TASM) all identifiers are treated case-insensitive
        and will be transformed to lower (CFT)  resp.  upper  (FFT)  case
        characters,  but identifiers in '.S' (GNU,  I960) assembler files
        are  treated  case-sensitive.  This  means,   that  an  assembler
        function 'func1' defined in an '.ASM' file can be called from the
        source by 'func1',  'FUNC1', 'Func1' or any other lower and upper
        case character combination.  If 'func1' is  defined  in  an  '.S'
        file,  the name must match exactly.  The first leading underscore
        of a function name will be removed to get exact  naming  matches.
        Type modifiers in C source code like 'cdecl' or 'pascal' will not
        be  considered.  Remember  these  conventions  when processing C,
        FORTRAN and assembler files.

        Assembler code statements (inline code) inside C source code will
        not be processed and will be skipped, because it is too difficult
        to handle the several kinds of syntax being used for this    like
        'asm  ...',  'asm "..."' or 'asm(...)' and the different keywords
        ('asm', '_asm', '__asm', '__asm__', ...) used by various compiler
        implementations.























                                     - 17 -


        5    DATABASE GENERATION

        One of the most important features  is  the  database  generation
        which  can  be enabled with the -G option.  It is performed after
        writing the output  file  to  save  all  informations  about  the
        processed  files  in  a  set  of  dBASE compatible database files
        (extension '.DBF') for later use.  These database  files  contain
        all necessary informations like function or data type names,  the
        location   where   they   are   defined,    their   caller/callee
        relationship,  all  scanned  files  with  statistic informations,
        include files and so on.  It was tried to store the  informations
        in the most compact and effective database structure to save disk
        space.  Note  that  if  the  contents  of  the  database files is
        manipulated by external tools like dBASE or something  else,  the
        internal  consistency  will  be corrupted and wrong or unexpected
        results will happen!

        The database can be used to recall informations,  for example  to
        find  out,  if  and  in  which  file and on which line a specific
        function or data type is defined. A previously generated database
        can be read into CFT and CST (option -g) to add new files  to  it
        and/or  to  produce  another  output  file with new configuration
        options,  for example with the reverse call tree or only  with  a
        special  selected  item  of  interest  to  be displayed.  Such an
        incremental database generation is also useful if large  projects
        can  be  divided  into  a  set of commonly used files and project
        specific files.  A good example for this is the GNU  C  compiler,
        which  consists  of a set of language independent files and three
        language dependent file sets  for  C,  C++  and  Objective-C.  To
        analyse  this software with CFT or CST,  the language independent
        part can be stored into a database which is later reused for  the
        language   dependent   parts   to   build  the  complete  set  of
        informations.

        The ability to retrieve informations about the sources  from  the
        database  is  quite useful in many cases.  Recalling informations
        from a database is much faster than processing  all  the  sources
        again to find a specific item of interest.  The documentation and
        maintenance of large software projects is much more effective and
        easier to do if the developer has a tool to navigate through  the
        source  code  and  that  helps  him  in  his comprehension of the
        program and its internal structure. It is also useful for reverse
        engineering of source code to get an  overview  of  the  internal
        program structure.  Together with user programmable editors it is
        possible to offer the user a source code browser with a hypertext
        like feeling by integrating database recalling functions into the
        editors.

        Two  utility  programs,   called  CFTN  and  CSTN  to,   retrieve
        informations from databases, are available with supporting macros
        for their integration into the BRIEF, QEDIT or MicroEMACS editor,
        which are described in another section later in this manual.






                                     - 18 -


        6    PROGRAM LIMITATIONS

        First  of all,  CFT and CST cannot replace a compiler or a syntax
        checker like 'LINT' to detect errors in  the  source  code.  This
        means  that  it  should  be  possible  to compile the source code
        without fatal errors before it is possible to analyse it with CFT
        and CST,  otherwise the processing results may be incorrect  (and
        may be the system crashes ...).

        However,  there  are  some  situations  where  CFT and CST can be
        useful to detect bugs and inconsistencies in the source code like

        -    multiple definitions of functions or data types,
        -    different function return types,
        -    implicit declared functions with no prototype,
        -    function definitions used as prototype,
        -    recursive,  nested,  hidden and frequent  calls  of  include
             files,
        -    unterminated strings or character constants,
        -    nested comments,
        -    unterminated comments at end of file,
        -    misbalanced braces,
        -    unexpected end-of-file characters inside files,
        -    illegal characters in the source code,
        -    wrong number of macro arguments,
        -    missing macro arguments,
        -    misbalanced '#if...' control blocks.

        These  code  checks  are  done  on  multiple  files  in  multiple
        directories so that inconsistencies between different  files  can
        be  found and displayed.  This is a capability which conventional
        compilers working only on a single file at a time cannot  provide
        and will miss therefore (maybe the linker will find some of these
        inconsistencies).

        Some  statistical  informations  about the source code may not be
        correct if  preprocessing  is  enabled  (-P).  This  affects  all
        options which do statistics like the -p or -s option. The size of
        the  'pure' source code may not be correct due to macro expansion
        or removing of unnecessary blanks.  However,  the  file  size  is
        always correct because it will be taken from the source file.

        Most  of  the  program  limitations  are  caused  by  the limited
        available memory.  This means that  the  more  conventional  main
        memory you have,  the better it is. The real mode versions of CFT
        and CST do not use expanded or extended memory, no virtual memory
        management or disk  file  swapping,  so  keep  your  conventional
        memory  free of memory consuming TSR programs and other utilities
        if you want to process a  large  number  of  files.  The  use  of
        operating  systems  like  MS-DOS  6.0 and/or memory managers like
        QEMM or 386MAX to get more free conventional memory may  help  to
        handle  big applications with a large number of files.  If memory
        problems still occur during processing,  there is an easy way  to
        break  the  memory limits: use the 32 bit protected mode versions
        of CFT and CST,  called CFT386 and  CST386.  These  programs  are
        running  in protected mode and so they have no memory limitations


                                     - 19 -


        and are faster than the real mode versions.  You can also use the
        Windows 3.1, Win32s, Windows-NT and OS/2 versions which have also
        no memory limitations.

        The  number  and  the  sizes  of  files to be processed is nearly
        unlimited with 2^14 files and 2^31  bytes  maximum  file  length.
        Each  file can have 2^16 lines.  The number of functions and data
        types being handled is limited to 2^14.  Note that  these  values
        are given for the real mode versions, the protected mode versions
        usually exceed them.  These limitations should be enough even for
        the biggest project that could be mentioned.

        The calling of nested include files is limited by the  number  of
        files  which can be opened simultaneously (operating system resp.
        compiler dependent).  The ISO/ANSI C  minimum  for  include  file
        nesting  levels  is  8,  this demand will be fulfilled by CFT and
        CST.

        The integrated C-preprocessor limits the size of expanded  macros
        to  6  Kbytes.  The  number  of  macros simultaneously defined is
        unlimited (ISO/ANSI: 1024) and only  affected  by  the  available
        memory.   The  number  of  macro  parameters  is  limited  to  31
        (ISO/ANSI: 31) and there are  up  to  31  significant  characters
        (ISO/ANSI:  31)  recognised.  The conditional compilation nesting
        levels of '#if...' control blocks is limited to 32 (ISO/ANSI: 8).

        The line length is unlimited (ISO/ANSI: logical  line  length  is
        509 characters).  The number of characters in a string (including
        '\0') is 2048 (ISO/ANSI: 509).  The  number  of  members  in  one
        structure/union  is  unlimited  (ISO/ANSI:  127),  the  number of
        structure/union nesting levels is unlimited (ISO/ANSI: 15).

        The recognition of identifiers like function and  variable  names
        follows  the  standard rules: an identifier consists of upper and
        lower case letters (A-Z,  a-z),  underscore (_) and digits (0-9),
        additionally  the  dollar  sign  ($)  will be accepted.  National
        character set extensions as  they  are  usual  for  languages  in
        european countries like Germany, Denmark or Sweden can be defined
        with option -J.

        C++  comments  '//...' are usually only recognised if option -C++
        is set.  However,  to accept the non-standard extension  of  some
        compilers which allow such comments also in C source code, option
        -// can be used therefore.  Nested C style comments '/*...*/' are
        not allowed and will always produce warnings.

        CFT and CST may produce  warnings  with  wrong  line  numbers  if
        preprocessing  is  enabled  (option -P) and if the warning occurs
        inside a comment.  The reason is that line number synchronisation
        with '#line ...' is only guaranteed for executable source but not
        for  comments.  In  such  a  situation  the source code should be
        processed without  -P  to  get  the  correct  line  number  (such
        warnings are usually related to unexpected characters).





                                     - 20 -


        The  calculation  depth  of  the  critical  function call path or
        structure nesting level  is  unlimited.  The  calculation  is  an
        extremely    recursive function and was successfully tested up to
        more than 100 nesting levels.  It is not known from which nesting
        level on stack overflow will happen.

        CFT  cannot recognise and reference a function if it is used with
        its pure name,  without parentheses.  This happens if a  function
        name  is  assigned  to  a  function pointer variable or used as a
        function pointer argument in a function call. Indirect calls to a
        function via a function pointer cannot  be  resolved.  A  similar
        case  with  FFT is the use of function names as formal parameters
        and their use within subroutines or functions.

        CFT will be confused in some rare cases by extensive type-casting
        operations like 'void __based(void) * __cdecl ...  ()'  and  will
        display  unexpected  messages.  A  function prototype declaration
        inside a function block ('function  given  scope')  will  not  be
        recognised by CFT.  In assembler source code, some definitions of
        local  variables  seem  to  look  like  a  function  or  a  label
        definition  and are treated by CFT like that although this may be
        wrong in some cases.  It is also not always possible to detect  a