summaryrefslogtreecommitdiffstats
path: root/runtime/doc/if_cscop.txt
blob: 3fa8f817f448a3860e0836025d68e46a01663c4c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
*if_cscop.txt*  For Vim version 9.1.  Last change: 2022 Jan 08


		  VIM REFERENCE MANUAL    by Andy Kahn

							*cscope* *Cscope*
This document explains how to use Vim's cscope interface.

Cscope is a tool like ctags, but think of it as ctags on steroids since it
does a lot more than what ctags provides.  In Vim, jumping to a result from
a cscope query is just like jumping to any tag; it is saved on the tag stack
so that with the right keyboard mappings, you can jump back and forth between
functions as you normally would with |tags|.

1. Cscope introduction		|cscope-intro|
2. Cscope related commands	|cscope-commands|
3. Cscope options		|cscope-options|
4. How to use cscope in Vim	|cscope-howtouse|
5. Limitations			|cscope-limitations|
6. Suggested usage		|cscope-suggestions|
7. Availability & Information	|cscope-info|

This is currently for Unix and Win32 only.

==============================================================================
1. Cscope introduction					*cscope-intro*

The following text is taken from a version of the cscope man page:

				    -----

  Cscope is an interactive screen-oriented tool that helps you:

       Learn how a C program works without endless flipping through a thick
       listing.

       Locate the section of code to change to fix a bug without having to
       learn the entire program.

       Examine the effect of a proposed change such as adding a value to an
       enum variable.

       Verify that a change has been made in all source files such as adding
       an argument to an existing function.

       Rename a global variable in all source files.

       Change a constant to a preprocessor symbol in selected lines of files.

  It is designed to answer questions like:
       Where is this symbol used?
       Where is it defined?
       Where did this variable get its value?
       What is this global symbol's definition?
       Where is this function in the source files?
       What functions call this function?
       What functions are called by this function?
       Where does the message "out of space" come from?
       Where is this source file in the directory structure?
       What files include this header file?

  Cscope answers these questions from a symbol database that it builds the
  first time it is used on the source files.  On a subsequent call, cscope
  rebuilds the database only if a source file has changed or the list of
  source files is different.  When the database is rebuilt the data for the
  unchanged files is copied from the old database, which makes rebuilding
  much faster than the initial build.

				    -----

When cscope is normally invoked, you will get a full-screen selection
screen allowing you to make a query for one of the above questions.
However, once a match is found to your query and you have entered your
text editor to edit the source file containing match, you cannot simply
jump from tag to tag as you normally would with vi's Ctrl-] or :tag
command.

Vim's cscope interface is done by invoking cscope with its line-oriented
interface, and then parsing the output returned from a query.  The end
result is that cscope query results become just like regular tags, so
you can jump to them just like you do with normal tags (Ctrl-] or :tag)
and then go back by popping off the tagstack with Ctrl-T.  (Please note
however, that you don't actually jump to a cscope tag simply by doing
Ctrl-] or :tag without remapping these commands or setting an option.
See the remaining sections on how the cscope interface works and for
suggested use.)


==============================================================================
2. Cscope related commands				*cscope-commands*

		*:cscope* *:cs* *:scs* *:scscope* *E259* *E262* *E560* *E561*
All cscope commands are accessed through suboptions to the cscope commands.
	`:cscope` or `:cs` is the main command
	`:scscope` or `:scs` does the same and splits the window
	`:lcscope` or `:lcs` uses the location list, see |:lcscope|

The available subcommands are:

			*E563* *E564* *E566* *E568* *E622* *E623* *E625*
			*E626* *E609*
    add   : Add a new cscope database/connection.

	USAGE	:cs add {file|dir} [pre-path] [flags]

	    [pre-path] is the pathname used with the -P command to cscope.

	    [flags] are any additional flags you want to pass to cscope.

	EXAMPLES >
	    :cscope add /usr/local/cdb/cscope.out
	    :cscope add /projects/vim/cscope.out /usr/local/vim
	    :cscope add cscope.out /usr/local/vim -C
<
				      *cscope-find* *cs-find* *E567*
    find  : Query cscope.  All cscope query options are available
	    except option #5 ("Change this grep pattern").

	USAGE	:cs find {querytype} {name}

	    {querytype} corresponds to the actual cscope line
	    interface numbers as well as default nvi commands:

		0 or s: Find this C symbol
		1 or g: Find this definition
		2 or d: Find functions called by this function
		3 or c: Find functions calling this function
		4 or t: Find this text string
		6 or e: Find this egrep pattern
		7 or f: Find this file
		8 or i: Find files #including this file
		9 or a: Find places where this symbol is assigned a value

	For all types, except 4 and 6, leading white space for {name} is
	removed.  For 4 and 6 there is exactly one space between {querytype}
	and {name}.  Further white space is included in {name}.

	EXAMPLES >
	    :cscope find c vim_free
	    :cscope find 3  vim_free
