Ctags and Cscope

In the last article on Ctags, I discussed how to install and use Ctags to browse source code. In this article, I do the same for Cscope. This article also includes a comparison between Cscope and Ctags.

Cscope is an interactive tool to browse C source code. It examines .c and .h files, yacc (.y files) and lex (.l files) in the current directory. It maintains a symbol cross-reference (cscope.out), which is used for finding language objects including C pre-processor symbols, function calls, function declarations, etc. The symbol table for cross-reference is created only once, when Cscope is used on the source files for the first time; it is rebuilt when the source is changed.

Features

Cscope creates its own database to allow faster searching. It provides a number of options for searching source code; it allows you to search for global definitions, calling functions, called functions, any C symbol, and any text string. It also enables you to find files, and to find files that #include a particular file. It even lets you change a text string.

Figure 1: Definition of symbol or function in a particular file

Figure 2: Calling function pointing to a function call

Installing Cscope

To install Cscope, you need to compile from the source. Get the latest version from http://sourceforge.net/projects/cscope/ files/ and follow the instructions given below.

Note: The steps to build and configure Cscope on Linux and Cygwin are the same. I built and installed Cscope under Cygwin on Windows.

Go to the Downloads folder and extract the source with tar–xvf cscope-15.7a.tar.bz2.

Make a separate directory, build_scope, with mkdir build_scope. Change into the build_scope directory, and then configure the source by running the configure utility in the extracted source. For example: /cygdrive/c/Users/root/ Downloads/cscope-15.7a/configure.

To build Cscope, next run ‘make’, followed by (as the root user) make install to install it. Check if the cscope command is available (on Windows+Cygwin, look for cscope.exe in the folder ‘/c/cygwin/usr/local/bin’ ). If it is, the build was successful.

Using Cscope

Change to the directory containing the files you want to index for search. In this example, let’s go to the GCC source code with cd /cygdrive/d/source_gcc/gcc-4.7.0/ gcc/. To generate the Cscope symbol table for cross reference, run cscope –R * and wait (it takes time to build the database). Then press the Return key to continue with Cscope. Your terminal will show a list of various functions that can be performed by Cscope.

The following are some examples that show the various functions of Cscope.

To find a global definition, enter the name of the symbol or function against the relevant option. I tried to find the function ‘simplify_subreg’. The results are listed, and to choose from them, go to the particular option and press Enter. This will redirect yoy to the particular file containing that symbol or function definition, as shown in Figure 1. Now, :q is used to quit from the file containing the function or symbol definition; CTRL+D is used to quit

Figure 3: Definition of the called function

Figure 4: Call to the specified function

from the Cscope terminal.

To find the functions called by a particular function, again, enter the name of that function against the option. (I tried to find the functions called by the function ‘assemble_integer’.) The results get listed as before; navigate them as was done earlier to go to the particular file containing the global definition of the calling function, at the point where the chosen function is called (shown in Figure 2). Then go to the called function name and use CTRL+] to jump to the definition of the called function, as shown in Figure 3.

To find functions calling a function, enter the name of the function; I searched for ‘expand_mult’. As before, choose one of the results to open the file containing that function definition, as in Figure 4. Then go to the called function name and use CTRL+] to jump to the definition of the called function, as shown in Figure 5.

CTRL+T is used to trace back to where you started your search in the particular directory.

To find a particular text string (for example, ‘Print an error’), follow the now-familiar procedure to open the file containing that text string, as shown in Figure 6.

Ctags vs Cscope

From the previous article and this, you can see that both tools are helpful in browsing through source code. You might be wondering which one to use. There are some basic differences. You might have noticed that Ctags takes you to the function where it is defined, whereas Cscope will show you the place where the function is defined, as well as the places where it is called (or referenced). Another important difference is that Ctags offers auto-completion of code. For example, if my_structure is a structure object, and you type my_structure. or my_structure->, it will pop up the list of elements of the structure. So, whether to use Ctags or Cscope is your choice; I generally use a combination of both, depending on the requirement!

Figure 5: Global definition of the called function

Figure 6: Location of the text string

References and further reading

[1] http://vim.wikia.com/wiki/Browsing_programs_with_tags [2] http://www.fsl.cs.sunysb.edu/~rick/cscope.html [3] http://cscope.sourceforge.net/cscope_vim_tutorial.html

By: Gaganpreet Kaur

The author is a software engineer at RF-Silicon Technologies Pvt Ltd. She is currently working as a part of the GCC Compiler Team on machine descriptions specific to targets. She can be reached at kang_276@yahoo.in.

Edited and mentored by: Deepti Sharma, project manager, Software Group, RF-Silicon Pvt Ltd. Deepti has considerable experience in design, development and quality validation of system software tools (compilers, assemblers, device drivers, etc) for embedded systems. She has also been a mentor and trainer on compiler development, following good practices and maintaining quality. She loves writing for and can be reached at deepti.acmet@gmail.com.