cscope:Interactively
|
4 |
 |
This chapter is a tutorial on the cscope browser, which is provided with this release.
Note - SourceBrowser, a window-oriented code browser that is more powerful than cscope, is described briefly in "SourceBrowser" on page 102. SourceBrowser is sold separately.
When cscope has completed this search, it prints a list. Each list entry contains the name of the file, the number of the line, and the text of the line in which cscope has found the specified code. In our case, the list also includes the names of the functions that call the specified function. You now have the option of requesting another search or examining one of the listed lines with the editor. If you choose the latter, cscope invokes the editor for the file in which the line appears, with the cursor on that line. You can now view the code in context and, if you wish, edit the file as any other file. You can then return to the menu from the editor to request a new search.
Because the procedure you follow depends on the task at hand, there is no single set of instructions for using cscope. For an extended example of its use, review the cscope session described in the next section. It shows how you can locate a bug in a program without learning all the code.
In a Bourne shell, type:
$ TERM=term_name; export TERMIn a C shell, type:
% setenv TERM term_nameYou may now want to assign a value to the EDITOR environment variable. By default, cscope invokes the vi editor. (The examples in this chapter illustrate vi usage.) If you prefer not to use vi, set the EDITOR environment variable to the editor of your choice and export EDITOR, as follows:
In a Bourne shell, type:
$ EDITOR=emacs; export EDITORIn a C shell, type:
% setenv EDITOR emacsYou may have to write an interface between cscope and your editor. For details, see "Command-Line Syntax for Editors" on page 101.
If you want to use cscope only for browsing (without editing), you can set the VIEWER environment variable to pg and export VIEWER. cscope will then invoke pg instead of vi.
Step 2: Invoke the cscope Program
By default, cscope builds a symbol cross-reference table for all the C, lex, and yacc source files in the current directory, and for any included header files in the current directory or the standard place. So, if all the source files for the program to be browsed are in the current directory, and if its header files are there or in the standard place, invoke cscope without arguments:% cscope
To browse through selected source files, invoke cscope with the names of those files as arguments:% cscope file1.c file2.c file3.h
For other ways to invoke cscope, see "Command-Line Options" on page 93.
cscope builds the symbol cross-reference table the first time it is used on the source files for the program to be browsed. By default, the table is stored in the file cscope.out in the current directory. On a subsequent invocation, cscope rebuilds the cross-reference only if a source file has been modified or the list of source files is different. When the cross-reference is rebuilt, the data for the unchanged files is copied from the old cross-reference, which makes rebuilding faster than the initial build, and reduces startup time for subsequent invocations.
Step 3: Locate the Code
Now let's return to the task we undertook at the beginning of this section: to identify the problem that is causing the error message out of storage to be printed. You have invoked cscope, the cross-reference table has been built. The cscope menu of tasks appears on the screen.
If the first character of the text for which you are searching matches one of these commands, you can escape the command by entering a \ (backslash) before the character.
cscope searches for the specified text, finds one line that contains it, and reports its finding.
Note - Follow the same procedure to perform any other task listed in the menu except the sixth, Change this text string. Because this task is slightly more complex than the others, there is a different procedure for performing it. For a description of how to change a text string, see "Examples" on page 97.
Again, if the first character of the text for which you are searching matches one of these commands, you can escape the command by entering a backslash before the character.
You can see that the error message is generated when the variable p is NULL. To determine how an argument passed to alloctest() could have been NULL, you must first identify the functions that call alloctest().
cscope finds and lists three such functions.
Now you want to know which functions call mymalloc(). cscope finds ten such functions. It lists nine of them on the screen and instructs you to press the space bar to see the rest of the list.
Because you know that the error message out of storage is generated at the beginning of the program, you can guess that the problem may have occurred in the function dispinit() (display initialization).
mymalloc() failed because it was called either with a very large number or a negative number. By examining the possible values of FLDLINE and REFLINE, you can see that there are situations in which the value of mdisprefs is negative, that is, in which you are trying to call mymalloc() with a negative number.
Step 4: Edit the Code
On a windowing terminal, you may have multiple windows of arbitrary size. The error message out of storage might have appeared as a result of running prog in a window with too few lines. In other words, that may have been one of the situations in which mymalloc() was called with a negative number. Now you want to be sure that when the program aborts in this situation in the future, it does so after printing the more meaningful error message screen too small. Edit the function dispinit() as follows.
You have fixed the problem we began investigating at the beginning of this section. Now if prog is run in a window with too few lines, it does not simply fail with the unedifying error message out of storage. Instead, it checks the window size and generates a more meaningful error message before exiting.
Command-Line Options
As noted, cscope builds a symbol cross-reference table for the C, lex, and source files in the current directory by default. That is,% cscope
is equivalent to:% cscope *.[chly]
We have also seen that you can browse through selected source files by invoking cscope with the names of those files as arguments:% cscope file1.c file2.c file3.h
cscope provides command-line options with greater flexibility in specifying source files to be included in the cross-reference. When you invoke cscope with the -s option and any number of directory names (separated by commas):% cscope -s dir1,dir2,dir3
cscope builds a cross-reference for all the source files in the specified directories as well as the current directory. To browse through all of the source files whose names are listed in file (file names separated by spaces, tabs, or new-lines), invoke cscope with the -i option and the name of the file containing the list:% cscope -i file
If your source files are in a directory tree, use the following commands to browse through all of them:% find . -name '*.[chly]' -print | sort > file
If this option is selected, however, cscope ignores any other files appearing on the command-line.
% cscope -i file
-I option can be used for cscope in the same way as the -I option to cc. See "Include Files" on page 64.
You can specify a cross-reference file other than the default cscope.out by invoking the
-f option. This is useful for keeping separate symbol cross-reference files in the same directory. You may want to do this if two programs are in the same directory, but do not share all the same files: % cscope -f admin.ref admin.c common.c aux.c libs.c
In this example, the source files for two programs, admin and delta, are in the same directory, but the programs consist of different groups of files. By specifying different symbol cross-reference files when you invoke cscope for each set of source files, the cross-reference information for the two programs is kept separate.
% cscope -f delta.ref delta.c common.c aux.c libs.c
-pn option to specify that cscope display the path name, or part of the path name, of a file when it lists the results of a search. The number you give to -p stands for the last n elements of the path name you want to be displayed. The default is 1, the name of the file itself. So if your current directory is home/common, the command: % cscope -p2
causes cscope to display common/file1.c, common/file2.c, and so forth when it lists the results of a search.-b option, so that cscope stops after it has built a cross-reference; cscope does not display a menu of tasks. When you use cscope -b in a pipeline with the batch(1) command, cscope builds the cross-reference in the background: % echo 'cscope -b' | batch
Once the cross-reference is built, and as long as you have not changed a source file or the list of source files in the meantime, you need only specify:% cscope
for the cross-reference to be copied and the menu of tasks to be displayed in the normal way. You can use this sequence of commands when you want to continue working without having to wait for cscope to finish its initial processing.-d option instructs cscope not to update the symbol cross-reference. You can use it to save time if you are sure that no such changes have been made; cscope does not check the source files for changes.
Check the cscope(1) man page for other command-line options.
Note - Use the -d option with care. If you specify -d under the erroneous impression that your source files have not been changed, cscope refers to an outdated symbol cross-reference in responding to your queries.
View Paths
As we have seen, cscope searches for source files in the current directory by default. When the environment variable VPATH is set, cscope searches for source files in directories that comprise your view path. A view path is an ordered list of directories, each of which has the same directory structure below it.$ VPATH=/usr/you:/fs1/ofc; export VPATH
In a C shell, type:% setenv VPATH /usr/you:/fs1/ofc
You then make your current directory /usr/you/src/cmd/prog1, and invoke cscope:% cscope
The program locates all the files in the view path. In case duplicates are found, cscope uses the file whose parent directory appears earlier in VPATH. Thus, if f2.c is in your directory, and all three files are in the official directory, cscope examines f2.c from your directory, and f1.c and f3.c from the official directory. cscope and Editor Call Stacks
cscope and editor calls can be stacked. That is, when cscope puts you in the editor to view a reference to a symbol and there is another reference of interest, you can invoke cscope again from within the editor to view the second reference without exiting the current invocation of either cscope or the editor. You can then back up by exiting the most recent invocation with the appropriate cscope and editor commands. Examples
This section presents examples of how cscope can be used to perform three tasks: changing a constant to a preprocessor symbol, adding an argument to a function, and changing the value of a variable. The first example demonstrates the procedure for changing a text string, which differs slightly from the other tasks on the cscope menu. That is, once you have entered the text string to be changed, cscope prompts you for the new text, displays the lines containing the old text, and waits for you to specify which of these lines you want it to change. Changing a Constant to a Preprocessor Symbol
Suppose you want to change a constant, 100, to a preprocessor symbol, MAXSIZE. Select the sixth menu item, Change this text string, and enter \100. The 1 must be escaped with a backslash because it has a special meaning (item 1 on the menu) to cscope. Now press Return. cscope prompts you for the new text string. Type MAXSIZE.
cscope displays the lines containing the specified text string, and waits for you to select those in which you want the text to be changed.
In this case, enter 1, 2, and 3. The numbers you type are not printed on the screen. Instead, cscope marks each list item you want to be changed by printing a > (greater than) symbol after its line number in the list.
Now type ^d to change the selected lines. cscope displays the lines that have been changed and prompts you to continue.
Changed lines: char s[MAXSIZE]; for (i = 0; i < MAXSIZE; i++) if (c < MAXSIZE) {
Press the RETURN key to continue: |
When you press Return in response to this prompt, cscope redraws the screen, restoring it to its state before you selected the lines to be changed.
To resume the cscope session, quit the editor and type ^d to exit the shell.
Adding an Argument to a Function
Adding an argument to a function involves two steps: editing the function itself and adding the new argument to every place in the code where the function is called. Changing the Value of a Variable
At times, you may want to see how a proposed change affects your code. Command-Line Syntax for Editors
cscope invokes the vi editor by default. You can override the default setting by assigning your preferred editor to the EDITOR environment variable and exporting EDITOR, as described in "Step 1: Set Up the Environment" on page 84. However, cscope expects the editor it uses to have a command-line syntax of the form:
% editor +linenum filename
as does vi. If the editor you want to use does not have this command-line syntax, you must write an interface between cscope and the editor.
/usr/bin/ed $2 |
Let's name the shell script myedit. Now set the value of EDITOR to your shell script and export EDITOR:
$ EDITOR=myedit; export EDITOR
In a C shell, type:% setenv EDITOR myedit
When cscope invokes the editor for the list item you have specified, say, line 17 in main.c, it invoke your shell script with the command-line:% myedit +17 main.c
myedit then discards the line number ($1) and calls ed correctly with the file name ($2). Of course, you are not moved automatically to line 17 of the file and must execute the appropriate ed commands to display and edit the line.
Unknown Terminal Type Error
If you see the error message:Sorry, I don't know how to deal with your "term" terminal
your terminal may not be listed in the Terminal Information Utilities (terminfo) database that is currently loaded. Make sure you have assigned the correct value to TERM. If the message reappears, try reloading the Terminal Information Utilities.Sorry, I need to know a more specific terminal type than "unknown"
set and export the TERM variable as described in "Step 1: Set Up the Environment" on page 84.
SourceBrowser
The SourceBrowser is an interactive tool to aid programmers in the development and maintenance of software systems, particularly large ones. Because the SourceBrowser builds a database and uses it to respond to queries, once the database it built, the size of the code you are browsing has minimal impact on SourceBrowser's speed.