1 *if_cscop.txt* For Vim version 7.2b. Last change: 2005 Mar 29
4 VIM REFERENCE MANUAL by Andy Kahn
7 This document explains how to use Vim's cscope interface.
9 Cscope is a tool like ctags, but think of it as ctags on steroids since it
10 does a lot more than what ctags provides. In Vim, jumping to a result from
11 a cscope query is just like jumping to any tag; it is saved on the tag stack
12 so that with the right keyboard mappings, you can jump back and forth between
13 functions as you normally would with |tags|.
15 1. Cscope introduction |cscope-intro|
16 2. Cscope related commands |cscope-commands|
17 3. Cscope options |cscope-options|
18 4. How to use cscope in Vim |cscope-howtouse|
19 5. Limitations |cscope-limitations|
20 6. Suggested usage |cscope-suggestions|
21 7. Availability & Information |cscope-info|
23 This is currently for Unix and Win32 only.
24 {Vi does not have any of these commands}
26 ==============================================================================
27 1. Cscope introduction *cscope-intro*
29 The following text is taken from a version of the cscope man page:
33 Cscope is an interactive screen-oriented tool that helps you:
35 Learn how a C program works without endless flipping through a thick
38 Locate the section of code to change to fix a bug without having to
39 learn the entire program.
41 Examine the effect of a proposed change such as adding a value to an
44 Verify that a change has been made in all source files such as adding
45 an argument to an existing function.
47 Rename a global variable in all source files.
49 Change a constant to a preprocessor symbol in selected lines of files.
51 It is designed to answer questions like:
52 Where is this symbol used?
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?
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.
72 When cscope is normally invoked, you will get a full-screen selection
73 screen allowing you to make a query for one of the above questions.
74 However, once a match is found to your query and you have entered your
75 text editor to edit the source file containing match, you cannot simply
76 jump from tag to tag as you normally would with vi's Ctrl-] or :tag
79 Vim's cscope interface is done by invoking cscope with its line-oriented
80 interface, and then parsing the output returned from a query. The end
81 result is that cscope query results become just like regular tags, so
82 you can jump to them just like you do with normal tags (Ctrl-] or :tag)
83 and then go back by popping off the tagstack with Ctrl-T. (Please note
84 however, that you don't actually jump to a cscope tag simply by doing
85 Ctrl-] or :tag without remapping these commands or setting an option.
86 See the remaining sections on how the cscope interface works and for
90 ==============================================================================
91 2. Cscope related commands *cscope-commands*
93 *:cscope* *:cs* *:scs* *:scscope* *E259* *E262* *E561* *E560*
94 All cscope commands are accessed through suboptions to the main cscope
95 command ":cscope". The shortest abbreviation is ":cs". The ":scscope"
96 command does the same and also splits the window (short: "scs").
98 The available subcommands are:
100 *E563* *E564* *E566* *E568* *E569* *E622* *E623*
102 add : Add a new cscope database/connection.
104 USAGE :cs add {file|dir} [pre-path] [flags]
106 [pre-path] is the pathname used with the -P command to cscope.
108 [flags] are any additional flags you want to pass to cscope.
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
115 *cscope-find* *cs-find*
117 find : Query cscope. All cscope query options are available
118 except option #5 ("Change this grep pattern").
120 USAGE :cs find {querytype} {name}
122 {querytype} corresponds to the actual cscope line
123 interface numbers as well as default nvi commands:
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
135 :cscope find c vim_free
136 :cscope find 3 vim_free
138 These two examples perform the same query. >
140 :cscope find 0 DEFAULT_TERM
142 Executing this example on the source code for Vim 5.1 produces the
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>>
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>>
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>>
173 14 1833 vim-5.1-gtk/src/term.c <<termcapinit>>
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):
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.
186 help : Show a brief synopsis.
191 kill : Kill a cscope connection (or kill all cscope connections).
193 USAGE :cs kill {num|partial_name}
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!
200 If the specified connection number is -1, then _ALL_ cscope
201 connections will be killed.
203 reset : Reinit all cscope connections.
207 show : Show cscope connections.
212 This command is same as the ":cscope" command, except when the
213 'cscopequickfix' option is set, the location list for the current window is
214 used instead of the quickfix list to show the cscope results.
216 *:cstag* *E257* *E562*
217 If you use cscope as well as ctags, |:cstag| allows you to search one or
218 the other before making a jump. For example, you can choose to first
219 search your cscope database(s) for a match, and if one is not found, then
220 your tags file(s) will be searched. The order in which this happens
221 is determined by the value of |csto|. See |cscope-options| for more
224 |:cstag| performs the equivalent of ":cs find g" on the identifier when
225 searching through the cscope database(s).
227 |:cstag| performs the equivalent of |:tjump| on the identifier when searching
228 through your tags file(s).
231 ==============================================================================
232 3. Cscope options *cscope-options*
234 Use the |:set| command to set all cscope options. Ideally, you would do
235 this in one of your startup files (e.g., .vimrc). Some cscope related
236 variables are only valid within |.vimrc|. Setting them after vim has
237 started will have no effect!
240 'cscopeprg' specifies the command to execute cscope. The default is
241 "cscope". For example: >
242 :set csprg=/usr/local/bin/cscope
244 *cscopequickfix* *csqf* *E469*
245 {not available when compiled without the |+quickfix| feature}
246 'cscopequickfix' specifies whether to use quickfix window to show cscope
247 results. This is a list of comma-separated values. Each item consists of
248 |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
251 quickfix. Search is performed from start until first command occurrence.
252 The default value is "" (don't use quickfix anyway). The following value
253 seems to be useful: >
254 :set cscopequickfix=s-,c-,d-,i-,t-,e-
257 If 'cscopetag' set, the commands ":tag" and CTRL-] as well as "vim -t" will
258 always use |:cstag| instead of the default :tag behavior. Effectively, by
259 setting 'cst', you will always search your cscope databases as well as your
260 tag files. The default is off. Examples: >
264 *cscopetagorder* *csto*
265 The value of 'csto' determines the order in which |:cstag| performs a search.
266 If 'csto' is set to zero, cscope database(s) are searched first, followed
267 by tag file(s) if cscope did not return any matches. If 'csto' is set to
268 one, tag file(s) are searched before cscope database(s). The default is zero.
273 *cscopeverbose* *csverb*
274 If 'cscopeverbose' is not set (the default), messages will not be printed
275 indicating success or failure when adding a cscope database. Ideally, you
276 should reset this option in your |.vimrc| before adding any cscope databases,
277 and after adding them, set it. From then on, when you add more databases
278 within Vim, you will get a (hopefully) useful message should the database fail
279 to be added. Examples: >
283 *cscopepathcomp* *cspc*
284 The value of 'cspc' determines how many components of a file's path to
285 display. With the default value of zero the entire path will be displayed.
286 The value one will display only the filename with no path. Other values
287 display that many components. For example: >
289 will display the last 3 components of the file's path, including the file
292 ==============================================================================
293 4. How to use cscope in Vim *cscope-howtouse*
295 The first thing you need to do is to build a cscope database for your
296 source files. For the most basic case, simply do "cscope -b". Please
297 refer to the cscope man page for more details.
299 Assuming you have a cscope database, you need to "add" the database to Vim.
300 This establishes a cscope "connection" and makes it available for Vim to use.
301 You can do this in your .vimrc file, or you can do it manually after starting
302 vim. For example, to add the cscope database "cscope.out", you would do:
306 You can double-check the result of this by executing ":cs show". This will
307 produce output which looks like this:
309 # pid database name prepend path
310 0 28806 cscope.out <none>
313 Because of the Microsoft RTL limitations, Win32 version shows 0 instead
316 Once a cscope connection is established, you can make queries to cscope and
317 the results will be printed to you. Queries are made using the command
318 ":cs find". For example:
320 :cs find g ALIGN_SIZE
322 This can get a little cumbersome since one ends up doing a significant
323 amount of typing. Fortunately, there are ways around this by mapping
324 shortcut keys. See |cscope-suggestions| for suggested usage.
326 If the results return only one match, you will automatically be taken to it.
327 If there is more than one match, you will be given a selection screen to pick
328 the match you want to go to. After you have jumped to the new location,
329 simply hit Ctrl-T to get back to the previous one.
332 ==============================================================================
333 5. Limitations *cscope-limitations*
335 Cscope support for Vim is only available on systems that support these four
336 system calls: fork(), pipe(), execl(), waitpid(). This means it is mostly
337 limited to Unix systems.
339 Additionally Cscope support works for Win32. For more information and a
340 cscope version for Win32 see:
342 http://iamphet.nm.ru/cscope/index.html
344 The DJGPP-built version from http://cscope.sourceforge.net is known to not
347 There are a couple of hard-coded limitations:
349 1. The maximum number of cscope connections allowed is 8. Do you
352 2. Doing a |:tjump| when |:cstag| searches the tag files is not
353 configurable (e.g., you can't do a tselect instead).
355 ==============================================================================
356 6. Suggested usage *cscope-suggestions*
358 Put these entries in your .vimrc (adjust the pathname accordingly to your
362 set csprg=/usr/local/bin/cscope
366 " add any database in current directory
367 if filereadable("cscope.out")
369 " else add database pointed to by environment
370 elseif $CSCOPE_DB != ""
376 By setting 'cscopetag', we have effectively replaced all instances of the :tag
377 command with :cstag. This includes :tag, Ctrl-], and "vim -t". In doing
378 this, the regular tag command not only searches your ctags generated tag
379 files, but your cscope databases as well.
381 Some users may want to keep the regular tag behavior and have a different
382 shortcut to access :cstag. For example, one could map Ctrl-_ (underscore)
383 to :cstag with the following command: >
385 map <C-_> :cstag <C-R>=expand("<cword>")<CR><CR>
387 A couple of very commonly used cscope queries (using ":cs find") is to
388 find all functions calling a certain function and to find all occurrences
389 of a particular C symbol. To do this, you can use these mappings as an
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>
395 These mappings for Ctrl-] (right bracket) and Ctrl-\ (backslash) allow you to
396 place your cursor over the function name or C symbol and quickly query cscope
399 Or you may use the following scheme, inspired by Vim/Cscope tutorial from
400 Cscope Home Page (http://cscope.sourceforge.net/): >
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>
411 " Using 'CTRL-spacebar' then a search type makes the vim window
412 " split horizontally, with search result displayed in
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>
424 " Hitting CTRL-space *twice* before the search type does a vertical
425 " split instead of a horizontal one
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>
442 ==============================================================================
443 7. Cscope availability and information *cscope-info*
445 If you do not already have cscope (it did not come with your compiler
446 license or OS distribution), then you can download it for free from:
447 http://cscope.sourceforge.net/
448 This is released by SCO under the BSD license.
450 If you want a newer version of cscope, you will probably have to buy it.
451 According to the (old) nvi documentation:
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.
456 Also you can download cscope 13.x and mlcscope 14.x (multi-lingual cscope
457 which supports C, C++, Java, lex, yacc, breakpoint listing, Ingres, and SDL)
458 from World-Wide Exptools Open Source packages page:
459 http://www.bell-labs.com/project/wwexptools/packages.html
461 In Solaris 2.x, if you have the C compiler license, you will also have
462 cscope. Both are usually located under /opt/SUNWspro/bin
464 SGI 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/
467 The second one is for those who have a password for the SGI toolbox.
469 There is source to an older version of a cscope clone (called "cs") available
470 on the net. Due to various reasons, this is not supported with Vim.
472 The cscope interface/support for Vim was originally written by
473 Andy Kahn <ackahn@netapp.com>. The original structure (as well as a tiny
474 bit of code) was adapted from the cscope interface in nvi. Please report
475 any problems, suggestions, patches, et al., you have for the usage of
476 cscope within Vim to him.
478 For a cscope version for Win32 see: http://iamphet.nm.ru/cscope/index.html
480 Win32 support was added by Sergey Khorev <sergey.khorev@gmail.com>. Contact
481 him if you have Win32-specific issues.
483 vim:tw=78:ts=8:ft=help:norl: