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