1*if_cscop.txt* For Vim version 7.3. Last change: 2009 Mar 18 2 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 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 138 EXAMPLES > 139 :cscope find c vim_free 140 :cscope find 3 vim_free 141< 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". > 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 222 *:lcscope* *:lcs* 223This command is same as the ":cscope" command, except when the 224'cscopequickfix' option is set, the location list for the current window is 225used instead of the quickfix list to show the cscope results. 226 227 *:cstag* *E257* *E562* 228If you use cscope as well as ctags, |:cstag| allows you to search one or 229the other before making a jump. For example, you can choose to first 230search your cscope database(s) for a match, and if one is not found, then 231your tags file(s) will be searched. The order in which this happens 232is determined by the value of |csto|. See |cscope-options| for more 233details. 234 235|:cstag| performs the equivalent of ":cs find g" on the identifier when 236searching through the cscope database(s). 237 238|:cstag| performs the equivalent of |:tjump| on the identifier when searching 239through your tags file(s). 240 241 242============================================================================== 2433. Cscope options *cscope-options* 244 245Use the |:set| command to set all cscope options. Ideally, you would do 246this in one of your startup files (e.g., .vimrc). Some cscope related 247variables are only valid within |.vimrc|. Setting them after vim has 248started 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 258results. This is a list of comma-separated values. Each item consists of 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 262quickfix. Search is performed from start until first command occurrence. 263The default value is "" (don't use quickfix anyway). The following value 264seems to be useful: > 265 :set cscopequickfix=s-,c-,d-,i-,t-,e- 266< 267 *cscopetag* *cst* 268If 'cscopetag' set, the commands ":tag" and CTRL-] as well as "vim -t" will 269always use |:cstag| instead of the default :tag behavior. Effectively, by 270setting 'cst', you will always search your cscope databases as well as your 271tag files. The default is off. Examples: > 272 :set cst 273 :set nocst 274< 275 *cscopetagorder* *csto* 276The value of 'csto' determines the order in which |:cstag| performs a search. 277If 'csto' is set to zero, cscope database(s) are searched first, followed 278by tag file(s) if cscope did not return any matches. If 'csto' is set to 279one, tag file(s) are searched before cscope database(s). The default is zero. 280Examples: > 281 :set csto=0 282 :set csto=1 283< 284 *cscopeverbose* *csverb* 285If 'cscopeverbose' is not set (the default), messages will not be printed 286indicating success or failure when adding a cscope database. Ideally, you 287should reset this option in your |.vimrc| before adding any cscope databases, 288and after adding them, set it. From then on, when you add more databases 289within Vim, you will get a (hopefully) useful message should the database fail 290to be added. Examples: > 291 :set csverb 292 :set nocsverb 293< 294 *cscopepathcomp* *cspc* 295The value of 'cspc' determines how many components of a file's path to 296display. With the default value of zero the entire path will be displayed. 297The value one will display only the filename with no path. Other values 298display that many components. For example: > 299 :set cspc=3 300will display the last 3 components of the file's path, including the file 301name itself. 302 303============================================================================== 3044. How to use cscope in Vim *cscope-howtouse* 305 306The first thing you need to do is to build a cscope database for your 307source files. For the most basic case, simply do "cscope -b". Please 308refer to the cscope man page for more details. 309 310Assuming you have a cscope database, you need to "add" the database to Vim. 311This establishes a cscope "connection" and makes it available for Vim to use. 312You can do this in your .vimrc file, or you can do it manually after starting 313vim. For example, to add the cscope database "cscope.out", you would do: 314 315 :cs add cscope.out 316 317You can double-check the result of this by executing ":cs show". This will 318produce output which looks like this: 319 320 # pid database name prepend path 321 0 28806 cscope.out <none> 322 323Note: 324Because of the Microsoft RTL limitations, Win32 version shows 0 instead 325of the real pid. 326 327Once a cscope connection is established, you can make queries to cscope and 328the 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 333This can get a little cumbersome since one ends up doing a significant 334amount of typing. Fortunately, there are ways around this by mapping 335shortcut keys. See |cscope-suggestions| for suggested usage. 336 337If the results return only one match, you will automatically be taken to it. 338If there is more than one match, you will be given a selection screen to pick 339the match you want to go to. After you have jumped to the new location, 340simply hit Ctrl-T to get back to the previous one. 341 342 343============================================================================== 3445. Limitations *cscope-limitations* 345 346Cscope support for Vim is only available on systems that support these four 347system calls: fork(), pipe(), execl(), waitpid(). This means it is mostly 348limited to Unix systems. 349 350Additionally Cscope support works for Win32. For more information and a 351cscope version for Win32 see: 352 353 http://iamphet.nm.ru/cscope/index.html 354 355The DJGPP-built version from http://cscope.sourceforge.net is known to not 356work with Vim. 357 358Hard-coded limitation: doing a |:tjump| when |:cstag| searches the tag files 359is not configurable (e.g., you can't do a tselect instead). 360 361============================================================================== 3626. Suggested usage *cscope-suggestions* 363 364Put these entries in your .vimrc (adjust the pathname accordingly to your 365setup): > 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 382By setting 'cscopetag', we have effectively replaced all instances of the :tag 383command with :cstag. This includes :tag, Ctrl-], and "vim -t". In doing 384this, the regular tag command not only searches your ctags generated tag 385files, but your cscope databases as well. 386 387Some users may want to keep the regular tag behavior and have a different 388shortcut to access :cstag. For example, one could map Ctrl-_ (underscore) 389to :cstag with the following command: > 390 391 map <C-_> :cstag <C-R>=expand("<cword>")<CR><CR> 392 393A couple of very commonly used cscope queries (using ":cs find") is to 394find all functions calling a certain function and to find all occurrences 395of a particular C symbol. To do this, you can use these mappings as an 396example: > 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 401These mappings for Ctrl-] (right bracket) and Ctrl-\ (backslash) allow you to 402place your cursor over the function name or C symbol and quickly query cscope 403for any matches. 404 405Or you may use the following scheme, inspired by Vim/Cscope tutorial from 406Cscope 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============================================================================== 4497. Cscope availability and information *cscope-info* 450 451If you do not already have cscope (it did not come with your compiler 452license or OS distribution), then you can download it for free from: 453 http://cscope.sourceforge.net/ 454This is released by SCO under the BSD license. 455 456If you want a newer version of cscope, you will probably have to buy it. 457According 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 462Also you can download cscope 13.x and mlcscope 14.x (multi-lingual cscope 463which supports C, C++, Java, lex, yacc, breakpoint listing, Ingres, and SDL) 464from World-Wide Exptools Open Source packages page: 465 http://www.bell-labs.com/project/wwexptools/packages.html 466 467In Solaris 2.x, if you have the C compiler license, you will also have 468cscope. Both are usually located under /opt/SUNWspro/bin 469 470SGI 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/ 473The second one is for those who have a password for the SGI toolbox. 474 475There is source to an older version of a cscope clone (called "cs") available 476on the net. Due to various reasons, this is not supported with Vim. 477 478The cscope interface/support for Vim was originally written by 479Andy Kahn <ackahn@netapp.com>. The original structure (as well as a tiny 480bit of code) was adapted from the cscope interface in nvi. Please report 481any problems, suggestions, patches, et al., you have for the usage of 482cscope within Vim to him. 483 *cscope-win32* 484For a cscope version for Win32 see: 485 http://code.google.com/p/cscope-win32/ 486 487Win32 support was added by Sergey Khorev <sergey.khorev@gmail.com>. Contact 488him if you have Win32-specific issues. 489 490 vim:tw=78:ts=8:ft=help:norl: 491