1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
|
* 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 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:
- 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 <dima@secretsauce.net>
|
