README.org

Overview

This is an emacs interface to the ‘cscope’ source cross-referencing tool (http://cscope.sf.net). It can answer such questions as

• Where is this variable used?
• What is the value of this preprocessor symbol?
• Where is this function in the source files?
• What functions call this function?
• What functions are called by this function?
• Where does the message “out of space” come from?
• Where is this source file in the directory structure?
• What files include this header file?
• Where was this variable assigned-to?

The ‘cscope’ tool does the actual searching and lookup, while xcscope.el provides a convenient interface.

GNU Global support

GNU global (http://www.gnu.org/s/global/) is another source indexer much like cscope. It’s better than cscope in some ways and worse in others. It also provides a compatibility interface to allow it to be used just like cscope. This means that xcscope.el can be used as a front-end to GNU Global. To do that, simply evaluate

(setq cscope-program “gtags-cscope”)

Usage

Quick-start

1. Install xcscope.el through your system package manager or MELPA, or simply evaluate xcscope.el.
2. Evaluate

• (require ‘xcscope)
• (cscope-setup)

Done! cscope-minor-mode is now hooked to C, C++ and dired modes. Default bindings are all prefixed with C-c s. So, for instance, to find a symbol do C-c s s. This is analogous to the M-. of tags. All results are shown in a new cscope buffer which pops up when needed.

More-detailed usage instructions

When xcscope.el is active, you can just use the keybindings (described below) when looking at source. You can also use the Cscope menu or a mouse pop-up menu (button 3).

When a search is performend, by default xcscope.el will traverse the directory hierarchy upwards, looking for the cscope database. If it doesn’t find it, a new database will be made in the current directory. To create the database in a different (higher) directory, explicitly invoke C-c s I. A currently-existing database can be removed simply by deleting cscope.*. By default, cscope updates the database with every search. This is very convenient, but can be too slow for very large source trees.

The third mouse button is bound to a popup menu for cscope. Shift-mouse button 3 invokes the last find command again. E.g. if you look for the symbol ‘main’ and afterwards you want to look for another symbol, just press Shift and click the third button.

Search results are displayed in a cscope buffer, which pops up when results are available. 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]. You can also press [space] to show the result in the other window (cscope buffer stays focused). Alternately, the navigation commands invoked with n/p, show the results too.

Each cscope search adds its results to the cscope buffer. Thus this buffer contains a history of all past searches. These sets of results can be navigated and manupulated similar to patches in diff-mode:

• n/p navigates over individual results
• k kills individual results
• N/P or M-n/M-p navigates over file results
• M-k kills file results
• M-N/M-P navigates over result sets
• M-K kills result sets
• Navigation from outside the cscope buffer (C-c s n/p/N/P) is restricted to the result set at (point)

Any result set in the cscope buffer can be re-run with the ‘r’ key. This is useful if the sources changed

Keybindings:

All keybindings use the “C-c s” prefix:

C-c s sFind symbol.C-c s =Find assignments to this symbolC-c s dFind global definition.C-c s gFind global definition (alternate binding).C-c s GFind global definition without prompting.C-c s cFind functions calling a function.C-c s CFind called functions (list functions called from a function).C-c s tFind text string.C-c s eFind egrep pattern.C-c s fFind a file.C-c s iFind files #including a file.

These pertain to navigation through the search results:

C-c s bDisplay cscope buffer.C-c s BAuto display cscope buffer toggle.C-c s nNext symbol.C-c s NNext file.C-c s pPrevious symbol.C-c s PPrevious file.C-c s uPop mark.

These pertain to setting and unsetting the variable, `cscope-initial-directory’, (location searched for the cscope database directory):

C-c s aSet initial directory.C-c s AUnset initial directory.

These pertain to cscope database maintenance:

C-c s LCreate list of files to index.C-c s ICreate list and index.C-c s EEdit list of files to index.C-c s WLocate this buffer’s cscope directory (“W” –> “where”).C-c s SLocate this buffer’s cscope directory. (alternate binding: “S” –> “show”).C-c s TLocate this buffer’s cscope directory. (alternate binding: “T” –> “tell”).C-c s DDired this buffer’s directory.

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-option-….

  Various options passed to the ‘cscope’ process. Controls things like include directories, database compression, database type, etc.

• cscope-display-cscope-buffer

  If non-nil, display the cscope buffer after each search (default). This variable can be set in order to reduce the number of keystrokes required to navigate through the matches.

Provenance

This is a continuation of the xcscope.el (by Darryl Okahata) that ships in the CVS tree of cscope itself. The code in the cscope tree is stable, so this tree expands on the original source, fixing various bugs and adding features.

New features relative to the cscope CVS tree

• (cscope-setup) must be called to enable cscope-minor-mode in C and C++ major modes
• New searches are appended to the cscope buffer, instead of overwriting. The user thus sees a history of cscope search results in this buffer, and is able to navigate through all of them. There is a size limit to keep the buffer from growing out of control.
• The cscope buffer can be navigated and edited similarly to emacs Diff buffers:
  • n/p navigates over individual results
  • k kills individual results
  • N/P or M-n/M-p navigates over file results
  • M-k kills file results
  • M-N/M-P navigates over result sets
  • M-K kills result sets
  • Navigation from outside the cscope buffer (C-c s n/p/N/P) is restricted to the result set at (point)
• Previous searches can be re-run with the ‘r’ key in the cscope buffer. These are written in-place, overwriting the older results.
• Fuzzy matching is now enabled/disabled for specific types of searches. This was implemented earlier, but the implementation had a bug and wasn’t working
• xcscope.el can now work remotely over TRAMP
• The cscope-index output now goes to the echo area instead of an explicit new buffer that the user must deal with
• Fuzzy searching now works for non-trivial regex searches
• The mouse face respects cscope-use-face
• Better mouse support:
  • button3 opens a popup menu that runs prompt-less searches
  • shift-button3 reruns the last search on the point. This is thus even more prompt-less
• Shift-return or Shift-mouse2 now open the result in the same window as the cscope buffer
• Some bold highlighting in the cscope results: the sought term, the search directory
• Removed the external ‘cscope-indexer’ script; this is now handled inside xcscope.el. Additionally the list of source directories to ignore and the list of filename extensions to index are now customizable in the emacs customization interface
• Various cscope options (kernel mode, inverted index, etc) can now be accessed through the emacs variables

License and authorship

xcscope.el was written by Darryl Okahata, with patches contributed by Triet H. Lai and Steven Elliott. Dima Kogan added some features.

xcscope.el is distributed under the terms of version 2 (or later) of the GNU General Public License

Contact

The maintainer is Dima Kogan <[email protected]>