Browsing through your code with cscope

Command line options

As noted, cscope builds a symbol cross-reference table for the C, lex, and yacc source files in the current directory by default.

   $ cscope

is equivalent to

   $ cscope *.[chly]

The following example shows how 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 that allow you 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 dir,dir,dir

cscope will build 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, the following commands will allow you to browse through all of them easily:

   $ find . -name '*.[chly]' -print | sort > file
   $ cscope  -i  file

Note that if this option is selected, cscope ignores any other files appearing on the command line.

The -I option to cscope is similar to the -I option to cc. By default, cscope searches for included header files in the current directory, then the standard place. If you want cscope to search for an included header file in a different directory, specify the path of the directory with -I:

   $ cscope -I dir

In this example, cscope will search the directory dir for #include files called into the source files in the current directory. Directories are searched for #include files in the following order:

the current directory;
the directories specified with -I;
the standard place for header files, usually /usr/include.

You can invoke the -I option more than once on a command line. cscope will search the specified directories in the order they appear on the command line.

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

will cause 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 to tell cscope to stop after it has built a cross-reference; cscope will not display a menu of tasks. When you use cscope -b in a pipeline with the batch command, cscope will build the cross-reference in the background:

   $ echo 'cscope -b' | batch

NOTE: See the description of batch on at(1) for more information.

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. In other words, 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 -- cscope will not check the source files for changes -- if you are sure that no such changes have been made.

NOTE: Use the -d option with care. If you specify -d under the erroneous impression that your source files have not been changed, cscope will refer to an outdated symbol cross-reference in responding to your queries.

To use cscope separately on several programs in the same directory structure while keeping the databases in the same directory, use the -f and -i options to rename the cscope.out and cscope.files file as follows:

        find dir1 -name '*.[chlyCGHL}' -print >dir1.files
        find dir2 -name '*.[chlyCGHL}' -print >dir2.files
        cscope -b -f dir1.db -i dir1.files
        cscope -b -f dir2.db -i dir2.files

Call cscope with:

       cscope -d -f dir2.db

Options used only when building the database, such as -i are not needed with the -d option. Use the -P option to give the path to relative file names so the script does not have to change to the directory where the database was built.

The -Ffile option reads symbol reference lines from file, similar to the < command.

The -q option builds an inverted index for quick symbol searching. If you use this option with the -f option, you must use -f on every call to cscope including building the database, because it changes the names of the inverted index files. For large databases, you will be able to find a symbol in a few seconds instead of the several minutes it can take to build without -q, at the expense of about twice as much database disk space and build CPU time. Updating a -q database takes about half as long as building it. It contains binary numbers, so it is portable only between machines with the same byte ordering.

The -q option makes it practical to have databases for entire projects. If you try to build a project database and get a file too large message, you need to get your login's ulimit raised by your system administrator. [See sh(1) for information on the shell built-in ulimit command.] If you get the no space left on device message, you will have to use a file system with more space. You can change the temporary file system by setting the TMPDIR environment variable. If you have enough space to build the database but not to rebuild it after some files have changed, try removing the inverted index cscope.in.out and cscope.po.out files. If you still don't have enough space to rebuild, remove the cscope.out file.

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