home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / browser2.zip / README < prev    next >
Text File  |  1995-02-17  |  6KB  |  165 lines
  1. $Id: README,v 3.1 1995/02/17 18:21:38 mmann Exp $
  2.  
  3.                A C++ Source Code Browser
  4.             Gerd Moellmann, mmann@ibm.net
  5.  
  6. Overview
  7. --------
  8.  
  9. I am myself working in C++ commercial software projects for several
  10. years now, and in these projects I always missed software support for
  11. two things:
  12.  
  13. When a new class library is introduced or you have to work on some
  14. source code you haven't written yourself (or written sufficiently long
  15. ago) you need a tool letting you navigate through class hierarchies
  16. and investigate features of the software. Without such a tool you often
  17. end up grep'ing through dozens or even hundreds of files.
  18.  
  19. Once you are productive, it would be nice to have a tool that knows your
  20. sources and can help you while you are editing source code.  Imagine to
  21. be able to jump to the definition of an identifier while you are
  22. editing, or something that can complete long identifier names because it
  23. knows what identifiers are defined in your program...
  24.  
  25. The design of the C++ class browser reflects these two needs;
  26. therefore the name class browser is really only half the truth.
  27.  
  28. How does it work? 
  29.  
  30. A fast parser written in C is used to parse C++ source and header
  31. files.  The parser generates a database containing information about
  32. identifiers---classes, members, global functions, types etc.
  33.  
  34. The second part of the C++ browser is a Lisp program.  This package
  35. reads the database generated by the parser; it displays its contents
  36. in various forms and allows you to perform operations on it, or with
  37. the help of the knowledge contained in it.
  38.  
  39. The "navigational" use of the browser is centered around two main
  40. buffer types which define their own major modes:
  41.  
  42. "Tree buffers" are used to view class hierarchies in tree form.  They
  43. allow you to quickly find classes, find or view a class declaration,
  44. perform operations like query replace on sets of files containing
  45. classes, and finally they are used to produce the second buffer form:
  46. member displays.
  47.  
  48. Members are displayed in "member buffers".  The browser distinguishes
  49. between six different types of members; each type is displayed as a
  50. member list of its own:
  51.  
  52.     * Instance member variables,
  53.     * Instance member functions,
  54.     * Static member variables,
  55.     * Static member functions,
  56.     * Friends,
  57.     * Types (enums, and typedefs defined with class scope.
  58.  
  59. You can quickly switch member buffers from one list to another, or to
  60. another class, you can include inherited members in a display, you can
  61. set filters, and most important of all you can edit or view member
  62. declarations and definitions with a keystroke.
  63.  
  64. These two buffer types and the commands they provide support the
  65. "navigational" use of the browser. The second form resembles the
  66. "tags" package for C and some other procedural languages that is part
  67. of the standard Emacs distribution; its commands are not bound to
  68. special buffer types but are most often used while you are editing
  69. your source code.
  70.  
  71. To list just some of what you can use the @dfn{tags} part of the browser
  72. for:
  73.  
  74.     * Quickly jump to the definition or declaration of an
  75.       identifier in your source code.     
  76.  
  77.     * Complete identifiers in your source---just type in a few
  78.       characters and let Emacs fill in the rest.
  79.  
  80.     * Perform search and query replace operations over some
  81.       or all of your source files.
  82.  
  83.     * Show all identifiers matching a regular expression---and
  84.       jump to one of them, if you like.
  85.  
  86. The browser has already been used in projects containing hundreds of
  87. classes. The maximum project size that has been successfully tried so
  88. long was about 500,000 lines of code. With Emacs 18.55 it runs on an
  89. MS-DOS notebook with 4 Mb of RAM and has no problems to handle
  90. projects up to about 70,000 lines of code.
  91.  
  92.  
  93. Prereqisites
  94. ------------
  95.  
  96. You must have Emacs 18.x or 19.x installed on your system. You must
  97. have a C compiler running on your system (GCC preferred). 
  98.  
  99.  
  100. Operating Systems
  101. -----------------
  102.  
  103. The system has been in use for more than 2 years on
  104.  
  105.     OS/2 >= 2.0     with Emacs 19.19 and greater
  106.     MS-DOS         with DJ Emacs 18.55
  107.  
  108. Unix ports should be trivial (Emacs lisp sources are portable, use GCC
  109. to compile the rest).
  110.  
  111. The system has been used in projects with more than 800 Kloc code
  112. (it's not a toy :-)).
  113.  
  114.  
  115. Installation
  116. ------------
  117.  
  118. The standard distribution consists of a GZIP'ed tar archive. To unpack
  119. this archive use the following commands:
  120.  
  121.     gzip -d C++-browser.tar.gz
  122.     tar xvf C++-browser.tar
  123.  
  124. This will create a directory named `browser' under the current
  125. directory containing all files in the distrubution:
  126.  
  127.     README        The file you are currently reading.
  128.     INSTALL        Installation description.
  129.     LICENSE        The GNU General Public License.
  130.     *.el        Emacs Lisp source files.
  131.     *.c        C source files compilable with GNU C.
  132.             and other compilers.
  133.     *.h        C include files.
  134.     makefile    Makefile for DMAKE v3.8.
  135.     browser.texi    Hypertext helo source file for Emacs.
  136.  
  137. Follow the instructions in `INSTALL' to install the package.
  138.  
  139.  
  140.  
  141. Legal Stuff
  142. -----------
  143.  
  144. The C++ source code browser is free software; you can redistribute it
  145. and/or modify it under the terms of the GNU General Public License as
  146. published by the Free Software Foundation; either version 2, or (at
  147. your option) any later version.
  148.  
  149. The C++ source code browser is distributed in the hope that it will be
  150. useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
  151. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  152. General Public License for more details.
  153.  
  154. You should have received a copy of the GNU General Public License
  155. along with the C++ source code browser; see the file COPYING. if not,
  156. write to the Free Software Foundation, 675 Mass Ave, Cambridge, MA
  157. 02139, USA.
  158.  
  159. See the files COPYING.GEM and COPYING for details.
  160.  
  161. Instead of a list: All the trademarks used in this document and the
  162. other documents in the C++ source code browser package are registered
  163. to whoever it is that owns them.
  164.  
  165.             --- end of file ---