blob: 183ca30ad37a794f151a9ab691716f6a55c32b6f [file] [log] [blame]
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001*if_cscop.txt* For Vim version 7.0aa. Last change: 2005 Mar 29
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Andy Kahn
5
6 *cscope* *Cscope*
7This document explains how to use Vim's cscope interface.
8
9Cscope is a tool like ctags, but think of it as ctags on steroids since it
10does a lot more than what ctags provides. In Vim, jumping to a result from
11a cscope query is just like jumping to any tag; it is saved on the tag stack
12so that with the right keyboard mappings, you can jump back and forth between
13functions as you normally would with |tags|.
14
151. Cscope introduction |cscope-intro|
162. Cscope related commands |cscope-commands|
173. Cscope options |cscope-options|
184. How to use cscope in Vim |cscope-howtouse|
195. Limitations |cscope-limitations|
206. Suggested usage |cscope-suggestions|
217. Availability & Information |cscope-info|
22
23This is currently for Unix and Win32 only.
24{Vi does not have any of these commands}
25
26==============================================================================
271. Cscope introduction *cscope-intro*
28
29The following text is taken from a version of the cscope man page:
30
31 -----
32
33 Cscope is an interactive screen-oriented tool that helps you:
34
35 Learn how a C program works without endless flipping through a thick
36 listing.
37
38 Locate the section of code to change to fix a bug without having to
39 learn the entire program.
40
41 Examine the effect of a proposed change such as adding a value to an
42 enum variable.
43
44 Verify that a change has been made in all source files such as adding
45 an argument to an existing function.
46
47 Rename a global variable in all source files.
48
49 Change a constant to a preprocessor symbol in selected lines of files.
50
51 It is designed to answer questions like:
52 Where is this symbol used?
53 Where is it defined?
54 Where did this variable get its value?
55 What is this global symbol's definition?
56 Where is this function in the source files?
57 What functions call this function?
58 What functions are called by this function?
59 Where does the message "out of space" come from?
60 Where is this source file in the directory structure?
61 What files include this header file?
62
63 Cscope answers these questions from a symbol database that it builds the
64 first time it is used on the source files. On a subsequent call, cscope
65 rebuilds the database only if a source file has changed or the list of
66 source files is different. When the database is rebuilt the data for the
67 unchanged files is copied from the old database, which makes rebuilding
68 much faster than the initial build.
69
70 -----
71
72When cscope is normally invoked, you will get a full-screen selection
73screen allowing you to make a query for one of the above questions.
74However, once a match is found to your query and you have entered your
75text editor to edit the source file containing match, you cannot simply
76jump from tag to tag as you normally would with vi's Ctrl-] or :tag
77command.
78
79Vim's cscope interface is done by invoking cscope with its line-oriented
80interface, and then parsing the output returned from a query. The end
81result is that cscope query results become just like regular tags, so
82you can jump to them just like you do with normal tags (Ctrl-] or :tag)
83and then go back by popping off the tagstack with Ctrl-T. (Please note
84however, that you don't actually jump to a cscope tag simply by doing
85Ctrl-] or :tag without remapping these commands or setting an option.
86See the remaining sections on how the cscope interface works and for
87suggested use.)
88
89
90==============================================================================
912. Cscope related commands *cscope-commands*
92
93 *:cscope* *:cs* *:scs* *:scscope* *E259* *E262* *E561* *E560*
94All cscope commands are accessed through suboptions to the main cscope
95command ":cscope". The shortest abbreviation is ":cs". The ":scscope"
96command does the same and also splits the window (short: "scs").
97
98The available subcommands are:
99
100 *E563* *E564* *E566* *E568* *E569* *E622* *E623*
101 *E625* *E626* *E609*
102 add : Add a new cscope database/connection.
103
104 USAGE :cs add {file|dir} [pre-path] [flags]
105
106 [pre-path] is the pathname used with the -P command to cscope.
107
108 [flags] are any additional flags you want to pass to cscope.
109
110 EXAMPLES >
111 :cscope add /usr/local/cdb/cscope.out
112 :cscope add /projects/vim/cscope.out /usr/local/vim
113 :cscope add cscope.out /usr/local/vim -C
114<
115 *cscope-find* *cs-find*
116 *E565* *E567*
117 find : Query cscope. All cscope query options are available
118 except option #5 ("Change this grep pattern").
119
120 USAGE :cs find {querytype} {name}
121
122 {querytype} corresponds to the actual cscope line
123 interface numbers as well as default nvi commands:
124
125 0 or s: Find this C symbol
126 1 or g: Find this definition
127 2 or d: Find functions called by this function
128 3 or c: Find functions calling this function
129 4 or t: Find this text string
130 6 or e: Find this egrep pattern
131 7 or f: Find this file
132 8 or i: Find files #including this file
133
134 EXAMPLES >
135 :cscope find c vim_free
136 :cscope find 3 vim_free
137<
138 These two examples perform the same query. >
139
140 :cscope find 0 DEFAULT_TERM
141<
142 Executing this example on the source code for Vim 5.1 produces the
143 following output:
144
145 Cscope tag: DEFAULT_TERM
146 # line filename / context / line
147 1 1009 vim-5.1-gtk/src/term.c <<GLOBAL>>
148 #define DEFAULT_TERM (char_u *)"amiga"
149 2 1013 vim-5.1-gtk/src/term.c <<GLOBAL>>
150 #define DEFAULT_TERM (char_u *)"win32"
151 3 1017 vim-5.1-gtk/src/term.c <<GLOBAL>>
152 #define DEFAULT_TERM (char_u *)"pcterm"
153 4 1021 vim-5.1-gtk/src/term.c <<GLOBAL>>
154 #define DEFAULT_TERM (char_u *)"ansi"
155 5 1025 vim-5.1-gtk/src/term.c <<GLOBAL>>
156 #define DEFAULT_TERM (char_u *)"vt52"
157 6 1029 vim-5.1-gtk/src/term.c <<GLOBAL>>
158 #define DEFAULT_TERM (char_u *)"os2ansi"
159 7 1033 vim-5.1-gtk/src/term.c <<GLOBAL>>
160 #define DEFAULT_TERM (char_u *)"ansi"
161 8 1037 vim-5.1-gtk/src/term.c <<GLOBAL>>
162 # undef DEFAULT_TERM
163 9 1038 vim-5.1-gtk/src/term.c <<GLOBAL>>
164 #define DEFAULT_TERM (char_u *)"beos-ansi"
165 10 1042 vim-5.1-gtk/src/term.c <<GLOBAL>>
166 #define DEFAULT_TERM (char_u *)"mac-ansi"
167 11 1335 vim-5.1-gtk/src/term.c <<set_termname>>
168 term = DEFAULT_TERM;
169 12 1459 vim-5.1-gtk/src/term.c <<set_termname>>
170 if (STRCMP(term, DEFAULT_TERM))
171 13 1826 vim-5.1-gtk/src/term.c <<termcapinit>>
172 term = DEFAULT_TERM;
173 14 1833 vim-5.1-gtk/src/term.c <<termcapinit>>
174 term = DEFAULT_TERM;
175 15 3635 vim-5.1-gtk/src/term.c <<update_tcap>>
176 p = find_builtin_term(DEFAULT_TERM);
177 Enter nr of choice (<CR> to abort):
178
179 The output shows several pieces of information:
180 1. The tag number (there are 15 in this example).
181 2. The line number where the tag occurs.
182 3. The filename where the tag occurs.
183 4. The context of the tag (e.g., global, or the function name).
184 5. The line from the file itself.
185
186 help : Show a brief synopsis.
187
188 USAGE :cs help
189
190 *E260* *E261*
191 kill : Kill a cscope connection (or kill all cscope connections).
192
193 USAGE :cs kill {num|partial_name}
194
195 To kill a cscope connection, the connection number or a partial
196 name must be specified. The partial name is simply any part of
197 the pathname of the cscope database. Kill a cscope connection
198 using the partial name with caution!
199
200 If the specified connection number is -1, then _ALL_ cscope
201 connections will be killed.
202
203 reset : Reinit all cscope connections.
204
205 USAGE :cs reset
206
207 show : Show cscope connections.
208
209 USAGE :cs show
210
Bram Moolenaarc7453f52006-02-10 23:20:28 +0000211 *:lcscope* *:lcs*
212This command is same as the ":cscope" command, except when the
213'cscopequickfix' option is set, the location list for the current window is
214used instead of the quickfix list to show the cscope results.
215
Bram Moolenaar071d4272004-06-13 20:20:40 +0000216 *:cstag* *E257* *E562*
217If you use cscope as well as ctags, |:cstag| allows you to search one or
218the other before making a jump. For example, you can choose to first
219search your cscope database(s) for a match, and if one is not found, then
220your tags file(s) will be searched. The order in which this happens
221is determined by the value of |csto|. See |cscope-options| for more
222details.
223
224|:cstag| performs the equivalent of ":cs find g" on the identifier when
225searching through the cscope database(s).
226
227|:cstag| performs the equivalent of |:tjump| on the identifier when searching
228through your tags file(s).
229
230
231==============================================================================
2323. Cscope options *cscope-options*
233
234Use the |:set| command to set all cscope options. Ideally, you would do
235this in one of your startup files (e.g., .vimrc). Some cscope related
236variables are only valid within |.vimrc|. Setting them after vim has
237started will have no effect!
238
239 *cscopeprg* *csprg*
240'cscopeprg' specifies the command to execute cscope. The default is
241"cscope". For example: >
242 :set csprg=/usr/local/bin/cscope
243<
244 *cscopequickfix* *csqf* *E469*
245{not available when compiled without the |+quickfix| feature}
246'cscopequickfix' specifies whether to use quickfix window to show cscope
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000247results. This is a list of comma-separated values. Each item consists of
Bram Moolenaar071d4272004-06-13 20:20:40 +0000248|cscope-find| command (s, g, d, c, t, e, f or i) and flag (+, - or 0).
249'+' indicates that results must be appended to quickfix window,
250'-' implies previous results clearance, '0' or command absence - don't use
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000251quickfix. Search is performed from start until first command occurrence.
252The default value is "" (don't use quickfix anyway). The following value
Bram Moolenaar009b2592004-10-24 19:18:58 +0000253seems to be useful: >
254 :set cscopequickfix=s-,c-,d-,i-,t-,e-
255<
Bram Moolenaar071d4272004-06-13 20:20:40 +0000256 *cscopetag* *cst*
257If 'cscopetag' set, the commands ":tag" and CTRL-] as well as "vim -t" will
258always use |:cstag| instead of the default :tag behavior. Effectively, by
259setting 'cst', you will always search your cscope databases as well as your
260tag files. The default is off. Examples: >
261 :set cst
262 :set nocst
263<
264 *cscopetagorder* *csto*
265The value of 'csto' determines the order in which |:cstag| performs a search.
266If 'csto' is set to zero, cscope database(s) are searched first, followed
267by tag file(s) if cscope did not return any matches. If 'csto' is set to
268one, tag file(s) are searched before cscope database(s). The default is zero.
269Examples: >
270 :set csto=0
271 :set csto=1
272<
273 *cscopeverbose* *csverb*
274If 'cscopeverbose' is not set (the default), messages will not be printed
275indicating success or failure when adding a cscope database. Ideally, you
276should reset this option in your |.vimrc| before adding any cscope databases,
277and after adding them, set it. From then on, when you add more databases
278within Vim, you will get a (hopefully) useful message should the database fail
279to be added. Examples: >
280 :set csverb
281 :set nocsverb
282<
283 *cscopepathcomp* *cspc*
284The value of 'cspc' determines how many components of a file's path to
285display. With the default value of zero the entire path will be displayed.
286The value one will display only the filename with no path. Other values
287display that many components. For example: >
288 :set cspc=3
289will display the last 3 components of the file's path, including the file
290name itself.
291
292==============================================================================
2934. How to use cscope in Vim *cscope-howtouse*
294
295The first thing you need to do is to build a cscope database for your
296source files. For the most basic case, simply do "cscope -b". Please
297refer to the cscope man page for more details.
298
299Assuming you have a cscope database, you need to "add" the database to Vim.
300This establishes a cscope "connection" and makes it available for Vim to use.
301You can do this in your .vimrc file, or you can do it manually after starting
302vim. For example, to add the cscope database "cscope.out", you would do:
303
304 :cs add cscope.out
305
306You can double-check the result of this by executing ":cs show". This will
307produce output which looks like this:
308
309 # pid database name prepend path
310 0 28806 cscope.out <none>
311
312Note:
313Because of the Microsoft RTL limitations, Win32 version shows 0 instead
314of the real pid.
315
316Once a cscope connection is established, you can make queries to cscope and
317the results will be printed to you. Queries are made using the command
318":cs find". For example:
319
320 :cs find g ALIGN_SIZE
321
322This can get a little cumbersome since one ends up doing a significant
323amount of typing. Fortunately, there are ways around this by mapping
324shortcut keys. See |cscope-suggestions| for suggested usage.
325
326If the results return only one match, you will automatically be taken to it.
327If there is more than one match, you will be given a selection screen to pick
328the match you want to go to. After you have jumped to the new location,
329simply hit Ctrl-T to get back to the previous one.
330
331
332==============================================================================
3335. Limitations *cscope-limitations*
334
335Cscope support for Vim is only available on systems that support these four
336system calls: fork(), pipe(), execl(), waitpid(). This means it is mostly
337limited to Unix systems.
338
339Additionally Cscope support works for Win32. For more information and a
340cscope version for Win32 see:
341
342 http://iamphet.nm.ru/cscope/index.html
343
Bram Moolenaar5eb86f92004-07-26 12:53:41 +0000344The DJGPP-built version from http://cscope.sourceforge.net is known to not
345work with Vim.
346
Bram Moolenaar071d4272004-06-13 20:20:40 +0000347There are a couple of hard-coded limitations:
348
349 1. The maximum number of cscope connections allowed is 8. Do you
350 really need more?
351
352 2. Doing a |:tjump| when |:cstag| searches the tag files is not
353 configurable (e.g., you can't do a tselect instead).
354
355==============================================================================
3566. Suggested usage *cscope-suggestions*
357
358Put these entries in your .vimrc (adjust the pathname accordingly to your
359setup): >
360
361 if has("cscope")
362 set csprg=/usr/local/bin/cscope
363 set csto=0
364 set cst
365 set nocsverb
366 " add any database in current directory
367 if filereadable("cscope.out")
368 cs add cscope.out
369 " else add database pointed to by environment
370 elseif $CSCOPE_DB != ""
371 cs add $CSCOPE_DB
372 endif
373 set csverb
374 endif
375
376By setting 'cscopetag', we have effectively replaced all instances of the :tag
377command with :cstag. This includes :tag, Ctrl-], and "vim -t". In doing
378this, the regular tag command not only searches your ctags generated tag
379files, but your cscope databases as well.
380
381Some users may want to keep the regular tag behavior and have a different
382shortcut to access :cstag. For example, one could map Ctrl-_ (underscore)
383to :cstag with the following command: >
384
385 map <C-_> :cstag <C-R>=expand("<cword>")<CR><CR>
386
387A couple of very commonly used cscope queries (using ":cs find") is to
388find all functions calling a certain function and to find all occurrences
389of a particular C symbol. To do this, you can use these mappings as an
390example: >
391
392 map g<C-]> :cs find 3 <C-R>=expand("<cword>")<CR><CR>
393 map g<C-\> :cs find 0 <C-R>=expand("<cword>")<CR><CR>
394
395These mappings for Ctrl-] (right bracket) and Ctrl-\ (backslash) allow you to
396place your cursor over the function name or C symbol and quickly query cscope
397for any matches.
398
399Or you may use the following scheme, inspired by Vim/Cscope tutorial from
400Cscope Home Page (http://cscope.sourceforge.net/): >
401
402 nmap <C-_>s :cs find s <C-R>=expand("<cword>")<CR><CR>
403 nmap <C-_>g :cs find g <C-R>=expand("<cword>")<CR><CR>
404 nmap <C-_>c :cs find c <C-R>=expand("<cword>")<CR><CR>
405 nmap <C-_>t :cs find t <C-R>=expand("<cword>")<CR><CR>
406 nmap <C-_>e :cs find e <C-R>=expand("<cword>")<CR><CR>
407 nmap <C-_>f :cs find f <C-R>=expand("<cfile>")<CR><CR>
408 nmap <C-_>i :cs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
409 nmap <C-_>d :cs find d <C-R>=expand("<cword>")<CR><CR>
410
411 " Using 'CTRL-spacebar' then a search type makes the vim window
412 " split horizontally, with search result displayed in
413 " the new window.
414
415 nmap <C-Space>s :scs find s <C-R>=expand("<cword>")<CR><CR>
416 nmap <C-Space>g :scs find g <C-R>=expand("<cword>")<CR><CR>
417 nmap <C-Space>c :scs find c <C-R>=expand("<cword>")<CR><CR>
418 nmap <C-Space>t :scs find t <C-R>=expand("<cword>")<CR><CR>
419 nmap <C-Space>e :scs find e <C-R>=expand("<cword>")<CR><CR>
420 nmap <C-Space>f :scs find f <C-R>=expand("<cfile>")<CR><CR>
421 nmap <C-Space>i :scs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
422 nmap <C-Space>d :scs find d <C-R>=expand("<cword>")<CR><CR>
423
424 " Hitting CTRL-space *twice* before the search type does a vertical
425 " split instead of a horizontal one
426
427 nmap <C-Space><C-Space>s
428 \:vert scs find s <C-R>=expand("<cword>")<CR><CR>
429 nmap <C-Space><C-Space>g
430 \:vert scs find g <C-R>=expand("<cword>")<CR><CR>
431 nmap <C-Space><C-Space>c
432 \:vert scs find c <C-R>=expand("<cword>")<CR><CR>
433 nmap <C-Space><C-Space>t
434 \:vert scs find t <C-R>=expand("<cword>")<CR><CR>
435 nmap <C-Space><C-Space>e
436 \:vert scs find e <C-R>=expand("<cword>")<CR><CR>
437 nmap <C-Space><C-Space>i
438 \:vert scs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
439 nmap <C-Space><C-Space>d
440 \:vert scs find d <C-R>=expand("<cword>")<CR><CR>
441
442==============================================================================
4437. Cscope availability and information *cscope-info*
444
445If you do not already have cscope (it did not come with your compiler
446license or OS distribution), then you can download it for free from:
447 http://cscope.sourceforge.net/
448This is released by SCO under the BSD license.
449
450If you want a newer version of cscope, you will probably have to buy it.
451According to the (old) nvi documentation:
452
453 You can buy version 13.3 source with an unrestricted license
454 for $400 from AT&T Software Solutions by calling +1-800-462-8146.
455
456Also you can download cscope 13.x and mlcscope 14.x (multi-lingual cscope
457which supports C, C++, Java, lex, yacc, breakpoint listing, Ingres, and SDL)
458from World-Wide Exptools Open Source packages page:
459 http://www.bell-labs.com/project/wwexptools/packages.html
460
461In Solaris 2.x, if you have the C compiler license, you will also have
462cscope. Both are usually located under /opt/SUNWspro/bin
463
464SGI developers can also get it. Search for Cscope on this page:
465 http://freeware.sgi.com/index-by-alpha.html
466 https://toolbox.sgi.com/toolbox/utilities/cscope/
467The second one is for those who have a password for the SGI toolbox.
468
469There is source to an older version of a cscope clone (called "cs") available
470on the net. Due to various reasons, this is not supported with Vim.
471
472The cscope interface/support for Vim was originally written by
473Andy Kahn <ackahn@netapp.com>. The original structure (as well as a tiny
474bit of code) was adapted from the cscope interface in nvi. Please report
475any problems, suggestions, patches, et al., you have for the usage of
476cscope within Vim to him.
477 *cscope-win32*
478For a cscope version for Win32 see: http://iamphet.nm.ru/cscope/index.html
479
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000480Win32 support was added by Sergey Khorev <sergey.khorev@gmail.com>. Contact
Bram Moolenaarb23c3382005-01-31 19:09:12 +0000481him if you have Win32-specific issues.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000482
483 vim:tw=78:ts=8:ft=help:norl: