diff options
Diffstat (limited to 'runtime/doc/if_cscop.txt')
| -rw-r--r-- | runtime/doc/if_cscop.txt | 486 |
1 files changed, 486 insertions, 0 deletions
diff --git a/runtime/doc/if_cscop.txt b/runtime/doc/if_cscop.txt new file mode 100644 index 0000000..3fa8f81 --- /dev/null +++ b/runtime/doc/if_cscop.txt @@ -0,0 +1,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: |