This is an emacs interface to the 'cscope' source cross-referencing tool (http://cscope.sf.net). It can answer such questions as
The 'cscope' tool does the actual searching and lookup, while xcscope.el provides a convenient interface.
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")
** Quick-start
Install xcscope.el through your system package manager or MELPA, or simply evaluate xcscope.el.
Evaluate
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 s | Find symbol. | | C-c s = | Find assignments to this symbol | | C-c s d | Find global definition. | | C-c s g | Find global definition (alternate binding). | | C-c s G | Find global definition without prompting. | | 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 navigation through the search results:
| C-c s b | Display cscope buffer. | | C-c s B | Auto display cscope buffer toggle. | | C-c s n | Next symbol. | | C-c s N | Next file. | | C-c s p | Previous symbol. | | C-c s P | Previous file. | | C-c s u | Pop mark. |
These pertain to setting and unsetting the variable, `cscope-initial-directory', (location searched for the cscope database directory):
| C-c s a | Set initial directory. | | C-c s A | Unset initial directory. |
These pertain to cscope database maintenance:
| 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. |
** 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:
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
The maintainer is Dima Kogan dima@secretsauce.net