if_cscop.cnx

Vim 中文文档

*if_cscop.txt*  For Vim version 6.3.  最近更新：2004年6月


		  VIM REFERENCE MANUAL    by Andy Kahn
		(译者：lang2 http://vimcdoc.sf.net)

							*cscope* *Cscope*
本文档阐述如何使用 Vim 的 cscope 界面。

Cscope 是一个类似 ctags 的工具。 你可以把它想作是超过频的 ctags，因为它功能比
ctags 强大很多。 在 Vim 里，通过 cscope 查询结果来跳转就象跳转到其他的标签完
全一样; 它被保存在标签堆栈里。这样你就可以象使用 |tags| 一样在函数等等之间便捷
的跳转。

1. Cscope 简介			|cscope-intro|
2. Cscope 相关命令		|cscope-commands|
3. Cscope 选项			|cscope-options|
4. 如何在 Vim 中使用 cscope	|cscope-howtouse|
5. 缺陷				|cscope-limitations|
6. 建议的使用方法		|cscope-suggestions|
7. cscope 的获取等等信息	|cscope-info|

到目前为止 cscope 界面仅在 Unix 及 Win32 平台下有效。
{Vi does not have any of these commands}

==============================================================================
1. Cscope 简介						*cscope-intro*

下面的文本是摘自 cscope 的手册页:

				    -----

  Cscope 是一个交互式的屏幕下使用的工具，用来帮助你:

       无须在厚厚的程序清单中翻来翻去就可以认识一个 C 程序的工作原理。

       无须熟悉整个程序就可以知道清楚程序 bug 所要修改的代码位置。

       检查提议的改动 (如添加一个枚举值) 可能会产生的效果。

       验证所有的源文件都已经作了需要的修改；例如给某一个现存的函数添加
       一个参数。

       在所有相关的源文件中对一个全局变量改名。

       在所有相关的位置将一个常数改为一个预处理符号。

  它被设计用来回答一下的问题:
       什么地方用到了这个符号?
       这是在什么地方定义的?
       这个变量在哪里被赋值?
       这个全局符号的定义在那里?
       这个函数在源文件中的那个地方?
       那些函数调用了这个函数?
       这个函数调用了那些函数?
       信息 "out of space" 从哪来?
       这个源文件在整个目录结构中处于什么位置?
       哪些文件包含这个头文件?

  Cscope 在第一次被使用在指定的源文件时会建立一个符号的数据库。接下来被调
  用时，cscope 仅仅重建那些被改动或者新文件相关的数据库。那些没有被改动的
  文件相关的数据库会被直接复制使用。这是的重建数据库要比第一次运行快许多。

				    -----

当 cscope 被一般的调用时，你会得到一个全屏幕的选择窗口。你可以输入以上
问题中的一个。然而，一旦找到一个匹配你必须进入一个文本编辑器来查看和编辑
匹配的文本。你无法象在 vi 中使用 Ctrl-] 或 :tag 命令那样方便的跳转。

Vim 的 cscope 界面的工作原理是：先调用 cscope 的命令行界面，然后分析其
输出结果从而找到匹配处。最终结果是：cscope 查询结果就象一般的标签一样。
你可以使用一般的标签命令 (Ctrl-］ 或 :tag) 然后再用 Ctrl-T 回跳。
(note 不过，其实你不能简单的就使用 Ctrl-] 或 :tag 来跳转到标签。在那之前
你必须重新定义映射或设定一些选项值。下面的几节会告诉你如何正确的使用
cscope 界面)


==============================================================================
2. Cscope 相关命令					*cscope-commands*

		*:cscope* *:cs* *:scs* *:scscope* *E259* *E262* *E561* *E560*
所有命令都是通过主命令 ":cscope" 的子项完成的。主命令最短的缩写是 ":cs"。
":scscope" 完成同样的功能的同时还可以分割窗口 (缩写: "scs").

可用的子命令有:

			*E563* *E564* *E566* *E568* *E569* *E622* *E623*
			*E625* *E626* *E609*
    add   : 添加一个新的 cscope 数据库／连接。

	用法	:cs add {file|dir} [pre-path] [flags]

	    [pre-path] 用来通知 cscope 使用 -P [pre-path] 选项。

	    [flags] 可以用来给 cscope 传递额外的选项。

	例子 >
	    :cscope add /usr/local/cdb/cscope.out
	    :cscope add /projects/vim/cscope.out /usr/local/vim
	    :cscope add cscope.out /usr/local/vim -C
<
				      *cscope-find* *cs-find*
						*E565* *E567*
    find  : 查询 cscope。除了第 5 个之外的所有 cscope 查询功能都
	    可以使用。第 5 个是 "Change this grep pattern"。

	用法	:cs find {querytype} {name}

	    {querytype} 和 cscope 的控制台界面以及 nvi 缺省命令
	    都是一致的。

		0 或 s: 查找 C 符号
		1 或 g: 查找定义
		2 或 d: 查找本函数调用的函数
		3 或 c: 查找调用指定函数的函数
		4 或 t: 查找字符串
		6 或 e: 查找 egrep 模式
		7 或 f: 查找文件
		8 或 i: 查找包含指定文件的文件

	例如 >
	    :cscope find c vim_free
	    :cscope find 3 vim_free
<
	    这两个例子执行同样的查询。 >

	    :cscope find 0 DEFAULT_TERM
<
	    在 Vim 5.1 的源代码内执行以上的命令得到一下的结果:

	    Cscope tag: DEFAULT_TERM
	       #   line  filename / context / line
	       1   1009  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"amiga"
	       2   1013  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"win32"
	       3   1017  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"pcterm"
	       4   1021  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"ansi"
	       5   1025  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"vt52"
	       6   1029  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"os2ansi"
	       7   1033  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"ansi"
	       8   1037  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 # undef DEFAULT_TERM
	       9   1038  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"beos-ansi"
	      10   1042  vim-5.1-gtk/src/term.c <<GLOBAL>>
			 #define DEFAULT_TERM (char_u *)"mac-ansi"
	      11   1335  vim-5.1-gtk/src/term.c <<set_termname>>
			 term = DEFAULT_TERM;
	      12   1459  vim-5.1-gtk/src/term.c <<set_termname>>
			 if (STRCMP(term, DEFAULT_TERM))
	      13   1826  vim-5.1-gtk/src/term.c <<termcapinit>>
			 term = DEFAULT_TERM;
	      14   1833  vim-5.1-gtk/src/term.c <<termcapinit>>
			 term = DEFAULT_TERM;
	      15   3635  vim-5.1-gtk/src/term.c <<update_tcap>>
			 p = find_builtin_term(DEFAULT_TERM);
	    Enter nr of choice (<CR> to abort):

	    这样的输出显示了几类信息:
	    1. 标签号码 (例子中有 15 个).
	    2. 标签所在的行号.
	    3. 标签所在文件的文件名.
	    4. 标签的上下文 (如：全局或函数名).
	    5. 标签所在行的文本.

    help  : 显示一个简单的帮助。

	    用法    :cs help

						*E260* *E261*
    kill  : 终止一个 cscope 连接 (或终止所有 cscope 连接).

	    用法   :cs kill {num|partial_name}

	    要终止一个连接，需要给处连接号或者部分的连接名称。部分名称可以
	    是数据库文件路径的任何一部分。所以要当心使用这个功能！

	    如果给定的连接号是 -1，那么 所 有 的 cscope 连接都会被终止。

    reset : 重新初始化所有连接。

	    用法    :cs reset

    show  : 显示当前的连接。

	    用法    :cs show

							*:cstag* *E257* *E562*
如果你同时使用 cscope 和 ctags, |:cstag| 允许你在跳转前对两者都在查询。
例如，你可以选择先查询 cscope 数据库，如果无法找到匹配，再查询标签文件。
这种做法的次序可以通过 |csto| 的值来调整。参见 |cscope-options|。

|:cstag| 在搜索 cscope 数据库时执行和 ":cs find g" 一样的操作。

|:cstag| 在搜索标签文件时执行和 |:tjump| 一样的操作。


==============================================================================
3. Cscope 选项						*cscope-options*

所有 cscope 有关的选项都可以用 |:set| 命令来设定。比较理想的做法是将这些
设定添加到你的启动文件中 (如：.vimrc)。某些 cscope 选项仅仅在 |.vimrc|
文件内才有效。在 vim 启动之后再设定它们的值没有任何效果！

							*cscopeprg* *csprg*
'cscopeprg' 指定用来执行 cscope 的命令。缺省值是 "cscope"。例如: >
	:set csprg=/usr/local/bin/cscope
<