home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / browser2.zip / INSTALL < prev    next >
Text File  |  1995-02-17  |  9KB  |  256 lines
  1. Copyright (c) 1993-1995 Gerd Moellmann
  2. $Id: INSTALL,v 3.1 1995/02/17 18:21:38 mmann Exp $
  3.  
  4.              C++ SOURCE CODE BROWSER v3.1
  5.               INSTALLATION INSTRUCTIONS
  6.  
  7.         MS-DOS users, please read INSTALL.DOS instead
  8.  
  9.  
  10.  
  11. Overview
  12. --------
  13.  
  14. I am myself working in C++ commercial software projects for several
  15. years now, and in these projects I always missed software support for
  16. two things:
  17.  
  18. When a new class library is introduced or you have to work on some
  19. source code you haven't written yourself (or written sufficiently long
  20. ago) you need a tool letting you navigate through class hierarchies
  21. and investigate features of the software. Without such a tool you often
  22. end up grep'ing through dozens or even hundreds of files.
  23.  
  24. Once you are productive, it would be nice to have a tool that knows your
  25. sources and can help you while you are editing source code.  Imagine to
  26. be able to jump to the definition of an identifier while you are
  27. editing, or something that can complete long identifier names because it
  28. knows what identifiers are defined in your program...
  29.  
  30. The design of the C++ class browser reflects these two needs;
  31. therefore the name class browser is really only half the truth.
  32.  
  33. How does it work? 
  34.  
  35. A fast parser written in C is used to parse C++ source and header
  36. files.  The parser generates a database containing information about
  37. identifiers---classes, members, global functions, types etc.
  38.  
  39. The second part of the C++ browser is a Lisp program.  This package
  40. reads the database generated by the parser; it displays its contents
  41. in various forms and allows you to perform operations on it, or with
  42. the help of the knowledge contained in it.
  43.  
  44. The "navigational" use of the browser is centered around two main
  45. buffer types which define their own major modes:
  46.  
  47. "Tree buffers" are used to view class hierarchies in tree form.  They
  48. allow you to quickly find classes, find or view a class declaration,
  49. perform operations like query replace on sets of files containing
  50. classes, and finally they are used to produce the second buffer form:
  51. member displays.
  52.  
  53. Members are displayed in "member buffers".  The browser distinguishes
  54. between six different types of members; each type is displayed as a
  55. member list of its own:
  56.  
  57.     * Instance member variables,
  58.     * Instance member functions,
  59.     * Static member variables,
  60.     * Static member functions,
  61.     * Friends,
  62.     * Types (enums, and typedefs defined with class scope.
  63.  
  64. You can quickly switch member buffers from one list to another, or to
  65. another class, you can include inherited members in a display, you can
  66. set filters, and most important of all you can edit or view member
  67. declarations and definitions with a keystroke.
  68.  
  69. These two buffer types and the commands they provide support the
  70. "navigational" use of the browser. The second form resembles the
  71. "tags" package for C and some other procedural languages that is part
  72. of the standard Emacs distribution; its commands are not bound to
  73. special buffer types but are most often used while you are editing
  74. your source code.
  75.  
  76. To list just some of what you can use the @dfn{tags} part of the browser
  77. for:
  78.  
  79.     * Quickly jump to the definition or declaration of an
  80.       identifier in your source code.     
  81.  
  82.     * Complete identifiers in your source---just type in a few
  83.       characters and let Emacs fill in the rest.
  84.  
  85.     * Perform search and query replace operations over some
  86.       or all of your source files.
  87.  
  88.     * Show all identifiers matching a regular expression---and
  89.       jump to one of them, if you like.
  90.  
  91. The browser has already been used in projects containing hundreds of
  92. classes. The maximum project size that has been successfully tried so
  93. long was about 500,000 lines of code. With Emacs 18.55 it runs on an
  94. MS-DOS notebook with 4 Mb of RAM and has no problems to handle
  95. projects up to about 70,000 lines of code.
  96.  
  97.  
  98. Prerequisites
  99. -------------
  100.  
  101. To use the source code browser you need at least:
  102.  
  103.   - Emacs 18 or 19 installed on your system,
  104.   
  105.   - a C compiler to compile the C part of the browser (GCC is
  106.     fine of course),
  107.  
  108.   - `gzip' unpacker to decompress the source archive,
  109.  
  110.   - a `tar' to unpack the files in the archive.
  111.  
  112.  
  113. Installation
  114. ------------
  115.  
  116. It is recommended to install the package outside of the Emacs
  117. directory tree to make upgrading both Emacs or the browser easier.
  118. Choose a place where the browser package should go, make a directory
  119. with a name of your choice, e.g. `browser'
  120.  
  121.     cd xy
  122.     mkdir browser
  123.     cd browser
  124.  
  125. Copy the C++ browser archive to this directory and unpack it:
  126.  
  127.     cp wherever/cppbrwsr.tar.gz .
  128.     gzip -d cppbrwsr.tar.gz
  129.     tar xvf cppbrwsr.tar
  130.     rm *.tar
  131.  
  132. This will create the following files in the `browser' directory:
  133.  
  134.     br-*.el        Lisp source files for the Lisp part of the
  135.             browser.
  136.     cl*.el        Lisp source files for the Emacs Common Lisp 
  137.             compatibility package (this is only needed
  138.             if you are Emacs 18, since you should already
  139.             have it if you're using Emacs 19).
  140.     by*.el        Lisp source files for a modified version of the
  141.             Emacs 19 optimizing byte compiler. This is only
  142.             needed for Emacs 18).
  143.     *.c, *.h    C source files for the C part of the browser
  144.     makefile    A makefile for DMAKE 3.8 (you can compile the
  145.             C sources without using this).
  146.     README        A readme file.
  147.     INSTALL        The file you are currently reading.
  148.     INSTALL.DOS    Installation instructions for MS-DOS users.
  149.     COPYING        A copy of the GNU General Public License.
  150.  
  151.  
  152. Compiling under OS/2
  153. --------------------
  154.  
  155. The C part of the browser has been compiled with GNU C (EMX 0.9a) and
  156. IBM C Set++ 2.1 under OS/2 Warp. If you have DMAKE 3.8 available, use
  157. the following commands to compile:
  158.  
  159.     IBM C Set++ ->    dmake CC=icc
  160.     EMX 0.9a    ->    dmake
  161.  
  162. If you don't have DMAKE, use the commands (long lines shown with
  163. backslash at the end):
  164.  
  165.     IBM C Set++ ->    icc -Q+ -O -B"/noe" -DOS2=1 -Feebrowse.exe \
  166.                 lex.c parse.c sym.c setargv.obj
  167.  
  168.     EMX 0.9a    ->    gcc -O2 -DOS2=1 -DPROTOTYPES \
  169.                 lex.c parse.c sym.c -o ebrowse.exe
  170.  
  171. Copy `ebrowse.exe' to a directory in your PATH, e.g. to the `bin'
  172. directory of your Emacs installation.
  173.  
  174.  
  175. Compiling under Unix
  176. --------------------
  177.  
  178. There should be no problems compiling `ebrowse' under UNIX since the
  179. program doesn't contain OS specific code. If you are using an ANSI
  180. compatible compiler, define the macro `PROTOTYPES' on the command
  181. line:
  182.  
  183.     gcc -O2 -DPROTOTYPES lex.c parse.c sym.c -o ebrowse
  184.  
  185. If there are problems compiling under UNIX I would be interested to
  186. hear of them so that I can fix the sources.
  187.  
  188.  
  189. Compiling the Lisp Part (Emacs 19)
  190. ----------------------------------
  191.  
  192. Make sure that your Emacs has the Lisp compatibility package
  193. installed. If necessary, add the compile the files with the prefix
  194. `cl' in your Emacs Lisp directory and add the line 
  195.  
  196.     (require 'cl-19 "cl")
  197.  
  198. to your Emacs startup file `.emacs' (located in your `$HOME'
  199. directory). 
  200.  
  201. To compile the Lisp part of the browser, compile and load the files
  202.  
  203.     br-macro.el
  204.     br-struc.el
  205.  
  206. from inside Emacs (the easiest way to do this in Emacs 19 is to open a
  207. dired buffer and use the command `B'). After loading the compiled
  208. files `br-macro.elc' and `br-struc.elc', compile the rest of the Lisp
  209. files that start with the `br-' prefix.
  210.  
  211. The optimizing compiler of Emacs 19 will display a number of warnings
  212. during the compilation process, which can be ignored (it warns about
  213. the usage of buffer-local variables, and I didn't find a way to turn
  214. this useless warning off).
  215.  
  216.  
  217. Modifying your Emacs Startup File `.emacs'
  218. ------------------------------------------
  219.  
  220. After compiling, modify the Emacs Lisp load path to include the
  221. directory the browser was installed in:
  222.  
  223.     (setq emacs-load-path 
  224.           (append '("xyz/browser") emacs-load-path))
  225.  
  226. and add the following lines, following the `require' of the CL-19
  227.  package:
  228.  
  229.     (require 'browse "br-brows")
  230.     (require 'br-utils)
  231.  
  232.  
  233. Installing the Documentation
  234. ----------------------------
  235.  
  236. Compile the Texinfo file `browser.texi' using the command line
  237.  
  238.     makeinfo browser.texi
  239.  
  240. and modify the info search path to include the browser directory:
  241.  
  242.     (setq Info-directory-list
  243.           (append '("xyz/browser") Info-directory-list))
  244.  
  245. Load the file `dir' located in the `info' directory of your Emacs
  246. installation and add a line at the end of the file (omit the
  247. quotee): 
  248.  
  249.     `* Browser: (browser).        C++ Browser'
  250.  
  251. (make sure there is a newline at the end of the file). Save `dir' to
  252. disk. You should now be able to select the browser documentation in
  253. the Info browser of Emacs (`\C-h i). 
  254.     
  255.  
  256.              --- end of file ---