This is the README for the "C Browsing and Analysis Toolkit"
(c-bat) Version 0.1i alpha !

This toolkit is a quick and dirty product what means that it is
not designed like a software product should be. In fact, it
grew more like a plant ;-) 

However, I will stop improving c-bat for the next couple of
month because of my exams ! But I think, this toolkit has
achieved a state, where it will be ready for releasing ! 

(I hope you think so too !)

However, the following two lines are still valid, so I can
keep track of the users of the 0.1-version ! Especially if you 
write own clients or do change or update something ! I am planning
to keep downward-compatibility, at least for the brs_... functions
defined clients.c ! But you can never be sure about that, so ...

PLEASE EMAIL ME IF YOU HAVE DOWNLOADED THIS RELEASE, BECAUSE
YOU WILL BE INFORMED ABOUT BUG FIXES AND UPDATES BY EMAIL !!!!

You can send email to:
stolz@fiffi.sta.sub.org            
or
stolz@informatik.tu-muenchen.de   (until April '94)

happy programming and analyzing !

Eckehard Stolz

p.s. Look in the file TODO for things next to come ...

p.p.s. Please read the entire document !


TABLE OF CONTENTS:

1. What is c-bat and how to use it
2. Installing
3. Using c-bat
4. Functions provided by the toolkit (programming with c-bat)
5. Format of the browser file
6. To do
7. Acknowledgement
8. Disclaimer


1. WHAT IS C-BAT AND HOW TO USE IT ****************************************

This tool is based on GCC (2.4.5 and 2.5.8) for Linux and is 
intented to help programmers understand foreign (or their 
own :-) code by analysing call-structures, use of variables, ...

It uses a client-server-concept where the server returns
information requested by client applications. Besides a single
example-client this toolkit provides a function library for 
retrieving information from the browser-server which can be
integrated in everyone's favorite programming environment.

First step is the compiling the project with a patched version of
GCC and the option "-aux-brs" (or "-aux-BRS"). This will generate
a browser-file for every source file with the same basename and the
extension ".brs" (e.g.  compiling "foo.c" will produce "foo.brs").
Aditionally, the preprocessor creates a ".brp" file for every source
file, which holds ALL macro definitions in this file !
If you use the option "-aux-BRS" instead of "-aux-brs", symbols declared
in system-include-files will also appear in the browser file, 
otherwise system-symbols (mostly library-calls or library-variables)
will be ommitted.

After compiling, all these browser-files have to be combined by the
browser-collector (brs_collect). This program creates a browser-control
file ending with ".brc" (name is specified with the -o option) which
lists all browser-files of the project in the given directory and their
working-directories. Multiple project-directories are handled by 
collecting browser-control-files from different directories. Aditionally, 
the preprocessor-files (.brp) will be collected and all written to a 
new file, ending with ".bri". The processed .brp-files will be deleted !
Please note that it is not possible to have two files with the same
filename within a project in the current version. This will change in
some of the next versions. Until then, you have to rename the double
filenames.

The total set of browser-files contains information about all
function- and data-definition, function calls, include-files, ...
in a tagged ASCII-format (explanation of this format see below).


brs_client
==========

You can use now the "brs_client"-programm to retrieve information 
about the project by giving the appropriate commands. Please note
that this is not intented as high-quality end-user-tool because
normally everyone has his own favorite programming enviroment.
In fact, the functions provided with the toolkit makes it easy
to integrate the functionality of the brs_client into your own
environment (availability of C-source code assumed) .

Please regard brs_client as an example of the possibilities 
given by this toolkit (in fact, I used it mainly to test my
browser-functions !). If you write some other useful clients,
please upload them to a appropriate ftp-site and send me an
email. Also, a sophisticated X-environment for a brs-client
would be something very nice and useful. So, if you like to
learn writing X-application and are looking for a challenge,
well, here is one !

After starting brs_client, you will see the first of a total of 4
menus with following options:

menu 1:

             FUNCTION-MENU
   'F'  Print all functions defined in project
   'c'  Print all functions called by a given function
   'C'  Like 'c', but print EVERY function call position)
   'u'  Print all variables used by a function
   'U'  Like 'U', but print EVERY usage position
   'b'  Print all functions calling a given function (!see note below *!)
   'B'  Like 'b', but for EVERY calling position
   'd'  Print definition position of a function

   '?'  Help Screen
   '+'  Next menu-screen (variable-menu)
   '-'  Previous menu-screen (misc-menu)