<
	    These two examples perform the same query: functions calling
	    "vim_free". >

	    :cscope find t initOnce
	    :cscope find t  initOnce
<
	    The first one searches for the text "initOnce", the second one for
	    " initOnce". >

	    :cscope find 0 DEFAULT_TERM
<
	    Executing this example on the source code for Vim 5.1 produces the
	    following output:

	    Cscope tag: DEFAULT_TERM
	       #   line  filename / context / line
	       1   1009  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"amiga"
	       2   1013  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"win32"
	       3   1017  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"pcterm"
	       4   1021  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"ansi"
	       5   1025  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"vt52"
	       6   1029  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"os2ansi"
	       7   1033  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"ansi"
	       8   1037  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 # undef DEFAULT_TERM
	       9   1038  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"beos-ansi"
	      10   1042  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"mac-ansi"
	      11   1335  vim-5.1-gtk/src/term.c <<set_termname>>
			 term = DEFAULT_TERM;
	      12   1459  vim-5.1-gtk/src/term.c <<set_termname>>
			 if (STRCMP(term, DEFAULT_TERM))
	      13   1826  vim-5.1-gtk/src/term.c <<termcapinit>>
			 term = DEFAULT_TERM;
	      14   1833  vim-5.1-gtk/src/term.c <<termcapinit>>
			 term = DEFAULT_TERM;
	      15   3635  vim-5.1-gtk/src/term.c <<update_tcap>>
			 p = find_builtin_term(DEFAULT_TERM);
	    Enter nr of choice (<CR> to abort):

	    The output shows several pieces of information:
	    1. The tag number (there are 15 in this example).
	    2. The line number where the tag occurs.
	    3. The filename where the tag occurs.
	    4. The context of the tag (e.g., global, or the function name).
	    5. The line from the file itself.

    help  : Show a brief synopsis.

	    USAGE   :cs help

							*E261*
    kill  : Kill a cscope connection (or kill all cscope connections).

	    USAGE   :cs kill {num|partial_name}

	    To kill a cscope connection, the connection number or a partial
	    name must be specified.  The partial name is simply any part of
	    the pathname of the cscope database.  Kill a cscope connection
	    using the partial name with caution!

	    If the specified connection number is -1, then _ALL_ cscope
	    connections will be killed.

    reset : Reinit all cscope connections.

	    USAGE   :cs reset

    show  : Show cscope connections.

	    USAGE   :cs show

							*:lcscope* *:lcs*
This command is same as the ":cscope" command, except when the
'cscopequickfix' option is set, the location list for the current window is
used instead of the quickfix list to show the cscope results.

							*:cstag* *E257* *E562*
If you use cscope as well as ctags, |:cstag| allows you to search one or
the other before making a jump.  For example, you can choose to first
search your cscope database(s) for a match, and if one is not found, then
your tags file(s) will be searched.  The order in which this happens
is determined by the value of |csto|.  See |cscope-options| for more
details.

|:cstag| performs the equivalent of ":cs find g" on the identifier when
searching through the cscope database(s).

|:cstag| performs the equivalent of |:tjump| on the identifier when searching
through your tags file(s).


==============================================================================
3. Cscope options					*cscope-options*

Use the |:set| command to set all cscope options.  Ideally, you would do
this in one of your startup files (e.g., .vimrc).  Some cscope related
variables are only valid within |.vimrc|.  Setting them after vim has
started will have no effect!

							*cscopeprg* *csprg*
'cscopeprg' specifies the command to execute cscope.  The default is
"cscope".  For example: >
	:set csprg=/usr/local/bin/cscope
<
					    *cscopequickfix* *csqf* *E469*
{not available when compiled without the |+quickfix| feature}
'cscopequickfix' specifies whether to use quickfix window to show cscope
results.  This is a list of comma-separated values. Each item consists of
|cscope-find| command (s, g, d, c, t, e, f, i or a) and flag (+, - or 0).
'+' indicates that results must be appended to quickfix window,
'-' implies previous results clearance, '0' or command absence - don't use
quickfix.  Search is performed from start until first command occurrence.
The default value is "" (don't use quickfix anyway).  The following value
seems to be useful: >
	:set cscopequickfix=s-,c-,d-,i-,t-,e-,a-
<
							*cscopetag* *cst*
If 'cscopetag' is set, the commands ":tag" and CTRL-] as well as "vim -t"
will always use |:cstag| instead of the default :tag behavior.  Effectively,
by setting 'cst', you will always search your cscope databases as well as
your tag files.  The default is off.  Examples: >
	:set cst
	:set nocst
