7.3. cscope Utility
One of the most useful tools available as an open-source project under the BSD license is cscope. It is a utility used for interactively locating specified elements of code in C, C++, lex, or yacc source files. When you are dealing with large porting projects, cscope proves useful for finding references to a function, global definitions, functions called by a function, functions calling a function, text strings, regular expression patterns, files, and files including a specific file.
Linux distributions now include cscope as part of their standard distribution, but for those who need to download cscope and build it themselves, it can be found at http://cscope.sourceforge.net. As of this writing, the latest version is 15.5. The following steps describe how to build cscope from scratch, but first you must download cscope from http://cscope.sourceforge.net:
$ gunzip -c cscope-15.5.tar.gz | tar -xvf $ cd cscope-15.5/ $ ./configure --prefix=/usr/local $ make install
To build cscope, flex, bison, and libncurses need to be present and installed on the build system.
Prior to using cscope to browse and search for functions and text, you need to build a cscope database that contains all the searchable symbols in the source code. To do this, cscope needs to be invoked with the necessary switches. An easier way to build the cscope database is to use a script named ocs, which is included in the contrib directory of the cscope source code.
Invoke ocs in the top directory of the source code to be browsed as follows:
$ cd $TOP_DIR $TOP_DIR is the top of the source tree and where the cscope database resides $ ocs executing ocs without any flags runs cscope using the default cscope database
The ocs script goes through all the subdirectories and builds a list of files that will eventually be parsed by cscope to build the cscope database. After ocs finishes building the cscope database, it runs cscope using the cscope database, and it is ready for use. To exit cscope, just type ctl-d. The cscope database produced by default is called cscope.out. To update this database in case of code changes or addition to the source code, run ocs again with the u flag.
7.3.1. Vim and cscope
cscope is a useful tool for searching symbols and functions and invoking the developer's favorite editor to edit a file where these symbols and functions are found. However, cscope is limited such that if the developer wants to search for another symbol found in the current source file opened for editing, the programmer has to exit the editor invoked by cscope to return to the cscope default screen. When back at the cscope default screen, the programmer can then enter the symbol for cscope to do another search. This type of interaction can sometimes be tedious. To alleviate this problem, a number of open-source editors have incorporated support for cscope. The support enables programmers to search and open editing sessions for source code without the need to jump back to the cscope default screen to begin another search.
One such editor that supports cscope is Vim. Because some Linux distributions include Vim already compiled without turning on the support for cscope, it would be necessary to download the Vim source code and build it. To build Vim with cscope support, download Vim from www.vim.org. Then build it as follows:
$ bunzip2 vim-6.3.tar.bz2 $ tar -xvf vim-6.3.tar $ cd vim63/src $ ./configure --enable-cscope $ make $ make install
With cscope enabled in Vim, the programmer can use cscope through the Vim command cs. To add the cscope database, cscope.out, to Vim, invoke cs by typing <esc> :cs add cscope.out. Invoke cs again with the show argument, as in <esc> :cs show, to show whether Vim has any cscope connections. If there is a cscope connection, Vim shows the following output:
# pid database name prepend path 0 22212 cscope.out <none>
Invoking cs by itself prints the arguments that can be used to invoke cscope to do its search features. The find argument to cs invokes the different search features of cscope. For example, <esc> :cs find g symbol_name finds the definition of a symbol.
Here is the help screen printed when :cs is invoked by itself:
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)
The cscope subcommand cs can be invoked using Vim shortcuts, too. This eliminates typing cs commands and enables the programmer to place the cursor on the symbol and press the programmed shortcut key, which expands and executes the command to start the cscope search automatically. Vim shortcuts can be placed in the .vimrc file to automatically program them when Vim is invoked. The following is an example of a .vimrc that programs the F5 and F6 keys to invoke cscope commands to find symbol definitions and find the C symbol in all files, respectively:
$ cat .vimrc if has("cscope") set csprg=/usr/local/bin/cscope set csto=0 set cst set nocsverb map <F5> :cs find g <C-R>=expand("<cword>")<CR><CR> map <F6> :cs find s <C-R>=expand("<cword>")<CR><CR> cs add cscope.out set csverb endif
Vim also keeps track of files that were opened previously during a Vim session. This is called a tag stack. This enables the programmer to back up to previous files using Ctrl-T. For example, if Vim opens foo.c and within the same session the programmer searches for symbol1 and cscope finds it in foo1.c, Vim opens foo1.c for editing. Then in foo1.c the programmer searches for symbol2, and cscope finds it in foo2.c. Vim then opens foo2.c for editing. If the programmer wants to go back to foo.c, all he has to do is press Ctrl-T twice to go back to foo.c. The tag stack is a convenient way to jump back to previously opened files. More information on how to use cscope with Vim is included in the Vim documentation included in the Vim source code distribution.