mirror of
https://github.com/neovim/neovim.git
synced 2024-12-26 14:11:15 -07:00
375 lines
14 KiB
Plaintext
375 lines
14 KiB
Plaintext
*if_cscop.txt* Nvim
|
|
|
|
|
|
VIM REFERENCE MANUAL by Andy Kahn
|
|
|
|
*cscope* *Cscope*
|
|
Cscope is a "code intelligence" tool that helps you navigate C programs. It
|
|
can also perform some refactoring tasks, such as renaming a global variable in
|
|
all source files. Think of it as "ctags on steroids".
|
|
|
|
See |cscope-usage| for a quickstart.
|
|
|
|
Type |gO| to see the table of contents.
|
|
|
|
==============================================================================
|
|
Cscope introduction *cscope-intro*
|
|
|
|
|
|
Cscope 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.
|
|
|
|
See |cscope-usage| to get started.
|
|
|
|
==============================================================================
|
|
Cscope commands *cscope-commands*
|
|
|
|
*:cscope* *:cs* *:scs* *:scscope* *E259* *E262* *E561* *E560*
|
|
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).
|
|
|
|
|
|
==============================================================================
|
|
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 |init.vim|. 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*
|
|
'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.
|
|
|
|
*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).
|
|
|
|
*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.
|
|
|
|
*cscopepathcomp* *cspc*
|
|
'cscopepathcomp' 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 cscopepathcomp=3
|
|
will display the last 3 components of the file's path, including the file
|
|
name itself.
|
|
|
|
==============================================================================
|
|
Using cscope in Nvim *cscope-usage* *cscope-howtouse*
|
|
|
|
To get started, build the cscope database in your project root directory: >
|
|
cscope -bcqR
|
|
|
|
See the cscope manpage for details: >
|
|
:Man cscope
|
|
|
|
By default the cscope database file is named "cscope.out". After building the
|
|
database, connect to it from Nvim: >
|
|
:cscope add cscope.out
|
|
|
|
That establishes a cscope connection for Nvim to use. You can check the
|
|
result with ":cs show". It will show something like:
|
|
|
|
# pid database name prepend path
|
|
0 28806 cscope.out <none>
|
|
|
|
Once a cscope connection is established, you can make queries to cscope and
|
|
the results will be printed. Queries are made using the command ":cs find".
|
|
For example: >
|
|
:cs find g ALIGN_SIZE
|
|
|
|
To make this easier you can configure mappings, see |cscope-suggestions|.
|
|
|
|
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.
|
|
|
|
|
|
==============================================================================
|
|
Limitations *cscope-limitations*
|
|
|
|
Hard-coded limitation: doing a |:tjump| when |:cstag| searches the tag files
|
|
is not configurable (e.g., you can't do a tselect instead).
|
|
|
|
|
|
==============================================================================
|
|
Sample config *cscope-suggestions*
|
|
|
|
Copy this into your init.vim (adjust paths for your system): >
|
|
|
|
if has("cscope")
|
|
set csprg=/usr/local/bin/cscope
|
|
set csto=0
|
|
set cst
|
|
" add any database in current directory
|
|
if filereadable("cscope.out")
|
|
silent cs add cscope.out
|
|
" else add database pointed to by environment
|
|
elseif $CSCOPE_DB != ""
|
|
silent cs add $CSCOPE_DB
|
|
endif
|
|
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>
|
|
<
|
|
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|