<
							*cscoperelative* *csre*
If 'cscoperelative' is set, then in absence of a prefix given to cscope
(prefix is the argument of -P option of cscope), basename of cscope.out
location (usually the project root directory) will be used as the prefix
to construct an absolute path.  The default is off.  Note: This option is
only effective when cscope (cscopeprg) is initialized without a prefix
path (-P).  Examples: >
	:set csre
	:set nocsre
<
							*cscopetagorder* *csto*
The value of 'csto' determines the order in which |:cstag| performs a search.
If 'csto' is set to zero, cscope database(s) are searched first, followed
by tag file(s) if cscope did not return any matches.  If 'csto' is set to
one, tag file(s) are searched before cscope database(s).  The default is zero.
Examples: >
	:set csto=0
	:set csto=1
<
						*cscopeverbose* *csverb*
If 'cscopeverbose' is not set (the default), messages will not be printed
indicating success or failure when adding a cscope database.  Ideally, you
should reset this option in your |.vimrc| before adding any cscope databases,
and after adding them, set it.  From then on, when you add more databases
within Vim, you will get a (hopefully) useful message should the database fail
to be added.  Examples: >
	:set csverb
	:set nocsverb
<
						      *cscopepathcomp* *cspc*
The value of 'cspc' determines how many components of a file's path to
display.  With the default value of zero the entire path will be displayed.
The value one will display only the filename with no path.  Other values
display that many components.  For example: >
	:set cspc=3
will display the last 3 components of the file's path, including the file
name itself.

==============================================================================
4. How to use cscope in Vim				*cscope-howtouse*

The first thing you need to do is to build a cscope database for your
source files.  For the most basic case, simply do "cscope -b".  Please
refer to the cscope man page for more details.

Assuming you have a cscope database, you need to "add" the database to Vim.
This establishes a cscope "connection" and makes it available for Vim to use.
You can do this in your .vimrc file, or you can do it manually after starting
vim.  For example, to add the cscope database "cscope.out", you would do:

	:cs add cscope.out

You can double-check the result of this by executing ":cs show".  This will
produce output which looks like this:

 # pid	  database name			      prepend path
 0 28806  cscope.out			      <none>

Note:
Because of the Microsoft RTL limitations, Win32 version shows 0 instead
of the real pid.

Once a cscope connection is established, you can make queries to cscope and
the results will be printed to you.  Queries are made using the command
":cs find".  For example:

	:cs find g ALIGN_SIZE

This can get a little cumbersome since one ends up doing a significant
amount of typing.  Fortunately, there are ways around this by mapping
shortcut keys.  See |cscope-suggestions| for suggested usage.

If the results return only one match, you will automatically be taken to it.
If there is more than one match, you will be given a selection screen to pick
the match you want to go to.  After you have jumped to the new location,
simply hit Ctrl-T to get back to the previous one.


==============================================================================
5. Limitations						*cscope-limitations*

Cscope support for Vim is only available on systems that support these four
system calls: fork(), pipe(), execl(), waitpid().  This means it is mostly
limited to Unix systems.

Additionally Cscope support works for Win32.  For more information and a
cscope version for Win32 see:

	http://iamphet.nm.ru/cscope/index.html

The DJGPP-built version from http://cscope.sourceforge.net is known to not
work with Vim.

Hard-coded limitation: doing a |:tjump| when |:cstag| searches the tag files
is not configurable (e.g., you can't do a tselect instead).

==============================================================================
6. Suggested usage					*cscope-suggestions*

Put these entries in your .vimrc (adjust the pathname accordingly to your
setup): >

	if has("cscope")
		set csprg=/usr/local/bin/cscope
		set csto=0
		set cst
		set nocsverb
		" add any database in current directory
		if filereadable("cscope.out")
		    cs add cscope.out
		" else add database pointed to by environment
		elseif $CSCOPE_DB != ""
		    cs add $CSCOPE_DB
		endif
		set csverb
	endif

By setting 'cscopetag', we have effectively replaced all instances of the :tag
command with :cstag.  This includes :tag, Ctrl-], and "vim -t".  In doing
this, the regular tag command not only searches your ctags generated tag
files, but your cscope databases as well.

