vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

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: