cscope tutorial: Using Cscope on large projects

Cscope can be a particularly useful tool if you need to wade into a large codebase. You can save yourself a lot of time by being able to do fast, targetedsearches rather than randomly grepping through the source files by hand(especially since grep starts to take a while with a truly large code base).

当涉及大量代码的时候，Cscope就是一个非常有用的工具。相比不断的手工检索源代码文件（比如使用grep命令，当在大量代码的目录中搜索的时候就会很耗费时间），Cscope可以节约时间，做更快的有目的的事情。

In this tutorial you'll learn how to set up Cscope with a large project.We'll use as our example the Linux kernel source code, but the basic steps arethe same for any other large project, including C++ or Java projects.

该指南可以作为学习配置Cscope来浏览项目之用。这里用linux kernel源代码作为例子，但是其他的项目中使用Cscope的基本步骤是一样的，比如C++或者Java项目。

1.Get the source. First get the source code. You can download the Linux kernel source from http://www.kernel.org. For the rest of this tutorial, I'll assume you've downloaded Linux 2.4.18 and installed it into /home/jru/linux-2.4.18.

Note: Make sure you've got enough disk space: the kernel tarball alone is 30 MB, it expands into 150 MB of source code, and the Cscope database we'll generate will gobble up another 20-100+ MB (depending on how much of the kernel code you decide to include in the database). You can put the Cscope database on a different disk partition than the source code if you need to.

1.获得源代码。可以到www.kernel.org下载linux内核源代码。该指南假设，Linux2.4.18的内核源代码已经下载并安装在/home/jru/linux-2.4.18.

注意：请确定有足够的磁盘空间。内核源代码树压缩文件会占据30MB空间，解压后大约有150MB。此外，Cscope为内核源代码产生的数据库需要额外占据20-100MB(数据库占用空间的大小决定于Cscope为多少内核代码建立数据库)。当然Cscope的数据库可以存放在不同于linux内核源代码树的目录，如果需要的话。

2.Figure out where you want to put your Cscope database files. I'll assume you'll use /home/jru/cscope as the directory to store your database and associated files.

2.请自行决定在何处存放Cscope为源码树产生的数据库。这里假设Cscope数据库和相关文件存放在/home/jru/cscope下.

3.Generate cscope.files with a list of files to be scanned. For some projects, you may want to include every C source file in the project's directories in your Cscope database. In that case you can skip this step, and just use 'cscope -R' in the project's top-level directory to build your Cscope database. But if there's some code that you wish to exclude, and/or your project contains C++ or Java source code (by default Cscope only parses files with the .c, .h, .y, or .l extensions), you'll need to generate a file called cscope.files, which should contain the name of all files that you wish to have Cscope scan (one file name per line).

3.创建一个名为cscope.files的文件，该文件是Cscope扫描源代码文件并创建数据库时所使用的清单。对于一些项目来说，可能不需要扫描项目下每个C源文件。你也可以省略这一步，直接在项目的顶层目录使用‘cscope -R’命令来创建Cscope数据库。但是如果你需要排除项目中的一些源代码文件，或者项目中包含C++或者Java源文件（Cscope默认只遍历以.c .h .y .l作为文件扩展名的文件），你就必须要创建cscope.files文件了。该文件应该包含所有你想让Cscope扫描并将扫描后的数据存入数据库的源文件名（每个文件名占据一行）。

You'll probably want to use absolute paths (at least if you're planning to use the Cscope database within an editor), so that you can use the database from directories other than the one you create. The commands I show will first cd to root, so that find prints out absolute paths.

你应该使用绝对路径（毕竟你在一个编辑器中使用Cscope创建的数据库），这样你才能在不同的目录中使用这个cscope数据库。作为示例，首先cd到根目录中，这样才能找到绝对路径。

For many projects, your find command may be as as simple as

对于大多数项目来说，命令大约是这样子的：
    cd /
    find /my/project/dir -name '*.java' >/my/cscope/dir/cscope.files

