Cscope

Proposed tip Please edit this page to improve it, or add your comments below (do not use the discussion page).

Please use new tips to discuss whether this page should be a permanent tip, or whether it should be merged to an existing tip.

created November 2, 2009 · complexity basic · author Tonymec · version 6.2

---

Cscope is a very powerful interface allowing you to scan C-like sources for not only identifier definitions, but also their uses, or even any regular expression in the text, and more; and the "standard include files" of your compiler are automagically added to "your" sources (if cscope can find them, and for me it can). The output from the ":cscope help" command says it all:

cscope commands:
add  : Add a new database             (Usage: add file|dir [pre-path] [flags])
find : Query for a pattern            (Usage: find c|d|e|f|g|i|s|t name)
       c: Find functions calling this function
       d: Find functions called by this function
       e: Find this egrep pattern
       f: Find this file
       g: Find this definition
       i: Find files #including this file
       s: Find this C symbol
       t: Find assignments to
help : Show this message              (Usage: help)
kill : Kill a connection              (Usage: kill #)
reset: Reinit all connections         (Usage: reset)
show : Show connections               (Usage: show)

Generating the database

Before you can use cscope on a set of source files, you must have a cscope database applying to them. For instance, the following patch to the Vim src/Makefile adds a few targets related to generating a cscope database for the Vim source (and the "usual" include files, which cscope is clever enough to find):

*** src/Makefile	2009-06-17 23:31:27.000000000 +0200
--- ../vim72/src/Makefile	2009-06-18 02:01:45.000000000 +0200
***************
*** 1734,1739 ****
--- 1734,1748 ----
  tags TAGS: notags
  	$(TAGPRG) $(TAGS_SRC) $(TAGS_INCL)
  
+ # Build the cscope database.
+ # This may search more files than necessary.
+ .PHONY: cscope csclean
+ csclean:
+ 	-rm -vf cscope.out
+ cscope.out:
+ 	cscope -bv ./*.[ch] ./*.cpp ./if_perl.xs auto/*.h auto/pathdef.c proto/*.pro
+ cscope: csclean cscope.out  ;
+ 
  # Make a highlight file for types.  Requires Exuberant ctags and awk
  types: types.vim
  types.vim: $(TAGS_SRC) $(TAGS_INCL)

Using these targets works best after compiling Vim, since it also scans files in auto/ which are generated by the [configure+]make run.

Setting up Vim to use cscope

The following snippet from my .vimrc sets up Vim to use cscope:

if has('cscope')
	set cst csverb 
	if has('quickfix')
		set csqf=s-,c-,d-,i-,t-,e-
	endif
	if version < 700
		cnoreabbrev csa cs add
		cnoreabbrev csf cs find
		cnoreabbrev csk cs kill
		cnoreabbrev csr cs reset
		cnoreabbrev css cs show
		cnoreabbrev csh cs help
	else
		cnoreabbrev <expr> csa
		 \ ((getcmdtype() == ':' && getcmdpos() <= 4)? 'cs add'  : 'csa')
		cnoreabbrev <expr> csf
		 \ ((getcmdtype() == ':' && getcmdpos() <= 4)? 'cs find' : 'csf')
		cnoreabbrev <expr> csk
		 \ ((getcmdtype() == ':' && getcmdpos() <= 4)? 'cs kill' : 'csk')
		cnoreabbrev <expr> csr
		 \ ((getcmdtype() == ':' && getcmdpos() <= 4)? 'cs reset' : 'csr')
		cnoreabbrev <expr> css
		 \ ((getcmdtype() == ':' && getcmdpos() <= 4)? 'cs show' : 'css')
		cnoreabbrev <expr> csh
		 \ ((getcmdtype() == ':' && getcmdpos() <= 4)? 'cs help' : 'csh')
	endif
	command -nargs=0 Cscope cs add $VIMSRC/src/cscope.out $VIMSRC/src
	if has('autocmd')
		au VimLeave * cs kill -1
	endif
endif

Explanation:

if has('cscope')

If Vim hasn't got support for cscope, it's no use trying to use that support, so we bracket this whole snippet in this if statement to avoid unnecessary errors.

set cst csverb

• 'cscopetag' on means Vim will include the cscope database whenever we search for a tag (e.g. by hitting <CTRL-]> in a C program).
• 'cscopeverbose' on (optional) gives us a success/failure message when trying to add a cscope database (including the one near the end of this snippet).

'cscopequickfix'

(only if +quickfix compiled-in) specifies when to use quickfix for the output of cscope commands. We use the value given as example in the Vim help.

cnoreabbrev

Here we set up a number of command-line-mode abbreviations to make cscope commands easier to type. In Vim 7.0 or higher, we take advantage of the new <expr> modifier to only expand these abbreviations at the start of the command-line.
The use of continuation lines assumes that 'nocompatible' is set, which is the default anyway if your vimrc is named .vimrc or _vimrc (but not .exrc or _exrc, or anything with a -u command-line switch).

cs add

We define a command :Cscope which will try to open the cscope database for the Vim source, and tell cscope that the relative paths in it are relative to the src directory containing the database itself (this assumes that the $VIMSRC variable has been set to the top directory of the Vim source: I use ~/.build/vim/vim72 for Vim 7.2, but of course YMMV).

cs kill

Finally, we set up an autocommand to close any cscope database(s) when exiting Vim.
(Inspection of the Vim C source shows that this is not necessary — Vim does it anyway — but I prefer to leave it in on general "good programming practice" principles: "Always close what you have opened.")

Using cscope commands

This is the simplest: if you've forgotten the fine points, :cs help (or, with the above abbreviations, :csh) will tell you.

See also

:help if_cscop.txt

Comments

Please sign your comments with ~~~~, and separate unrelated comments with four dashes on their own line. Tonymec 05:36, November 2, 2009 (UTC)

---