Some users may want to keep the regular tag behavior and have a different
shortcut to access :cstag.  For example, one could map Ctrl-_  (underscore)
to :cstag with the following command: >

	map <C-_> :cstag <C-R>=expand("<cword>")<CR><CR>

A couple of very commonly used cscope queries (using ":cs find") is to
find all functions calling a certain function and to find all occurrences
of a particular C symbol.  To do this, you can use these mappings as an
example: >

	map g<C-]> :cs find 3 <C-R>=expand("<cword>")<CR><CR>
	map g<C-\> :cs find 0 <C-R>=expand("<cword>")<CR><CR>

These mappings for Ctrl-] (right bracket) and Ctrl-\ (backslash) allow you to
place your cursor over the function name or C symbol and quickly query cscope
for any matches.

Or you may use the following scheme, inspired by Vim/Cscope tutorial from
Cscope Home Page (http://cscope.sourceforge.net/): >

	nmap <C-_>s :cs find s <C-R>=expand("<cword>")<CR><CR>
	nmap <C-_>g :cs find g <C-R>=expand("<cword>")<CR><CR>
	nmap <C-_>c :cs find c <C-R>=expand("<cword>")<CR><CR>
	nmap <C-_>t :cs find t <C-R>=expand("<cword>")<CR><CR>
	nmap <C-_>e :cs find e <C-R>=expand("<cword>")<CR><CR>
	nmap <C-_>f :cs find f <C-R>=expand("<cfile>")<CR><CR>
	nmap <C-_>i :cs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
	nmap <C-_>d :cs find d <C-R>=expand("<cword>")<CR><CR>
	nmap <C-_>a :cs find a <C-R>=expand("<cword>")<CR><CR>

	" Using 'CTRL-spacebar' then a search type makes the vim window
	" split horizontally, with search result displayed in
	" the new window.

	nmap <C-Space>s :scs find s <C-R>=expand("<cword>")<CR><CR>
	nmap <C-Space>g :scs find g <C-R>=expand("<cword>")<CR><CR>
	nmap <C-Space>c :scs find c <C-R>=expand("<cword>")<CR><CR>
	nmap <C-Space>t :scs find t <C-R>=expand("<cword>")<CR><CR>
	nmap <C-Space>e :scs find e <C-R>=expand("<cword>")<CR><CR>
	nmap <C-Space>f :scs find f <C-R>=expand("<cfile>")<CR><CR>
	nmap <C-Space>i :scs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
	nmap <C-Space>d :scs find d <C-R>=expand("<cword>")<CR><CR>
	nmap <C-Space>a :scs find a <C-R>=expand("<cword>")<CR><CR>

	" Hitting CTRL-space *twice* before the search type does a vertical
	" split instead of a horizontal one

	nmap <C-Space><C-Space>s
		\:vert scs find s <C-R>=expand("<cword>")<CR><CR>
	nmap <C-Space><C-Space>g
		\:vert scs find g <C-R>=expand("<cword>")<CR><CR>
	nmap <C-Space><C-Space>c
		\:vert scs find c <C-R>=expand("<cword>")<CR><CR>
	nmap <C-Space><C-Space>t
		\:vert scs find t <C-R>=expand("<cword>")<CR><CR>
	nmap <C-Space><C-Space>e
		\:vert scs find e <C-R>=expand("<cword>")<CR><CR>
	nmap <C-Space><C-Space>i
		\:vert scs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
	nmap <C-Space><C-Space>d
		\:vert scs find d <C-R>=expand("<cword>")<CR><CR>
	nmap <C-Space><C-Space>a
		\:vert scs find a <C-R>=expand("<cword>")<CR><CR>

==============================================================================
7. Cscope availability and information			*cscope-info*

If you do not already have cscope (it did not come with your compiler
license or OS distribution), then you can download it for free from:
	http://cscope.sourceforge.net/
This is released by SCO under the BSD license.

In Solaris 2.x, if you have the C compiler license, you will also have
cscope.  Both are usually located under /opt/SUNWspro/bin

There is source to an older version of a cscope clone (called "cs") available
on the net.  Due to various reasons, this is not supported with Vim.

The cscope interface/support for Vim was originally written by
Andy Kahn <ackahn@netapp.com>.  The original structure (as well as a tiny
bit of code) was adapted from the cscope interface in nvi.
							*cscope-win32*
For a cscope version for Win32 see (seems abandoned):
	https://code.google.com/archive/p/cscope-win32/

Win32 support was added by Sergey Khorev <sergey.khorev@gmail.com>.  Contact
him if you have Win32-specific issues.

 vim:tw=78:ts=8:noet:ft=help:norl: