使用Cscope阅读Linux源码

原文出处：刘建文 | 学术半·IT歌·文（http://arttech.us）

cscope是神马

cscope 是什么东东？先看看官方定义：

“cscope is an interactive, screen-oriented tool that allows the user to browse through C source files for specified elements of code.”

简译并补充为：“cscope 是一支面向屏幕的（与面向行相对）交互式C源代码浏览程序。它可以对C程序源代码的元素（例如各种标号：变量，宏以及函数调用等）进行索引，提供简单的字符查询界面，用户可根据【元素名】对其定义及引用进行查询查看。”

以上是cscope的一个严格的完整定义，此定义表明cscope有两个主要功能，第一是对C源码文件进行［符号索引］；第二是提供简单的查询接口。如果你一般只使用像VIM这样的高级工具编辑和阅读源码，完全可把cscope理解成生成源码［符号引用数据库］的工具。

一些重要的概念

源文件（source files）

源文件指被cscope的C源码文件，源文件的来源有几个，

• 第一，默认当前目录（包括子目录，使用-R参数）；
• 第二，命令行输入；
• 第三，源码文件列表（见下面定义）；
• 第四，包含目录。

这四种文件源的简单理解是，目录是一集文件；命令行是一个或几个文件；包含目录是文件内的文件；文件列表是给cscope一张文件清单，让cscope自己去找，是简接的自定文件。

既然搜索的文件来源有多种，当给cscope提供了多种来源时，搜索源码的次序也是以上次序。

包含目录（include dir）

对于任何一个C源码包含文件，如果它不是绝对路经（以反斜杠开始），并且不在［命令行输入］中或［源码文件列表］中时，cscope将搜索［cscope 包含目录］，此目录由命令行参数-I或环境变量$INCDIR指定。

源码文件列表（list file）cscope.files

源码文件列表功能提高了cscope的灵活性，它让cscope不限死搜索一集相近的文件，也不限死源文件是C源码。默认的源码文件列表是当前目录的 cscope.files，也可以通过-i参数自定。

符号引用数据库 cscope.out

cscope的索引输出是一个叫符号交叉引用文件（symble cross-reference file）——cscope.out，名字内涵较深刻，但有点学术味，不太好记。此文简化为［符号引用数据库］。此数据库格式如何，查询原理怎样，待究，数据库名可使用参数-f自定。

使用cscope阅读Linux的核心源码

1.确定项目源码位置，例如/home/kemin/linux-2.6.31；

2.选定保存一个cscope数据（包括［源码列表文件］和［符号引用数据库］）位置，例如/home/kemin/cscope/linux_no_driver；对于相对固定的大项目，有必要这样做。

3.如有必要，可先生成被Cscope索引的［源码列表文件］，触发Cscope针对这些文件进行索引，而不是对当前目录树进行全面索引。有两种情况有必要这样做：

第一，有选择地对项目源码文件进行扫描，过滤掉不感兴趣的代码；例如过滤掉Linux源码目录下的文档（doc）、脚本（script）和驱动程序源码文件（driver）等：

   LNX=/home/kemin/linux-2.6.31

   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

第二，项目为非C语言项目，文件类型是.c, .h, .y, or .l 以外的。例如为java项目建立索引：

$ cd / ; find /my/project/dir -name '*.java' >/my/cscope/dir/cscope.files

注意 : 以上两脚本都是首先转到根目录（cd /）进行操作的，这样做是为让生成的［符号引用数据库］对生成目录没有依赖，编辑程序可以任意目录下运行，只要设定环境变量$CSCOPE_DB指向［符号引用数据库］即可：

CSCOPE_DB=/foo/cscope.out; export CSCOPE_DB

特别地，如果过虑条件复杂，find很难编写，你可以直接编辑cscope.files文件。

4.生成［符号引用数据库］cscope.out

如果是一个简单的测试项目，则可以直接在源码目录执行：cscope 或 cscope -R然后调用编辑程序进行浏览，否则像本实验那样，转到指定目录进行操作：

$ cd /home/kemin/cscope/linux_no_driver # 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).

最后生成三个文件：results in 3 files (cscope.out, cscope.in.out, and cscope.po.out)

5.cscope的使用

cscope 自带一个基于字符的查询界面（Cscope GUI），当你在源码目录直接执行cscope时（无任何参数），Cscope 的默认行为是索引当前目录或cscope.files指定的源码文件，生成［符号引用数据库］cscope.out（如果数据库已经存在，则更新它），并调出Cscope GUI，选中查询结果则调出由指定编辑程序（由$EDITOR指定，或者默认的vi）进行查看。-b参数只生成数据库，-d参数则只调出Cscope GUI，不进行数据库更新。

使用Cscope GUI是很原始的，最好配合一些高级的编辑程序使用，下面说说VIM。

配合VIM使用

1. 确定VIM版本，6.X以上并且编译时开启了对Cscope 的支持，编译开关是--enable-cscope

2. 下载并安装脚本文件cscope_maps.vim（http://cscope.sourceforge.net/cscope_maps.vim ），一般情况下只要把该拷贝到VIM安装目录的下子plugin目录即可（可使用VIM命令:scriptename查看）。

3. 光标搜索

Put the cursor over a C symbol ，

• 当前窗口搜索
  • Type "CTRL-/ s" (Control-backslash, then just 's') ，the '/' key is right next to the ']' key, which is used for ctags searches
  • hit "CTRL-t" to jump back
• 分割窗口搜索
  • 水平分割： "CTRL-spacebar s"
  • 垂直分割：CTRL-spacebar CTRL-spacebar s

4. 传统命令行搜索

• ":cscope find symbol foo" (or, more tersely, ":cs f s foo").
• To do the horizontal split version, use ":scscope" (or just ":scs")

5. 四种常用的搜索目标类型

• 's', for 'find all uses of symbol X'.
• 'g' finds the global definition(s) of a symbol,
• 'c' finds all calls to a function,
• 'f' opens the filename under the cursor

6.6 VIM多窗口功能使用

• 在多个窗口间切换： 'CTRL-W w' (or CTRL-W arrow key, or CTRL-W h/j/k/l for left/up/down/right),
• 关闭当前窗口： 'CTRL-W c' (or good old ':q'),
• 关闭其它窗口： 'CTRL-W o',
• 分割当前窗口： 'CTRL-W s' (or 'CTRL-W v' for a vertical split),
• 在新窗口打一个文件： ':spl[it] filename']

参考

• 肯塔基大学CS585课程讲义：http://www.cs.uky.edu/~raphael/courses/CS585/setup.html
• http://cscope.sourceforge.net/