menu 2:

             VARIABLE-MENU
   'V'  Print all variables in project
   't'  Print all structs in project
   'n'  Print all unions in project
   'm'  Print all enums in project
   'y'  Print all typdefs in project
   's'  Print all functions using a variable
   'S'  Like 's', but for EVERY usage position
   'D'  Print definition position of a variable
   '.'  Print usage of a struct component
   ':'  Print usage of a struct component with a variable

   '?'  Help Screen
   '+'  Next menu-screen (file-menu)
   '-'  Previous menu-screen (function-menu)

menu 3:

               FILE-MENU
   'f'  Print all source-files in project
   'i'  Print all includes of a source-file
   'I'  Print all source files including a given file
   '#'  Print all macro defininitions in project
   '*'  Print position of a macro defininition
   'w'  Print working directory of a file

   '?'  Help Screen
   '+'  Next menu-screen (misc-menu)
   '-'  Previous menu-screen (variable-menu)

menu 4:

               MISC-MENU
   'l'  Clear Marking
   'T'  Set new Timeout-Time
   'a'  Get all messages in queue
   '['  Change viewer (currently: internal )
   'R'  Set new browsing-datafile in actual server
   'r'  Switch to a new server
   'k'  Kill server and exit
   'q'  Exit client (not killing server)

   '?'  Help Screen
   '+'  Next menu-screen (function-menu)
   '-'  Previous menu-screen (files-menu)


Additionally, you can view the returned position in the sourcefile and
dump the returned information to a file.

You can press '?' in any window for a Help-Screen !

*) Note: If you give "" as function name, all functions, which are called
         outside of all functions, will be returned. This is mostly the
         case when functions are used as function-pointers to initialize
         global function pointer data.

OTHER TOOLS PROVIDED IN THIS RELEASE:

brs_collect
===========

This programm collects all browser-files IN ONE DIRECTORY and creates
a browser-control-file (default: all.brc) with the names and the working
directories of these source-files. Support for multiple project-
directories is done by collecting the generated BROWSER-CONTROL-FILES
from their creation directory.

Restrictions:
- all browser-files (and the corresponding source-files) have to be
  in the actual directory (browser-control-files to be collected may 
  reside in other directories though)
  
- there must not be two source-files with the same name in one project !
  please rename them, if you have a project with two identical filenames
  in different directories

Usage: 
brs_collect [Options] <file1> <file2> ...
Collects all given browser-files in that directory and creates a
control-file (default-name: 'all.brc' )

Options:
-o <file>    specify name for output control-file

<file?> can be one of the following:
*.brs     ...  explicitly given browser-file
*.brp     ...  explicitly given browser preprocessor-file
*.brc     ...  control-file (might be in a different directory)
*.o, *.c  ...  takes basename and check's for *.brs and *.brc  

brs_calltree
============

Prints a calltree from a funtion. you can specify the output of this tree
by giving a formatfile or by setting the characters used to print the tree.

Usage: 
brs_calltree [Options] <funct> [<file>]
Print a calltree from function <funct>, defined in <file>
This program needs the browser-server run in background !

You will get a complete list of options if you call brs_calltree with
the option "-?" !


brs_extract
===========
This program is the stand-alone-test-version of a function called
"brs_cut", which tries to cut definition line, a possible leading
comment and the body of a function, a variable or a type definition.
It has not been tested very intensivly now and will definitly have
some bugs ! Please be so kind to report them with the piece of code
that produced the unexpected result.


Usage: 
brs_extract [Options] <source-file> <item> <lineno>
Browser-extract: tries to cut the definition line and a leading
comment out of the source code

<source-file>    ...  filename, where the item is defined
<item>           ...  identifier of the item to be extracted
<lineno>         ...  linenumber, where this item is defined
                      (because of the browser-bug with the linenumber
                       set to the first token AFTER the definition
                       this function does accept linenumber which are
                       within a range of the definition position !
                       BUT CAUTION: maybe it works, maybe not !)
Options:
-c    extract comment
-b    extract body
-n    item is NOT a function



brs_f_list
==========
This program prints a list of all functions defined in the project to
stdout. Functions are printed like this:

================================================================================
Function   : Exit
File       : brs_client.c    Line 205
Length     : 5 Lines
Declaration:
void Exit(int val )
--------------------------------------------------------------------------------
/* reset curses
 */


You can specify your own template-file, which will be used as format-string
for a printf with the following arguments: 
   function-identifier (char *)
   filename (char *)
   line number (long)
   length (long)
   definition line (char *)
   leading comment (char *)

This function header might be followed by a list of functions (or just their
definition files) which are called from this function. The same is possible
for functions calling this function.


Usage: brs_flist [Options] 
Prints a list of all functions defined in a project
This program needs the browser-server run in background !

Options:
-b <browser-file>    Connect to server processing this browser file
-ft <template-file>  Use this file as template for the function-list
                     It will be used for a printf-statement with the
                     following arguments: 
                     function (char *), file (char *), line (long)
                     number of lines (long)
                     
-q                   Quiet: Do not print information to stderr
-C                   Print heading comments
-c                   Print functions called by actual function
-c-                  Print only filenames of functions called
-g                   Print functions calling actual function
-g-                  Print only filenames of functions calling
-l<char per line>    set maximum characters per output line
-i<indent>           indent function-lists by <indent> characters 


Tools for debugging:
====================

debug_msg     ...  reads all messages in the queue
brs_sendcmd   ...  sends a message to a server. The return can be obtained
                   using debug_msg
brs_cleanup   ...  tries to kill all servers, removes the message queue 

2. INSTALLING *************************************************************

If you are using GCC 2.4.5 or 2.5.8, you can use the binary 
available for this packages. If not, you have to build your own 
GCC by applying the patches in "gcc245.tar.gz" or "gcc258.tar.gz"
to the GCC-sources (these versions only. But the changes are not so 
very big, so it might be easy to apply them to later versions)
If you do so, please upload the patches to the ftp-site
you downloaded this package from and send me an email).

However, both is risky, because you have to replace the original
compiler and have to change the specs !!!!! THIS MAY CAUSE YOUR
COMPILER NOT TO WORK ANYMORE !!!! BE SURE TO HAVE A COPY OF THE
INSTALLATION DISK HANDY. I DO NOT TAKE ANY RESPONSIBILITY FOR
DAMAGES TO YOUR SYSTEM (See disclaimer below !)

