| *if_cscop.txt* For Vim version 7.4. Last change: 2011 Jun 12 |
| |
| |
| 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. |
| {Vi does not have any of these commands} |
| |
| ============================================================================== |
| 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* *E561* *E560* |
| All cscope commands are accessed through suboptions to the main cscope |
| command ":cscope". The shortest abbreviation is ":cs". The ":scscope" |
| command does the same and also splits the window (short: "scs"). |
| |
| The available subcommands are: |
| |
| *E563* *E564* *E566* *E568* *E569* *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 |
| |
| 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 or i) 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- |
| < |
| *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> |
| |
| " 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> |
| |
| " 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> |
| |
| ============================================================================== |
| 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. |
| |
| If you want a newer version of cscope, you will probably have to buy it. |
| According to the (old) nvi documentation: |
| |
| You can buy version 13.3 source with an unrestricted license |
| for $400 from AT&T Software Solutions by calling +1-800-462-8146. |
| |
| Also you can download cscope 13.x and mlcscope 14.x (multi-lingual cscope |
| which supports C, C++, Java, lex, yacc, breakpoint listing, Ingres, and SDL) |
| from World-Wide Exptools Open Source packages page: |
| http://www.bell-labs.com/project/wwexptools/packages.html |
| |
| In Solaris 2.x, if you have the C compiler license, you will also have |
| cscope. Both are usually located under /opt/SUNWspro/bin |
| |
| SGI developers can also get it. Search for Cscope on this page: |
| http://freeware.sgi.com/index-by-alpha.html |
| https://toolbox.sgi.com/toolbox/utilities/cscope/ |
| The second one is for those who have a password for the SGI toolbox. |
| |
| 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. Please report |
| any problems, suggestions, patches, et al., you have for the usage of |
| cscope within Vim to him. |
| *cscope-win32* |
| For a cscope version for Win32 see: |
| http://code.google.com/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:ft=help:norl: |