1XCSCOPE.EL(1) General Commands Manual XCSCOPE.EL(1)
3
7 xcscope.el - xemacs cscope lisp support package
8
10 xcscope is a lisp package for use in integrating cscope functionality
11 into xemacs
12
14 Installation steps:
15 0. (It is, of course, assumed that cscope is already properly
18 installed on the current system.)
19 1. Ensure that the location of cscope-indexer is located in your path
21 2. Ensure that the location of xcscope.el is in the xemacs module load
24 path
25 3. Edit your ~/.emacs file to add the line:
28 (require'xcscope)
30 5. If you intend to use xcscope.el often you can optionally edit your
33 ~/.emacs file to add keybindings that reduce the number of keystrokes
34 required. For example, the following will add "C-f#" keybindings,
35 which are easier to type than the usual "C-c s" prefixed keybindings.
36 Note that specifying "global-map" instead of "cscope:map" makes the
37 keybindings available in all buffers:
38 (define-key global-map [(ctrl f3)] 'cscope-set-initial-directory)
39 (define-key global-map [(ctrl f4)] 'cscope-unset-initial-directory)
40 (define-key global-map [(ctrl f5)] 'cscope-find-this-symbol)
41 (define-key global-map [(ctrl f6)] 'cscope-find-global-definition)
42 (define-key global-map [(ctrl f7)]
43 cscope-find-global-definition-no-prompting)
44 (define-key global-map [(ctrl f8)] 'cscope-pop-mark)
45 (define-key global-map [(ctrl f9)] 'cscope-next-symbol)
46 (define-key global-map [(ctrl f10)] 'cscope-next-file)
47 (define-key global-map [(ctrl f11)] 'cscope-prev-symbol)
48 (define-key global-map [(ctrl f12)] 'cscope-prev-file)
49 (define-key global-map [(meta f9)] 'cscope-display-buffer)
50 (define-key global-map [(meta f10)] 'cscope-display-buffer-toggle)
51 6. Restart (X)Emacs. That's it.
54
58 * Basic usage:
59 If all of your C/C++/lex/yacc source files are in the same
60 directory, you can just start using this module. If your files are
61 spread out over multiple directories, see "Advanced usage", below.
62 Just edit a source file, and use the pull-down or pop-up (button 3)
65 menus to select one of:
66 Find symbol
68 Find global definition
69 Find called functions
70 Find functions calling a function
71 Find text string
72 Find egrep pattern
73 Find a file
74 Find files #including a file
75 The cscope database will be automatically created in the same directory
78 as the source files (assuming that you've never used cscope before),
79 and a buffer will pop-up displaying the results. You can then use but‐
80 ton 2 (the middle button) on the mouse to edit the selected file, or
81 you can move the text cursor over a selection and press [Enter].
82 Hopefully, the interface should be fairly intuitive.
85 * Locating the cscope databases:
88 This module will first use the variable, `cscope-database-regexps', to
89 search for a suitable database directory. If a database location can‐
90 not be found using this variable then a search is begun at the vari‐
91 able, `cscope-initial-directory', if set, or the current directory oth‐
92 erwise. If the directory is not a cscope database directory then the
93 directory's parent, parent's parent, etc. is searched until a cscope
94 database directory is found, or the root directory is reached. If the
95 root directory is reached, the current directory will be used.
96 A cscope database directory is one in which EITHER a cscope database
99 file (e.g., "cscope.out") OR a cscope file list (e.g., "cscope.files")
100 exists. If only "cscope.files" exists, the corresponding "cscope.out"
101 will be automatically created by cscope when a search is done. By
102 default, the cscope database file is called "cscope.out", but this can
103 be changed (on a global basis) via the variable, `cscope-database-
104 file'. There is limited support for cscope databases that are named
105 differently than that given by `cscope-database-file', using the vari‐
106 able, `cscope-database-regexps'.
107 Note that the variable, `cscope-database-regexps', is generally not
110 needed, as the normal hierarchical database search is sufficient for
111 placing and/or locating the cscope databases. However, there may be
112 cases where it makes sense to place the cscope databases away from
113 where the source files are kept; in this case, this variable is used to
114 determine the mapping. One use for this variable is when you want to
115 share the database file with other users; in this case, the database
116 may be located in a directory separate from the source files.
117 Setting the variable, `cscope-initial-directory', is useful when a
120 search is to be expanded by specifying a cscope database directory that
121 is a parent of the directory that this module would otherwise use. For
122 example, consider a project that contains the following cscope database
123 directories:
124 /users/jdoe/sources
126 /users/jdoe/sources/proj1
127 /users/jdoe/sources/proj2
128 If a search is initiated from a .c file in /users/jdoe/sources/proj1
131 then (assuming the variable, `cscope-database-regexps', is not set)
132 /users/jdoe/sources/proj1 will be used as the cscope data base direc‐
133 tory. Only matches in files in /users/jdoe/sources/proj1 will be
134 found. This can be remedied by typing "C-c s a" and then "M-del" to
135 remove single path element in order to use a cscope database directory
136 of /users/jdoe/sources. Normal searching can be restored by typing "C-
137 c s A".
138 * Keybindings:
143 All keybindings use the "C-c s" prefix, but are usable only while edit‐
144 ing a source file, or in the cscope results buffer:
145 C-c s s Find symbol.
147 C-c s d Find global definition.
149 C-c s g Find global definition (alternate binding).
151 C-c s G Find global definition without prompting.
153 C-c s c Find functions calling a function.
155 C-c s C Find called functions (list functions called
157 from a function).
158 C-c s t Find text string.
160 C-c s e Find egrep pattern.
162 C-c s f Find a file.
164 C-c s i Find files #including a file.
166 These pertain to navigation through the search results:
169 C-c s b Display *cscope* buffer.
172 C-c s B Auto display *cscope* buffer toggle.
174 C-c s n Next symbol.
176 C-c s N Next file.
178 C-c s p Previous symbol.
180 C-c s P Previous file.
182 C-c s u Pop mark.
184 These pertain to setting and unsetting the variable, `cscope-initial-
187 directory', (location searched for the cscope database directory):
188 C-c s a Set initial directory.
191 C-c s A Unset initial directory.
193 These pertain to cscope database maintenance:
196 C-c s L Create list of files to index.
198 C-c s I Create list and index.
200 C-c s E Edit list of files to index.
202 C-c s W Locate this buffer's cscope directory
204 ( "W" --> "where" ).
205 C-c s S Locate this buffer's cscope directory.
207 (alternate binding: "S" --> "show" ).
208 C-c s T Locate this buffer's cscope directory.
210 (alternate binding: "T" --> "tell" ).
211 C-c s D Dired this buffer's directory.
213 * Advanced usage:
216 If the source files are spread out over multiple directories, you've
217 got a few choices:
218 [ NOTE: you will need to have the script, "cscope-indexer", properly
221 installed in order for the following to work. ]
222 1. If all of the directories exist below a common directory (without
225 any extraneous, unrelated subdirectories), you can tell this module to
226 place the cscope database into the top-level, common directory. This
227 assumes that you do not have any cscope databases in any of the subdi‐
228 rectories. If you do, you should delete them; otherwise, they will
229 take precedence over the top-level database.
230 If you do have cscope databases in any subdirectory, the following
233 instructions may not work right.
234 It's pretty easy to tell this module to use a top-level, common direc‐
237 tory:
238 a. Make sure that the menu pick, "Cscope/Index recursively", is checked
241 (the default value).
242 b. Select the menu pick, "Cscope/Create list and index", and specify
245 the top-level directory. This will run the script, "cscope-
246 indexer", in the background, so you can do other things if
247 indexing takes a long time. A list of files to index will be
248 created in "cscope.files", and the cscope database will be cre‐
249 ated in "cscope.out".
250 Once this has been done, you can then use the menu picks (described in
253 "Basic usage", above) to search for symbols.
254 Note, however, that, if you add or delete source files, you'll have to
257 either rebuild the database using the above procedure, or edit
258 the file, "cscope.files" to add/delete the names of the source
259 files. To edit this file, you can use the menu pick,
260 "Cscope/Edit list of files to index".
261 2. If most of the files exist below a common directory, but a few are
264 outside, you can use the menu pick, "Cscope/Create list of files to
265 index", and specify the top-level directory. Make sure that
266 "Cscope/Index recursively", is checked before you do so, though. You
267 can then edit the list of files to index using the menu pick,
268 "Cscope/Edit list of files to index". Just edit the list to include
269 any additional source files not already listed.
270 Once you've created, edited, and saved the list, you can then use the
273 menu picks described under "Basic usage", above, to search for symbols.
274 The first time you search, you will have to wait a while for cscope to
275 fully index the source files, though. If you have a lot of source
276 files, you may want to manually run cscope to build the database:
277 cd top-level-directory # or wherever
279 rm -f cscope.out # not always necessary
280 cscope -b
281 3. If the source files are scattered in many different, unrelated
284 places, you'll have to manually create cscope.files and put a
285 list of all pathnames into it. Then build the database using:
286 cd some-directory # wherever cscope.files exists
288 rm -f cscope.out # not always necessary
289 cscope -b
290 Next, read the documentation for the variable, "cscope-database-reg‐
293 exps", and set it appropriately, such that the above-created cscope
294 database will be referenced when you edit a related source file.
295 Once this has been done, you can then use the menu picks described
298 under "Basic usage", above, to search for symbols.
299 * Interesting configuration variables:
302 cscope-truncate-lines
303 This is the value of `truncate-lines' to use in cscope buffers; the
305 default is the current setting of `truncate-lines'. This variable
306 exists because it can be easier to read cscope buffers with truncated
307 lines, while other buffers do not have truncated lines.
308 cscope-use-relative-paths
311 If non-nil, use relative paths when creating the list of files to
313 index. The path is relative to the directory in which the cscope data‐
314 base will be created. If nil, absolute paths will be used. Absolute
315 paths are good if you plan on moving the database to some other direc‐
316 tory (if you do so, you'll probably also have to modify `cscope-data‐
317 base-regexps'). Absolute paths may also be good if you share the data‐
318 base file with other users (you'll probably want to specify some auto‐
319 mounted network path for this).
320 cscope-index-recursively
323 If non-nil, index files in the current directory and all subdirecto‐
325 ries. If nil, only files in the current directory are indexed. This
326 variable is only used when creating the list of files to index, or when
327 creating the list of files and the corresponding cscope database.
328 cscope-name-line-width
331 The width of the combined "function name:line number" field in the
333 cscope results buffer. If negative, the field is left-justified.
334 cscope-do-not-update-database
337 If non-nil, never check and/or update the cscope database when search‐
339 ing. Beware of setting this to non-nil, as this will disable automatic
340 database creation, updating, and maintenance.
341 cscope-display-cscope-buffer
344 If non-nil, display the *cscope* buffer after each search (default).
346 This variable can be set in order to reduce the number of keystrokes
347 required to navigate through the matches.
348 cscope-database-regexps
351 List to force directory-to-cscope-database mappings. This is a list of
353 `(REGEXP DBLIST [ DBLIST ... ])', where:
354 REGEXP is a regular expression matched against the current buffer's
357 current directory. The current buffer is typically some source file,
358 and you're probably searching for some symbol in or related to this
359 file. Basically, this regexp is used to relate the current directory
360 to a cscope database. You need to start REGEXP with "^" if you want to
361 match from the beginning of the current directory.
362 DBLIST is a list that contains one or more of:
365 ( DBDIR )
367 ( DBDIR ( OPTIONS ) )
368 ( t )
369 t
370 Here, DBDIR is a directory (or a file) that contains a cscope database.
373 If DBDIR is a directory, then it is expected that the cscope database,
374 if present, has the filename given by the variable, `cscope-database-
375 file'; if DBDIR is a file, then DBDIR is the path name to a cscope
376 database file (which does not have to be the same as that given by
377 `cscope-database-file'). If only DBDIR is specified, then that cscope
378 database will be searched without any additional cscope command-line
379 options. If OPTIONS is given, then OPTIONS is a list of strings, where
380 each string is a separate cscope command-line option.
381 In the case of "( t )", this specifies that the search is to use the
384 normal hierarchical database search. This option is used to
385 explicitly search using the hierarchical database search either before
386 or after other cscope database directories.
387 If "t" is specified (not inside a list), this tells the searching
390 mechanism to stop searching if a match has been found (at the point
391 where "t" is encountered). This is useful for those projects that
392 consist of many subprojects. You can specify the most-used
393 subprojects first, followed by a "t", and then followed by a master
394 cscope database directory that covers all subprojects. This will
395 cause the most-used subprojects to be searched first (hopefully
396 quickly), and the search will then stop if a match was found. If not,
397 the search will continue using the master cscope database directory.
398 Here, `cscope-database-regexps' is generally not used, as the normal
401 hierarchical database search is sufficient for placing and/or locating
402 the cscope databases. However, there may be cases where it makes
403 sense to place the cscope databases away from where the source files
404 are kept; in this case, this variable is used to determine the
405 mapping.
406 This module searches for the cscope databases by first using this
409 variable; if a database location cannot be found using this variable,
410 then the current directory is searched, then the parent, then the
411 parent's parent, until a cscope database directory is found, or the
412 root directory is reached. If the root directory is reached, the
413 current directory will be used.
414 A cscope database directory is one in which EITHER a cscope database
417 file (e.g., "cscope.out") OR a cscope file list (e.g., "cscope.files")
418 exists. If only "cscope.files" exists, the corresponding "cscope.out"
419 will be automatically created by cscope when a search is done. By
420 default, the cscope database file is called "cscope.out", but this can
421 be changed (on a global basis) via the variable, `cscope-database-
422 file'. There is limited support for cscope databases that are named
423 differently than that given by `cscope-database-file', using the vari‐
424 able, `cscope-database-regexps'.
425 Here is an example of `cscope-database-regexps':
428 (setq cscope-database-regexps
430 '(
431 ( "^/users/jdoe/sources/proj1"
432 ( t )
433 ( "/users/jdoe/sources/proj2")
434 ( "/users/jdoe/sources/proj3/mycscope.out")
435 ( "/users/jdoe/sources/proj4")
436 t
437 ( "/some/master/directory" ("-d" "-I/usr/local/include") )
438 )
439 ( "^/users/jdoe/sources/gnome/"
440 ( "/master/gnome/database" ("-d") )
441 )
442 ))
443 If the current buffer's directory matches the regexp,
446 "^/users/jdoe/sources/proj1", then the following search will be done:
447 1. First, the normal hierarchical database search will be used to
450 locate a cscope database.
451 2. Next, searches will be done using the cscope database
454 directories, "/users/jdoe/sources/proj2",
455 "/users/jdoe/sources/proj3/mycscope.out", and
456 "/users/jdoe/sources/proj4". Note that, instead of the file,
457 "cscope.out", the file, "mycscope.out", will be used in the
458 directory "/users/jdoe/sources/proj3".
459 3. If a match was found, searching will stop.
462 4. If a match was not found, searching will be done using
465 "/some/master/directory", and the command-line options "-d" and
466 "-I/usr/local/include" will be passed to cscope.
467 If the current buffer's directory matches the regexp,
470 "^/users/jdoe/sources/gnome", then the following search will be
471 done:
472 The search will be done only using the directory,
475 "/master/gnome/database". The "-d" option will be passed to
476 cscope.
477 If the current buffer's directory does not match any of the above
480 regexps, then only the normal hierarchical database search will
481 be done.
482 * Other notes:
485 1. The script, "cscope-indexer", uses a sed command to determine what
486 is and is not a C/C++/lex/yacc source file. It's idea of a source file
487 may not correspond to yours.
488 2. This module is called, "xcscope", because someone else has already
491 written a "cscope.el" (although it's quite old).
492
495 1. Cannot handle whitespace in directory or file names.
496 2. By default, colored faces are used to display results. If you hap‐
499 pen to use a black background, part of the results may be invisible
500 (because the foreground color may be black, too). There are at least
501 two solutions for this:
502 2a. Turn off colored faces, by setting `cscope-use-face' to `nil', eg:
505 (setq cscope-use-face nil)
507 2b. Explicitly set colors for the faces used by cscope. The faces are
510 cscope-file-face
512 cscope-function-face
513 cscope-line-number-face
514 cscope-line-face
515 cscope-mouse-face
516 The face most likely to cause problems (e.g., black-on-black
519 color) is `cscope-line-face'.
520 3. The support for cscope databases different from that specified by
523 `cscope-database-file' is quirky. If the file does not exist, it will
524 not be auto-created (unlike files names by `cscope-database-file').
525 You can manually force the file to be created by using touch(1) to cre‐
526 ate a zero-length file; the database will be created the next time a
527 search is done.
528Darryl Okahata April 2000 XCSCOPE.EL(1)