Mercurial > vim
annotate runtime/doc/if_cscop.txt @ 2154:7c8c7c95a865 vim73
First step in the Vim 7.3 branch. Changed version numbers.
author | Bram Moolenaar <bram@zimbu.org> |
---|---|
date | Sat, 15 May 2010 13:56:02 +0200 |
parents | 1ee00a062acb |
children | 733f0dc510c3 12b829477c60 |
rev | line source |
---|---|
2154
7c8c7c95a865
First step in the Vim 7.3 branch. Changed version numbers.
Bram Moolenaar <bram@zimbu.org>
parents:
1949
diff
changeset
|
1 *if_cscop.txt* For Vim version 7.3a. Last change: 2009 Mar 18 |
7 | 2 |
3 | |
4 VIM REFERENCE MANUAL by Andy Kahn | |
5 | |
6 *cscope* *Cscope* | |
7 This document explains how to use Vim's cscope interface. | |
8 | |
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|. | |
14 | |
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| | |
22 | |
23 This is currently for Unix and Win32 only. | |
24 {Vi does not have any of these commands} | |
25 | |
26 ============================================================================== | |
27 1. Cscope introduction *cscope-intro* | |
28 | |
29 The 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 | |
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 | |
77 command. | |
78 | |
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 | |
87 suggested use.) | |
88 | |
89 | |
90 ============================================================================== | |
91 2. Cscope related commands *cscope-commands* | |
92 | |
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"). | |
97 | |
98 The 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 | |
1847 | 134 For all types, except 4 and 6, leading white space for {name} is |
135 removed. For 4 and 6 there is exactly one space between {querytype} | |
136 and {name}. Further white space is included in {name}. | |
137 | |
7 | 138 EXAMPLES > |
139 :cscope find c vim_free | |
1847 | 140 :cscope find 3 vim_free |
7 | 141 < |
1847 | 142 These two examples perform the same query: functions calling |
143 "vim_free". > | |
144 | |
145 :cscope find t initOnce | |
146 :cscope find t initOnce | |
147 < | |
148 The first one searches for the text "initOnce", the second one for | |
149 " initOnce". > | |
7 | 150 |
151 :cscope find 0 DEFAULT_TERM | |
152 < | |
153 Executing this example on the source code for Vim 5.1 produces the | |
154 following output: | |
155 | |
156 Cscope tag: DEFAULT_TERM | |
157 # line filename / context / line | |
158 1 1009 vim-5.1-gtk/src/term.c <<GLOBAL>> | |
159 #define DEFAULT_TERM (char_u *)"amiga" | |
160 2 1013 vim-5.1-gtk/src/term.c <<GLOBAL>> | |
161 #define DEFAULT_TERM (char_u *)"win32" | |
162 3 1017 vim-5.1-gtk/src/term.c <<GLOBAL>> | |
163 #define DEFAULT_TERM (char_u *)"pcterm" | |
164 4 1021 vim-5.1-gtk/src/term.c <<GLOBAL>> | |
165 #define DEFAULT_TERM (char_u *)"ansi" | |
166 5 1025 vim-5.1-gtk/src/term.c <<GLOBAL>> | |
167 #define DEFAULT_TERM (char_u *)"vt52" | |
168 6 1029 vim-5.1-gtk/src/term.c <<GLOBAL>> | |
169 #define DEFAULT_TERM (char_u *)"os2ansi" | |
170 7 1033 vim-5.1-gtk/src/term.c <<GLOBAL>> | |
171 #define DEFAULT_TERM (char_u *)"ansi" | |
172 8 1037 vim-5.1-gtk/src/term.c <<GLOBAL>> | |
173 # undef DEFAULT_TERM | |
174 9 1038 vim-5.1-gtk/src/term.c <<GLOBAL>> | |
175 #define DEFAULT_TERM (char_u *)"beos-ansi" | |
176 10 1042 vim-5.1-gtk/src/term.c <<GLOBAL>> | |
177 #define DEFAULT_TERM (char_u *)"mac-ansi" | |
178 11 1335 vim-5.1-gtk/src/term.c <<set_termname>> | |
179 term = DEFAULT_TERM; | |
180 12 1459 vim-5.1-gtk/src/term.c <<set_termname>> | |
181 if (STRCMP(term, DEFAULT_TERM)) | |
182 13 1826 vim-5.1-gtk/src/term.c <<termcapinit>> | |
183 term = DEFAULT_TERM; | |
184 14 1833 vim-5.1-gtk/src/term.c <<termcapinit>> | |
185 term = DEFAULT_TERM; | |
186 15 3635 vim-5.1-gtk/src/term.c <<update_tcap>> | |
187 p = find_builtin_term(DEFAULT_TERM); | |
188 Enter nr of choice (<CR> to abort): | |
189 | |
190 The output shows several pieces of information: | |
191 1. The tag number (there are 15 in this example). | |
192 2. The line number where the tag occurs. | |
193 3. The filename where the tag occurs. | |
194 4. The context of the tag (e.g., global, or the function name). | |
195 5. The line from the file itself. | |
196 | |
197 help : Show a brief synopsis. | |
198 | |
199 USAGE :cs help | |
200 | |
201 *E260* *E261* | |
202 kill : Kill a cscope connection (or kill all cscope connections). | |
203 | |
204 USAGE :cs kill {num|partial_name} | |
205 | |
206 To kill a cscope connection, the connection number or a partial | |
207 name must be specified. The partial name is simply any part of | |
208 the pathname of the cscope database. Kill a cscope connection | |
209 using the partial name with caution! | |
210 | |
211 If the specified connection number is -1, then _ALL_ cscope | |
212 connections will be killed. | |
213 | |
214 reset : Reinit all cscope connections. | |
215 | |
216 USAGE :cs reset | |
217 | |
218 show : Show cscope connections. | |
219 | |
220 USAGE :cs show | |
221 | |
665 | 222 *:lcscope* *:lcs* |
223 This command is same as the ":cscope" command, except when the | |
224 'cscopequickfix' option is set, the location list for the current window is | |
225 used instead of the quickfix list to show the cscope results. | |
226 | |
7 | 227 *:cstag* *E257* *E562* |
228 If you use cscope as well as ctags, |:cstag| allows you to search one or | |
229 the other before making a jump. For example, you can choose to first | |
230 search your cscope database(s) for a match, and if one is not found, then | |
231 your tags file(s) will be searched. The order in which this happens | |
232 is determined by the value of |csto|. See |cscope-options| for more | |
233 details. | |
234 | |
235 |:cstag| performs the equivalent of ":cs find g" on the identifier when | |
236 searching through the cscope database(s). | |
237 | |
238 |:cstag| performs the equivalent of |:tjump| on the identifier when searching | |
239 through your tags file(s). | |
240 | |
241 | |
242 ============================================================================== | |
243 3. Cscope options *cscope-options* | |
244 | |
245 Use the |:set| command to set all cscope options. Ideally, you would do | |
246 this in one of your startup files (e.g., .vimrc). Some cscope related | |
247 variables are only valid within |.vimrc|. Setting them after vim has | |
248 started will have no effect! | |
249 | |
250 *cscopeprg* *csprg* | |
251 'cscopeprg' specifies the command to execute cscope. The default is | |
252 "cscope". For example: > | |
253 :set csprg=/usr/local/bin/cscope | |
254 < | |
255 *cscopequickfix* *csqf* *E469* | |
256 {not available when compiled without the |+quickfix| feature} | |
257 'cscopequickfix' specifies whether to use quickfix window to show cscope | |
236 | 258 results. This is a list of comma-separated values. Each item consists of |
7 | 259 |cscope-find| command (s, g, d, c, t, e, f or i) and flag (+, - or 0). |
260 '+' indicates that results must be appended to quickfix window, | |
261 '-' implies previous results clearance, '0' or command absence - don't use | |
236 | 262 quickfix. Search is performed from start until first command occurrence. |
263 The default value is "" (don't use quickfix anyway). The following value | |
33 | 264 seems to be useful: > |
265 :set cscopequickfix=s-,c-,d-,i-,t-,e- | |
266 < | |
7 | 267 *cscopetag* *cst* |
268 If 'cscopetag' set, the commands ":tag" and CTRL-] as well as "vim -t" will | |
269 always use |:cstag| instead of the default :tag behavior. Effectively, by | |
270 setting 'cst', you will always search your cscope databases as well as your | |
271 tag files. The default is off. Examples: > | |
272 :set cst | |
273 :set nocst | |
274 < | |
275 *cscopetagorder* *csto* | |
276 The value of 'csto' determines the order in which |:cstag| performs a search. | |
277 If 'csto' is set to zero, cscope database(s) are searched first, followed | |
278 by tag file(s) if cscope did not return any matches. If 'csto' is set to | |
279 one, tag file(s) are searched before cscope database(s). The default is zero. | |
280 Examples: > | |
281 :set csto=0 | |
282 :set csto=1 | |
283 < | |
284 *cscopeverbose* *csverb* | |
285 If 'cscopeverbose' is not set (the default), messages will not be printed | |
286 indicating success or failure when adding a cscope database. Ideally, you | |
287 should reset this option in your |.vimrc| before adding any cscope databases, | |
288 and after adding them, set it. From then on, when you add more databases | |
289 within Vim, you will get a (hopefully) useful message should the database fail | |
290 to be added. Examples: > | |
291 :set csverb | |
292 :set nocsverb | |
293 < | |
294 *cscopepathcomp* *cspc* | |
295 The value of 'cspc' determines how many components of a file's path to | |
296 display. With the default value of zero the entire path will be displayed. | |
297 The value one will display only the filename with no path. Other values | |
298 display that many components. For example: > | |
299 :set cspc=3 | |
300 will display the last 3 components of the file's path, including the file | |
301 name itself. | |
302 | |
303 ============================================================================== | |
304 4. How to use cscope in Vim *cscope-howtouse* | |
305 | |
306 The first thing you need to do is to build a cscope database for your | |
307 source files. For the most basic case, simply do "cscope -b". Please | |
308 refer to the cscope man page for more details. | |
309 | |
310 Assuming you have a cscope database, you need to "add" the database to Vim. | |
311 This establishes a cscope "connection" and makes it available for Vim to use. | |
312 You can do this in your .vimrc file, or you can do it manually after starting | |
313 vim. For example, to add the cscope database "cscope.out", you would do: | |
314 | |
315 :cs add cscope.out | |
316 | |
317 You can double-check the result of this by executing ":cs show". This will | |
318 produce output which looks like this: | |
319 | |
320 # pid database name prepend path | |
321 0 28806 cscope.out <none> | |
322 | |
323 Note: | |
324 Because of the Microsoft RTL limitations, Win32 version shows 0 instead | |
325 of the real pid. | |
326 | |
327 Once a cscope connection is established, you can make queries to cscope and | |
328 the results will be printed to you. Queries are made using the command | |
329 ":cs find". For example: | |
330 | |
331 :cs find g ALIGN_SIZE | |
332 | |
333 This can get a little cumbersome since one ends up doing a significant | |
334 amount of typing. Fortunately, there are ways around this by mapping | |
335 shortcut keys. See |cscope-suggestions| for suggested usage. | |
336 | |
337 If the results return only one match, you will automatically be taken to it. | |
338 If there is more than one match, you will be given a selection screen to pick | |
339 the match you want to go to. After you have jumped to the new location, | |
340 simply hit Ctrl-T to get back to the previous one. | |
341 | |
342 | |
343 ============================================================================== | |
344 5. Limitations *cscope-limitations* | |
345 | |
346 Cscope support for Vim is only available on systems that support these four | |
347 system calls: fork(), pipe(), execl(), waitpid(). This means it is mostly | |
348 limited to Unix systems. | |
349 | |
350 Additionally Cscope support works for Win32. For more information and a | |
351 cscope version for Win32 see: | |
352 | |
353 http://iamphet.nm.ru/cscope/index.html | |
354 | |
20 | 355 The DJGPP-built version from http://cscope.sourceforge.net is known to not |
356 work with Vim. | |
357 | |
1931 | 358 Hard-coded limitation: doing a |:tjump| when |:cstag| searches the tag files |
359 is not configurable (e.g., you can't do a tselect instead). | |
7 | 360 |
361 ============================================================================== | |
362 6. Suggested usage *cscope-suggestions* | |
363 | |
364 Put these entries in your .vimrc (adjust the pathname accordingly to your | |
365 setup): > | |
366 | |
367 if has("cscope") | |
368 set csprg=/usr/local/bin/cscope | |
369 set csto=0 | |
370 set cst | |
371 set nocsverb | |
372 " add any database in current directory | |
373 if filereadable("cscope.out") | |
374 cs add cscope.out | |
375 " else add database pointed to by environment | |
376 elseif $CSCOPE_DB != "" | |
377 cs add $CSCOPE_DB | |
378 endif | |
379 set csverb | |
380 endif | |
381 | |
382 By setting 'cscopetag', we have effectively replaced all instances of the :tag | |
383 command with :cstag. This includes :tag, Ctrl-], and "vim -t". In doing | |
384 this, the regular tag command not only searches your ctags generated tag | |
385 files, but your cscope databases as well. | |
386 | |
387 Some users may want to keep the regular tag behavior and have a different | |
388 shortcut to access :cstag. For example, one could map Ctrl-_ (underscore) | |
389 to :cstag with the following command: > | |
390 | |
391 map <C-_> :cstag <C-R>=expand("<cword>")<CR><CR> | |
392 | |
393 A couple of very commonly used cscope queries (using ":cs find") is to | |
394 find all functions calling a certain function and to find all occurrences | |
395 of a particular C symbol. To do this, you can use these mappings as an | |
396 example: > | |
397 | |
398 map g<C-]> :cs find 3 <C-R>=expand("<cword>")<CR><CR> | |
399 map g<C-\> :cs find 0 <C-R>=expand("<cword>")<CR><CR> | |
400 | |
401 These mappings for Ctrl-] (right bracket) and Ctrl-\ (backslash) allow you to | |
402 place your cursor over the function name or C symbol and quickly query cscope | |
403 for any matches. | |
404 | |
405 Or you may use the following scheme, inspired by Vim/Cscope tutorial from | |
406 Cscope Home Page (http://cscope.sourceforge.net/): > | |
407 | |
408 nmap <C-_>s :cs find s <C-R>=expand("<cword>")<CR><CR> | |
409 nmap <C-_>g :cs find g <C-R>=expand("<cword>")<CR><CR> | |
410 nmap <C-_>c :cs find c <C-R>=expand("<cword>")<CR><CR> | |
411 nmap <C-_>t :cs find t <C-R>=expand("<cword>")<CR><CR> | |
412 nmap <C-_>e :cs find e <C-R>=expand("<cword>")<CR><CR> | |
413 nmap <C-_>f :cs find f <C-R>=expand("<cfile>")<CR><CR> | |
414 nmap <C-_>i :cs find i ^<C-R>=expand("<cfile>")<CR>$<CR> | |
415 nmap <C-_>d :cs find d <C-R>=expand("<cword>")<CR><CR> | |
416 | |
417 " Using 'CTRL-spacebar' then a search type makes the vim window | |
418 " split horizontally, with search result displayed in | |
419 " the new window. | |
420 | |
421 nmap <C-Space>s :scs find s <C-R>=expand("<cword>")<CR><CR> | |
422 nmap <C-Space>g :scs find g <C-R>=expand("<cword>")<CR><CR> | |
423 nmap <C-Space>c :scs find c <C-R>=expand("<cword>")<CR><CR> | |
424 nmap <C-Space>t :scs find t <C-R>=expand("<cword>")<CR><CR> | |
425 nmap <C-Space>e :scs find e <C-R>=expand("<cword>")<CR><CR> | |
426 nmap <C-Space>f :scs find f <C-R>=expand("<cfile>")<CR><CR> | |
427 nmap <C-Space>i :scs find i ^<C-R>=expand("<cfile>")<CR>$<CR> | |
428 nmap <C-Space>d :scs find d <C-R>=expand("<cword>")<CR><CR> | |
429 | |
430 " Hitting CTRL-space *twice* before the search type does a vertical | |
431 " split instead of a horizontal one | |
432 | |
433 nmap <C-Space><C-Space>s | |
434 \:vert scs find s <C-R>=expand("<cword>")<CR><CR> | |
435 nmap <C-Space><C-Space>g | |
436 \:vert scs find g <C-R>=expand("<cword>")<CR><CR> | |
437 nmap <C-Space><C-Space>c | |
438 \:vert scs find c <C-R>=expand("<cword>")<CR><CR> | |
439 nmap <C-Space><C-Space>t | |
440 \:vert scs find t <C-R>=expand("<cword>")<CR><CR> | |
441 nmap <C-Space><C-Space>e | |
442 \:vert scs find e <C-R>=expand("<cword>")<CR><CR> | |
443 nmap <C-Space><C-Space>i | |
444 \:vert scs find i ^<C-R>=expand("<cfile>")<CR>$<CR> | |
445 nmap <C-Space><C-Space>d | |
446 \:vert scs find d <C-R>=expand("<cword>")<CR><CR> | |
447 | |
448 ============================================================================== | |
449 7. Cscope availability and information *cscope-info* | |
450 | |
451 If you do not already have cscope (it did not come with your compiler | |
452 license or OS distribution), then you can download it for free from: | |
453 http://cscope.sourceforge.net/ | |
454 This is released by SCO under the BSD license. | |
455 | |
456 If you want a newer version of cscope, you will probably have to buy it. | |
457 According to the (old) nvi documentation: | |
458 | |
459 You can buy version 13.3 source with an unrestricted license | |
460 for $400 from AT&T Software Solutions by calling +1-800-462-8146. | |
461 | |
462 Also you can download cscope 13.x and mlcscope 14.x (multi-lingual cscope | |
463 which supports C, C++, Java, lex, yacc, breakpoint listing, Ingres, and SDL) | |
464 from World-Wide Exptools Open Source packages page: | |
465 http://www.bell-labs.com/project/wwexptools/packages.html | |
466 | |
467 In Solaris 2.x, if you have the C compiler license, you will also have | |
468 cscope. Both are usually located under /opt/SUNWspro/bin | |
469 | |
470 SGI developers can also get it. Search for Cscope on this page: | |
471 http://freeware.sgi.com/index-by-alpha.html | |
472 https://toolbox.sgi.com/toolbox/utilities/cscope/ | |
473 The second one is for those who have a password for the SGI toolbox. | |
474 | |
475 There is source to an older version of a cscope clone (called "cs") available | |
476 on the net. Due to various reasons, this is not supported with Vim. | |
477 | |
478 The cscope interface/support for Vim was originally written by | |
479 Andy Kahn <ackahn@netapp.com>. The original structure (as well as a tiny | |
480 bit of code) was adapted from the cscope interface in nvi. Please report | |
481 any problems, suggestions, patches, et al., you have for the usage of | |
482 cscope within Vim to him. | |
483 *cscope-win32* | |
1949 | 484 For a cscope version for Win32 see: |
485 http://code.google.com/p/cscope-win32/ | |
7 | 486 |
236 | 487 Win32 support was added by Sergey Khorev <sergey.khorev@gmail.com>. Contact |
147 | 488 him if you have Win32-specific issues. |
7 | 489 |
490 vim:tw=78:ts=8:ft=help:norl: |