5:05 p.m.
FYI,
I've been working on yet another cscope minor mode. This one's
specific to XEmacs. Although I'd call this an alpha release, it has a
number of nice features (e.g., searches are done in the background). If
you'd like an idea of what it can do, I've appended a copy of the
(minimal) usage instructions to the end of this message.
You can get a copy at:
ftp://ftp.sonic.net/pub/users/darrylo/cscope/cscope-xemacs-0.80.tar.gz
This being an alpha release, there's no README file; see the comments at
the beginning of xcscope.el for installation instructions, etc..
Please send any comments and complaints to me.
--
Darryl Okahata
darrylo(a)soco.agilent.com
DISCLAIMER: this message is the author's personal opinion and does not
constitute the support, opinion, or policy of Agilent Technologies, or
of the little green men that have been following him all day.
===============================================================================
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;; ***** USING THIS MODULE *****
;;
;; * Basic usage:
;;
;; If all of your C/C++/lex/yacc source files are in the same
;; directory, you can just start using this module. If your files are
;; spread out over multiple directories, see "Advanced usage", below.
;;
;; Just edit a source file, and use the pull-down or pop-up (button 3)
;; menus to select one of:
;;
;; Find symbol
;; Find global definition
;; Find called functions
;; Find functions calling a function
;; Find text string
;; Find egrep pattern
;; Find a file
;; Find files #including a file
;;
;; The cscope database will be automatically created in the same
;; directory as the source files (assuming that you've never used
;; cscope before), and a buffer will pop-up displaying the results.
;; You can then use button 2 (the middle button) on the mouse to edit
;; the selected file, or you can move the text cursor over a selection
;; and press [Enter].
;;
;; Hopefully, the interface should be fairly intuitive.
;;
;;
;; * Locating the cscope databases:
;;
;; This module will first use the variable, `cscope-database-regexps',
;; to search for a suitable database directory. If a database
;; location cannot be found using this variable, then the current
;; directory is searched, then the parent, then the parent's parent,
;; etc. until a cscope database directory is found, or the root
;; directory is reached. If the root directory is reached, the
;; current directory will be used.
;;
;; A cscope database directory is one in which EITHER a cscope
;; database file (e.g., "cscope.out") OR a cscope file list (e.g.,
;; "cscope.files") exists. If only "cscope.files" exists, the
;; corresponding "cscope.out" will be automatically created by cscope
;; when a search is done.
;;
;; Note that the variable, `cscope-database-regexps', is generally not
;; needed, as the normal hierarchical database search is sufficient
;; for placing and/or locating the cscope databases. However, there
;; may be cases where it makes sense to place the cscope databases
;; away from where the source files are kept; in this case, this
;; variable is used to determine the mapping. One use for this
;; variable is when you want to share the database file with other
;; users; in this case, the database may be located in a directory
;; separate from the source files.
;;
;;
;; * Keybindings:
;;
;; All keybindings use the "C-c s" prefix, but are usable only while
;; editing a source file, or in the cscope results buffer:
;;
;; C-c s s Find symbol.
;; C-c s d Find global definition.
;; C-c s g Find global definition (alternate binding).
;; C-c s c Find functions calling a function.
;; C-c s C Find called functions (list functions called
;; from a function).
;; C-c s t Find text string.
;; C-c s e Find egrep pattern.
;; C-c s f Find a file.
;; C-c s i Find files #including a file.
;;
;; These pertain to cscope database maintanance:
;;
;; C-c s L Create list of files to index.
;; C-c s I Create list and index.
;; C-c s E Edit list of files to index.
;; C-c s W Locate this buffer's cscope directory
;; ("W" --> "where").
;; C-c s S Locate this buffer's cscope directory.
;; (alternate binding: "S" --> "show").
;; C-c s T Locate this buffer's cscope directory.
;; (alternate binding: "T" --> "tell").
;; C-c s D Dired this buffer's directory.
;;
;;
;; * Advanced usage:
;;
;; If the source files are spread out over multiple directories,
;; you've got a few choices:
;;
;; [ NOTE: you will need to have the script, "cscope-indexer",
;; properly installed in order for the following to work. ]
;;
;; 1. If all of the directories exist below a common directory
;; (without any extraneous, unrelated subdirectories), you can tell
;; this module to place the cscope database into the top-level,
;; common directory. This assumes that you do not have any cscope
;; databases in any of the subdirectories. If you do, you should
;; delete them; otherwise, they will take precedence over the
;; top-level database.
;;
;; If you do have cscope databases in any subdirectory, the
;; following instructions may not work right.
;;
;; It's pretty easy to tell this module to use a top-level, common
;; directory:
;;
;; a. Make sure that the menu pick, "Cscope/Index recursively", is
;; checked (the default value).
;;
;; b. Select the menu pick, "Cscope/Create list and index", and
;; specify the top-level directory. This will run the script,
;; "cscope-indexer", in the background, so you can do other
;; things if indexing takes a long time. A list of files to
;; index will be created in "cscope.files", and the cscope
;; database will be created in "cscope.out".
;;
;; Once this has been done, you can then use the menu picks
;; (described in "Basic usage", above) to search for symbols.
;;
;; Note, however, that, if you add or delete source files, you'll
;; have to either rebuild the database using the above procedure,
;; or edit the file, "cscope.files" to add/delete the names of the
;; source files. To edit this file, you can use the menu pick,
;; "Cscope/Edit list of files to index".
;;
;;
;; 2. If most of the files exist below a common directory, but a few
;; are outside, you can use the menu pick, "Cscope/Create list of
;; files to index", and specify the top-level directory. Make sure
;; that "Cscope/Index recursively", is checked before you do so,
;; though. You can then edit the list of files to index using the
;; menu pick, "Cscope/Edit list of files to index". Just edit the
;; list to include any additional source files not already listed.
;;
;; Once you've created, edited, and saved the list, you can then
;; use the menu picks described under "Basic usage", above, to
;; search for symbols. The first time you search, you will have to
;; wait a while for cscope to fully index the source files, though.
;; If you have a lot of source files, you may want to manually run
;; cscope to build the database:
;;
;; cd top-level-directory # or whereever
;; rm -f cscope.out # not always necessary
;; cscope -b
;;
;;
;; 3. If the source files are scattered in many different, unrelated
;; places, you'll have to manually create cscope.files and put a
;; list of all pathnames into it. Then build the database using:
;;
;; cd some-directory # whereever cscope.files exists
;; rm -f cscope.out # not always necessary
;; cscope -b
;;
;; Next, read the documentation for the variable,
;; "cscope-database-regexps", and set it appropriately, such that
;; the above-created cscope database will be referenced when you
;; edit a related source file.
;;
;; Once this has been done, you can then use the menu picks
;; described under "Basic usage", above, to search for symbols.
;;
;;
;; * Interesting configuration variables:
;;
;; "cscope-truncate-lines"
;; This is the value of `truncate-lines' to use in cscope
;; buffers; the default is the current setting of
;; `truncate-lines'. This variable exists because it can be
;; easier to read cscope buffers with truncated lines, while
;; other buffers do not have truncated lines.
;;
;; "cscope-use-relative-paths"
;; If non-nil, use relative paths when creating the list of files
;; to index. The path is relative to the directory in which the
;; cscope database will be created. If nil, absolute paths will
;; be used. Absolute paths are good if you plan on moving the
;; database to some other directory (if you do so, you'll
;; probably also have to modify `cscope-database-regexps').
;; Absolute paths may also be good if you share the database file
;; with other users (you'll probably want to specify some
;; automounted network path for this).
;;
;; "cscope-index-recursively"
;; If non-nil, index files in the current directory and all
;; subdirectories. If nil, only files in the current directory
;; are indexed. This variable is only used when creating the
;; list of files to index, or when creating the list of files and
;; the corresponding cscope database.
;;
;; "cscope-name-line-width"
;; The width of the combined "function name:line number" field in
;; the cscope results buffer. If negative, the field is
;; left-justified.
;;
;; "cscope-do-not-update-database"
;; If non-nil, never check and/or update the cscope database when
;; searching. Beware of setting this to non-nil, as this will
;; disable automatic database creation, updating, and
;; maintenance.
;;
;; "cscope-database-regexps"
;; List to force directory-to-cscope-database mappings.
;; This is a list of `(REGEXP DIRECTORY OPTIONS)' triplets, where:
;;
;; REGEXP is a regular expression matched against the current
;; buffer's current directory. The current buffer is typically
;; some source file, and you're probably searching for some
;; symbol in or related to this file. Basically, this regexp is
;; used to relate the current directory to a cscope database.
;;
;; DIRECTORY is the name of the corresponding directory
;; containing (or will contain, if creating) the cscope database
;; files.
;;
;; OPTIONS is a string listing any additional options (e.g.,
;; "-d") to pass to the cscope executable. Normally, this
;; string is empty.
;;
;; All of the above are strings.
;;
;; This variable is generally not used, as the normal
;; hierarchical database search is sufficient for placing and/or
;; locating the cscope databases. However, there may be cases
;; where it makes sense to place the cscope databases away from
;; where the source files are kept; in this case, this variable
;; is used to determine the mapping.
;;
;; This module searches for the cscope databases by first using
;; this variable; if a database location cannot be found using
;; this variable, then the current directory is searched, then
;; the parent, then the parent's parent, until a cscope database
;; directory is found, or the root directory is reached. If the
;; root directory is reached, the current directory will be used.
;;
;; A cscope database directory is one in which EITHER a cscope
;; database file (e.g., "cscope.out") OR a cscope file list
;; (e.g., "cscope.files") exists.
;;
;;
;; * Other notes:
;;
;; 1. The script, "cscope-indexer", uses a sed command to determine
;; what is and is not a C/C++/lex/yacc source file. It's idea of a
;; source file may not correspond to yours.
;;
;; 2. This module is called, "xcscope", because someone else has
;; already written a "cscope.el" (although it's quite old).
;;