Using cscope for better source-code browsing

In my last two posts (here and here), I explained how you can simplify the task of browsing through code. So why is it that I’m writing another post on the same topic?

If you use the tags method I described, you’ll notice one small drawback. I can jump across function definitions to follow the flow of code, but I cannot:
a) See which functions are calling the function I’m browsing.
b) See a list of all the functions called by the current function.

These are serious drawbacks when you’re trying to hack through the jungle of kernel-code. This is where Cscope comes into the picture.

Cscope is designed to answer questions like:
Where is this variable used?
What is the value of this preprocessor symbol?
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?

You can download the tarball here. Extract the contents into a convenient directory, and let’s get ready to roll.

To install Cscope, open a terminal and navigated to the extracted directory.
Now run the commands

./configure
make
sudo make install

This should install cscope on your computer. I use cscope with emacs, so the next set of steps explain how to integrate it with emacs. If you wish to use csope with other browsers, please visit their website (http://cscope.sourceforge.net) for instructions.

1) Make the ‘cscope-indexer’ script (in cscope/contrib/xcscope) executable.

sudo chmod a+x ./contrib/xcscope/cscope-indexer

2)Copy it into /usr/bin or /usr/sbin (it needs to be in $PATH)

sudo cp ./contrib/xcscope/cscope-indexer /usr/bin

3)Copy the file xcscope.el (in cscope/contrib/xcscope) to /etc/emacs (basically it has to be in the emacs load-path)

sudo cp ./contrib/xcscope/xcsope.el /etc/emacs

4)Edit your ~/.emacs file and add the line

(require ‘xcscope)

Now you can use the cscope key bindings in emacs. Here is a list of the most common key-bindings:

1) to create a cscope database for your code files, navigate to the topmost direcory (under which all your code directories of current project are) in emacs (using C-x,C-f) and type C-c s I. This should create the files cscope.out and cscope.files. These together represent your database

2)While browsing through any source code file, use the following bindings:
C-c s s Find symbol.
C-c s d Find global definition.
C-c s g Find global definition (alternate binding).
C-c s G Find global definition without prompting.
C-c s c Find functions calling a function.
C-c s C Find called functions (list functions called
from a function).
C-c s t Find text string.
C-c s e Find egrep pattern.
C-c s f Find a file.
C-c s i Find files #including a file.

3)To navigate the cscope search results use:
C-c s n Next symbol.
C-c s N Next file.
C-c s p Previous symbol.
C-c s P Previous file.

4)Once you have satisfied your curiosity, you can return to the point from where you jumped using
C-c s u Pop Mark

And thus, you have complete control over code navigation! I have used the file xcscope.el as a reference, and it goes on to detail far more complex tasks using cscope. Look into it once you get the hang of cscope!

Tags: cscope, Emacs, Open Source, Tutorials