- Installing the binaries

  - The binaries are released as object files, so you can link them
    on your system wth the actual library you use
    just untar the archive and type:

    make -f Makefile.bin

    This should create two files called "cc1" (the compiler) and
    "cpp" (the preprocessor)

  - change to the directory, where your gcc-binaries are. This should
    normally be "/usr/lib/gcc-lib/i486-linux/2.4.5". You can verify
    that by typing "gcc -v" which tells you in "Reading specs from..."
    the appropriate directory

  - Save your original compiler, preprocessor and the specs-file by 
    copying specs to specs.backup
    and moving "cc1" to "cc1.old" and "cpp" to "cpp.old" by:

    cp specs specs.backup
    mv cc1 cc1.old
    mv cpp cpp.old

    (just in case :-)

  - copy the compiler and preprocessor from the directory, you just typed
    'make -f Makefile.bin' to the compiler-directory

  - edit the specs for the compiler. You have to add 

    %{aux-brs:-aux-brs} %{aux-BRS:-aux-BRS}

    to the "cc1"- and the "cpp"-line in the spec file. This should read like:

    ---------------------------------------------------
    *cpp:
    %{!m386:-D__i486__} %{posix:-D_POSIX_SOURCE} %{aux-brs:-aux-brs} %{aux-BRS:-aux-BRS}

    *cc1:
    %{aux-brs:-aux-brs} %{aux-BRS:-aux-BRS}
    ---------------------------------------------------
    (Note: These two lines came from my spec-file. Yours may differ
           from that !)

  - You can test now the new compiler by compiling any program. 
    It should behave totally like the original compiler. If you give the
    additional option "-aux-brs", there should be a ".brs" and a ".brp"file 
    created in the actual directory.

  - Compile all browser-programs by simply typing "make" in the src directory
    You should do that after the replacement of the compiler, because .brs
    files will be created for all browser-programs. Please note that you need
    the "ncurses" library (The Linux-curses library) installed. But I do
    not use curses functions heavily so any other curses-version should work
    as well.

  - copy the programs brs_server, brs_collect, brs_calltree and brs_client
    to the "/usr/bin"-drectory and set the apropriate file-permissions.

  - Installation is completed now.

Note: compiling with the new compiler may take more time, especially if
      you use the "-aux-brs" option !

Note: If you have problems compiling with the new version (especially if
      gcc says it could not find some system-include-files), please check the
      following directories. The directories, where cpp searches for include
      files by default, are hardcoded into "cpp". I used the following 
      predefined directories. Maybe a symbolic link helps to solve this
      problem

  GCC_INCLUDE_DIR       "/usr/local/lib/gcc-lib/i486-linux/2.4.5/include"
  GPLUSPLUS_INCLUDE_DIR "/usr/local/lib/g++-include"
  LOCAL_INCLUDE_DIR     "/usr/local/include"
  CROSS_INCLUDE_DIR     "/usr/local/lib/gcc-lib/i486-linux/2.4.5/sys-include"
  TOOL_INCLUDE_DIR      "/usr/local/i486-linux/include"
  TOOLDIR               "/usr/local/i486-linux/"


Note: If you want to build your own GCC-version: in the archive 
      "gcc245.tar.gz" and "gcc258.tar.gz" you find diff-files for GCC 
      version 2.4.5 and 2.5.8 and some notes for compiling it. 


3. USING C-BAT ************************************************************

COMPILING:

First, you have to compile alle sources of your project with the compiler-
option "-aux-brs" or "-aux-BRS" (if you want to have system-headers and 
library-function included - otherwise all system-headers and all symbols
declared inside this system-headers will be ignored) .

COLLECTING BROWSER-FILES:

After compiling all sources, you have to combine all .brs-files with the
brs_collect program together. This programm has to be called like the
ld (linker) with the option "-o <outfile>" and all brs-files. If the 
filenames given as arguments end with ".o" or ".c", brs_collect will
take the appropriate ".brs" and ".brp" files instead. So you can use 
the variables used in the makefile for calling brs_collect.
However, if you specify a "*.brs"-file in the command line, you should
also specify the corresponding "*.brp"-file. Only if the filename
ends with "*.c" or "*.o", both browser-files are automatically included
(e.g. "brs_collect -o project.brc m1.brs m1.brp m2.c mr.o $(OTHER_OBJ)" )


For analyzing the programm, you have to start the server with the filename
of the main browser-control-file. You have NOT to be in a specific directory
since all directories are stored in the control file.

BROWSER-SERVER:

Start the browser-server (brs_server) in background or in a single virtual
terminal (or xterm) with the browser-control-file as argument preceeded by
"-b" (e.g. "brs_server -b project.brc &"). This causes the server to 
initally scan all browser-files and to wait for commands sent by client
applications via IPC (message queues).