For the Linux kernel, it's a little trickier, since we want to exclude all the code in the docs and scripts directories, plus all of the architecture and assembly code for all chips except for the beloved Intel x86 (which I'm guessing is the architecture you're interested in). Additionally, I'm excluding all kernel driver code in this example (they more than double the amount of code to be parsed, which bloats the Cscope database, and they contain many duplicate definitions, which often makes searching harder. If you are interested in the driver code, omit the relevant line below, or modify it to print out only the driver files you're interested in):

但是对于linux内核源代码来说稍微需要点花招。因为我们想要排除那些脚本文件和说明文档，同时那些平台构架相关的汇编代码我们也不是很感兴趣（x86除外，我猜那是你唯一感兴趣的平台）。另外，在这个例子中我也想要排除一些驱动代码（它们在内核源代码中占据很多代码文件，会使cscope数据库更加肿胀，而且大多数驱动代码包含重复的定义，影响代码可读性。如果你对驱动代码感兴趣，请忽略这一步，或者修改下面的命令只将你感兴趣的驱动代码源文件放到cscope.files中）：

     LNX=/home/jru/linux-2.4.18
     cd /
     find $LNX \
      -path "$LNX/arch/*" ! -path "$LNX/arch/i386*" -prune -o \
      -path "$LNX/include/asm-*" ! -path "$LNX/include/asm-i386*" -prune -o \
      -path "$LNX/tmp*" -prune -o \
      -path "$LNX/Documentation*" -prune -o \
      -path "$LNX/scripts*" -prune -o \
      -path "$LNX/drivers*" -prune -o \
      -name "*.[chxsS]" -print >/home/jru/cscope/cscope.files

While find commands can be a little tricky to write, for large projects they are much easier than editing a list of files manually, and you can also cut and paste a solution from someone else.

上面的find命令看上去有点难写，不过对于大的工程项目来说毕竟比自己一行一行写cscope.files文件好多了
不是吗。你也可以定制自己的解决方案，如果需要的话。

4.Generate the Cscope database. Now it's time to generate the Cscope database:
现在可以为我们的项目生成Cscope数据库了：

    cd /home/jru/cscope # the directory with 'cscope.files'
    cscope -b -q -k

    The -b flag tells Cscope to just build the database, and not launch the Cscope GUI. The -q causes an additional, 'inverted index' file to be created, which makes searches run much faster for large databases. Finally, -k sets Cscope's 'kernel' mode--it will not look in /usr/include for any header files that are #included in your source files (this is mainly useful when you are using Cscope with operating system and/or C library source code, as we are here).

参数-b告诉Cscope只建数据库，不要启动GUI。-q产生一个附加的“反转目录”，可以让搜索更快。-k设置Cscope为“kernel”模式--Cscope不会到/usr/include去搜寻头文件，即使你的项目中的源代码包含了这些头文件。

On my 900 MHz Pentium III system (with a standard IDE disk), parsing this subset of the Linux source takes only 12 seconds, and results in 3 files (cscope.out, cscope.in.out, and cscope.po.out) that take up a total of 25 megabytes.

在我的900 MHz Pentiun III机子上，Cscope遍历这些linux内核源码用了12秒，产生了3个文件（cscope.out, cscope.in.out, cscope.po.out），这些文件（也就是cscope数据库）占据了25MB空间。

...剩下的不写了，很简单。

5.Using the database. If you like to use vim or emacs/xemacs, I recommend that you learn how to run Cscope within one of these editors, which will allow you to run searches easily within your editor. We have a tutorial for Vim, and emacs users will of course be clever enough to figure everything out from the helpful comments in the cscope/contrib/xcscope/ directory of the Cscope distribution.

Otherwise, you can use the standalone Cscope curses-based GUI, which lets you run searches, then launch your favorite editor (i.e., whatever $EDITOR is set to in your environment, or 'vi' by default) to open on the exact line of the search result.

If you use the standalone Cscope browser, make sure to invoke it via

cscope -d This tells Cscope not to regenerate the database. Otherwise you'll have to wait while Cscope checks for modified files, which can take a while for large projects, even when no files have changed. If you accidentally run 'cscope', without any flags, you will also cause the database to be recreated from scratch without the fast index or kernel modes being used, so you'll probably need to rerun your original cscope command above to correctly recreate the database.

6. Regenerating the database when the source code changes.

   If there are new files in your project, rerun your 'find' command to update cscope.files if you're using it.

   Then simply invoke cscope the same way (and in the same directory) as you did to generate the database initially (i.e., cscope -b -q -k).