Browsing Large source base using cscope

cscope is a developer’s tool for browsing source code. It allows searching code for: all references to a symbol, global definitions, functions etc.

Here is a simple example to illustrate the problem:

main()

{

FILE *p;

va_list p;

}

It’s quite difficult for a beginner to understand what is FILE & va_list. Simply you are made to know that p is a pointer to the file structure & va_list creates internally a variable argument list. But do you feel this information to be sufficient enough to clarify the doubt. Absolutely not, there you should surely go for the cscope.

cscope is used in two phases. First a developer builds the cscope database using find command to get the list of filenames that need to index into a file called cscope files.

Syntax:

$ find /usr/include/ -name “*.h”>myfile

This will include all header files to generate a database.

Second, the developer builds symbol database using cscope by specifying the file name list created in the above stop.

$ cscope -i myfile

This will take some time to build the symbol database & cscope will display the following input menu. Use up and down arrow key to move to the desired input menu.

 

Find this C symbol:

Find this global definition:

Find functions called by this function:

Find functions calling this function:

Find this text string:

Change this text string:

Find this egrep pattern:

Find this file:

 

Once the cscope cross reference database is built (usually named cscope.out and is generated in the current directory where cscope is run), you can search the database using ‘-d’ option of cscope. If you change the source files, then you may have to rebuild the symbol database.

Note: Make sure that when you are running cscope with –d option, cscope.out (symbol database) is present in the directory where are executing the cscope command.

Working with cscope

Open two terminals, one for writing the program & another to browse the code.

Invoke cscope in the second terminal, it will display two paragraphs, the top paragraph displays the results and bottom paragraph displays the options and accepts input from the user. Type va_list under “Find this global definition” menu as show below. 

It will display the following

File Line

0 slang.h 1012 SL_EXTERN void (*SLang_VMessage_Hook) (char *, va_list);

1 slang.h 1019 SL_EXTERN void (*SLang_Exit_Error_Hook)(char *, va_list);

2 sqlite3ext.h 151 char *(*vmprintf)(const char *,va_list);

3 stdio.h 80 typedef _G_va_list va_list;

4 tiffio.h 259 typedef void (*TIFFErrorHandler)(const char *, const char *,

va_list);

* 3 more lines – press the space bar to display more *

Find this C symbol:

Find this global definition: va_list

Find functions called by this function:

Find functions calling this function:

Find this text string:

Change this text string:

Find this egrep pattern:

Find this file: 

The top paragraph which displays the result, contains identifiers for each result line. In our case, it displays numbers 0 to 4. The output also contains file name, line number and the exact string which matched the input string specified. By pressing the appropriate key (in our case 0 to 4), automatically vi opens that file.  When you exit from the vi editor using “:q” you will be taken back to the cscope window. Press CTRL-D to exit from the cscope window.

Commands console to deal with cscope

:q – To go back to the menu.

Ctrl+d – To stop cscope or change the marked lines and exit

Up-arrow & down arrow – To move the cursor in the menu list.

Tab – For moving the cursor from upper paragraph to lower paragraph.

Space bar -To display more lines

0-9a-zA-Z – To edit the file referenced by the given identifier in the top output paragraph

                     or to mark or unmark lines to be changed

+ – Displays next set of matching lines

– – Displays previous set of matching lines

* – Mark or unmark all displayed lines to be changed

Esc – Exit without changing the marked line. 

Advantages of cscope

It is very useful when working on large project which contain thousands of source code files. It reduces the development effort by multi fold and increases the productivity.

  • While development, it is difficult for developers to remember all the structure names and its members. Often we search the required header file to know the members of a structure. This can be done easily using cscope
  • Often we need to know, before modifying a function (adding new arguments, changing implementation, etc), we need to make sure that all the callers of that function do not get affected by this modification. To do this we need to know first what functions are calling these functions. cscope tool comes handy to reduce your effort
  • When we are changing MACRO name or function name, all the files which references that macro or calls that function needs to be changed. With cscope you can do this much faster than doing it manually by editing each and every source file after searching that macro.
  • It helps maintenance engineers to understand the code flow of huge source base written by somebody else. If this tool is used together with “gdb”, it provides both static and run time code flow of the part of the code under investigation for bug analysis. This reduces the bug analysis and fixing time for maintenance engineers drastically

 

Advertisements