Options of brs_server:
-b <browser-file>  Use this Browser-File

-x <exclude-file>  Exclude symbols given in exclude-file

        An exclude-file is used, if you want to exclude some symbols (variables,
        functions, files, ...)
        This will mainly be used to prevent system-library-calls from being
        processed:

        format of exclude-file : one symbol per line

        example:   
        --------------------------
        strcmp
        strlen
        exit
        --------------------------

-m <module-file>   Combine source-files to modules given in <module-file>

        It is often useful to split a logical module into different files. 
        Especially for the outline-function, it is useful to specify logical
        modules by assigning a number of files to a module

        format: one symbol per line; first the module-name, then every 
                source-files distiguish modules

        example:   
        --------------------------
        MAIN
        main.c
        options.c
        init.c

        USER
        user1.c
        user2.c
        --------------------------


BROWSER-CLIENTS:

Now you can use any client application, which uses the library-functions
provided in this toolkit. They normally do not have to be started from
the project directory because they can get the paths from the server.
However, because there will (hopefully) be a lot of clients some day,
it depends on the given client itself !

The enclosed example-client ("brs_client") is an interactive program
using the curses library. It should be self-explaining. (if not, please
email me too !)

4. FUNCTIONS PROVIDED BY THE TOOLKIT **************************************

There are different functions for accessing the server. They are split into
two levels.

- Low Level Interfacing:
  Done by functions in 'intrface.c'. Used to establish connection and to 
  send commands and retrieve the information. In order to use them, you
  have to include the file 'c-bat.h'. You might only use them if you want 
  to write new Information Retrieving Functions or change the brs_server.
  
- Information Retrieving Functions
  These functions are defined in 'clients.c'. In order to use them, you also
  have to include 'c-bat.h' and the header-file 'clients.h'.
  Normally, the Information retrieving functions should be the only ones
  you use in your application. They take all the work with connection,
  timeout and fiddeling with the command- and return-arguments
  (according to the actual naming convention they all start with "brs_")

For further documentation, please refer to the file "README.programming"
or the source-files, the functions are also documented there.


5. FORMAT OF BROWSER FILE *************************************************

The format of the browser file is a tagged ASCII-format, which can easily
be processed by tools like grep, lex, awk, sed, ...

Every information-item is placed in a single line and is preceeded by a tag.
Every tag begins with '[' and ends with ']'.

There are following tags used:

---------------------------------------------------------------------------

[I?]"<filename>"  

Name of actual file (? ... 1 system include, 0 else)

examples:
[I0]"./config/i386/gstabs.h"
[I1]"/usr/include/sys/types.h"

---------------------------------------------------------------------------

