# Vim documentation: if_cscope

main help file

    *if_cscope.txt* For Vim version 6.0au.  Last change: 2001 Jul 23

    		  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 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*
    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:

        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

        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 assignments to
    		6 or e: Find this egrep pattern
    		7 or f: Find this file
    		8 or i: Find files #including this file

    	EXAMPLES
    	    :cscope find c vim_free
    	    :cscope find 3 vim_free

    	    These two examples perform the same query.

    	    :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

    						*E260* *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

    							*:cstag* *E257*
    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

    							*cscopetag* *cst*
    If 'cscopetag' 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

    							*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>

    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.

    Libraries are available for Win95 (win32) which translate a lot of Unix
    system calls to the Win32 API.  You can try the GNU-Win32 Project from Cygnus
    	http://www.cygnus.com/misc/gnu-win32 or the DJGPP suite of tools
    	http://www.delorie.com/djgpp/. I do not know the status of using these with
    Vim, so they may or may not work.

    Additionally, there are a couple of hard-coded limitations:

        1. The maximum number of cscope connections allowed is 8.  Do you
        really need more?

        2. 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.

    ==============================================================================

    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 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.

    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.  Currently a tardist file can be found at:
    	ftp://ftp.openage.com/pub/Sgi/Binaries/Cscope-13_3_tardist.gz
    	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.

    top - main help file