8.2.5 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
% cscope– i file

If this option is selected, however, cscope ignores any other files appearing on the command-line.

The– I option can be used for cscope in the same way as the– I option to cc. See 2.14 How to Specify Include Files.

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
% cscope– f delta.ref delta.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.

You can use the– 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.

If the program you want to browse contains a large number of source files, you can use the– 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.

The– 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.

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.

Check the cscope(1) man page for other command-line options.