[E?][l]"<identifier>"[d] ...  expression (function call, variable use)

 ? : 'F'  function call (internal function)
     'f'  function call (external function)
     'V'  use of variable defined in actual file
     'v'  use of external variable 
     'P'  use of formal parameter
     'T'  use of data type (I don't know, if this could ever occur)
     'C'  use of const (enum)

 l:  line number

 d:  position of definition
     [l]    ...  line number (l) in actual file
     [l<f>] ...  line number (l) and filename (f)

examples:
[Ef][1010]"fprintf"[132</usr/include/stdio.h>]
[EF][1045]"report_error_function"[972]
[EP][1029]"v"[1026]
[Ev][1012]"__std_filebuf_2"[114</usr/include/stdio.h>]
[EV][1013]"last_error_tick"[945]
---------------------------------------------------------------------------
[R]"<comp>""<ident>"     ...  reference to struct (or union) component
                              (of the variable <ident>)

example:
[EV][798]"tms"[778]           return (tms.tms_utime + tms.tms_stime);
[R]"tms_utime""tms"
[EV][798]"tms"[778]
[R]"tms_stime""tms"

---------------------------------------------------------------------------
[P][l]"<identifier>"     ...  definition of a macro

example:
[P][12]"TRUE"                 #define  TRUE

---------------------------------------------------------------------------
[f][l]"<identifier>"     ...  function declaration

l:  linenumber

Note: If there is a function without prototype called, [f] is used
      instead of [Ef].

examples:
[f][132]"fprintf"
---------------------------------------------------------------------------

[Dv?][l]"<identifier>"   ...  declaration of external variable

? : s  ... static variable
       ... external variable

examples:
[Dv][1361]"pedantic"

---------------------------------------------------------------------------
[DV?][l]"<identifier>"   ...  variable definition

? : s  ... static variable
       ... external variable

examples:
[DVs][389]"flag_rerun_cse_after_loop"
[DV][394]"flag_inline_functions"

---------------------------------------------------------------------------
[De][l]"<identifier>"    ...  definition of const (enum)

---------------------------------------------------------------------------
[DE][l]"<identifier>"    ...  definition of enum type

example:
[DE][378]"reg_class"

---------------------------------------------------------------------------
[DS][l]"<identifier>"    ...  definition of struct

example:
[DS][84]"fd_set"
---------------------------------------------------------------------------
[DU][l]"<identifier>"    ...  definition of union

example:
[DU][319]"real_extract"
---------------------------------------------------------------------------
[DT][l]"<identifier>"    ...  definition of type (typedef)

example:
[DT][6]"size_t"

---------------------------------------------------------------------------
[F?][l]"<identifier>"    ...  function definition

?  ...  s  =  static Funktion

example:
[F][2824]"main"
[Fs][931]"decl_name"
---------------------------------------------------------------------------
[fe][l]                  ...  ende of function definition

---------------------------------------------------------------------------
[EOFxxx]                 ...  end of browser file section 
                               (one section per source-file)

xxx ... file-offset (start after last 'F')
        not used at the moment.

5. BUGS *******************************************************************

- c-bat works only with C, not with C++ or Objective C

- line numbers are not correct with structs, unions or function definitions.
  They are set to the line of the first item after the struct, union, ...
  Annoying, but I didn't find any easy way to get around this !

- function-pointers will regarded as function calls

- identical [I?] tags may appear multiple times. Makes the brs-Files bigger,
  but is harmless !

- brs_extract will not handle #ifdef #else #endif correctly !

- files with identical filenames are not allowed within a project

- lot's and lot's of others knows and mostly unknown bugs !

If you find things to add to this list, please send a bug report with source
file, browser file and a short discription to:

stolz@fiffi.sta.sub.org !


6. TO DO ******************************************************************

- interactive environment for online-browsing under X11

- providing information about types of variables, parameters

- scoping information

- support for local variables

- _usage_ of macros in the source-files

- better documentation (man pages !!)

- generation of documentation-pages for a specific function or module

- binary format for combined browser-info with faster access and less
  redundancy

- print cross-reference table

- ....

see file TODO 


7. ACKNOWLEDGMENT *********************************************************

   I would like to thank the following people, who have assisted me by
   testing, sending bug-reports, giving ideas or just sending christmas
   greetings :-) THIS LIST IS NOT COMPLETE of course ! If I forgot
   someone, please tell me instead of beeing offended ! This list is
   in no order (or ordered by the time they got onto my adress-list :-)

   Harry Ohlsen
   Erik Troan
   Stephen Hill
   Bart Schuller
   Raimund K. Ege
   Dietmar Braun
   Marc Papen
   Paul T. Keener
   Juergen Schreier

8. COPYRIGHT / DISCLAIMER *************************************************

   This package and all enclosed files are copyrighted by 
   Eckehard Stolz (1993) except the files copyrighted by anyone else.

   However, it is distributed under the terms of the GNU GENERAL PUBLIC 
   LICENCE (see the File COPYRIGHT enclosed) !


			    NO WARRANTY

  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.


Bug reports, comments and suggestion are greatly appreciated and should be 
sent to:

stolz@fiffi.sta.sub.org


Eckehard Stolz