在常规的使用ctags生成tag标签文件实现跳转的方式下,每次需要更新tags文件时都需要手工运行 ctags -R 生成当前项目所有源文件对应的tag标签文件。

当工程文件多、文件更新频繁时,上述生成tags文件的方法显得笨拙、低效。

得益于 Vim 8 提供的异步机制,vim插件vim-gutentags能够自动异步生成 tags 文件,当检测到同一个工程下面的文件有修改时,gutentags能自动增量更新对应工程的 tags 文件,而不用全部重新生成tags文件,是一个非常高效的tags生成工具。

1.1 软件依赖

vim-gutentags的本质仍然是使用ctags生成tag标签来实现函数跳转等功能,只是在ctags的基础上进行了封装和简化(具体封装方式在后文有简单分析),方便用户在vim中使用。

由于vim-gutentags依赖ctags工具,因此在使用vim-gutentags插件的系统中必须安装ctags软件,否则会报错”Excutable ‘ctags’ can’t be found.”。

vim-gutentags

关于ctags的介绍和安装方法,可以参考vim教程网上的文章Vim使用ctags实现函数跳转

其次,vim-gutentags需要在vim8.0以上版本才能正常工作,因为vim-gutentags实现的是增量更新tags的方式,依赖于vim8提供的异步机制。

在低于vim8.0的版本是运行vim-gutentags插件,会报错”this plugin requires the job API from Vim8 or Neovim”。

关于vim8的编译和安装,可以参考vim教程网上的文章vim安装教程

1.2 gutentags安装方法

本文介绍使用插件管理器vim-plug安装vim-gutentags插件。

在配置文件 ~/.vimrc 中增加配置项 Plug 'ludovicchabant/vim-gutentags' 后再在vim命令行模式下执行命令 :PlugInstall 即可完成vim-gutentags插件的安装。

二、vim-gutentags配置介绍和原理分析

vim-gutentags插件的基本工作原理可以这么理解:首先确定vim当前打开的文件是否需要自动生成tags标签,若需要则通过某种方式确定tag文件的路径,再基于tag标签文件完成函数跳转、结构体定义跳转等功能。

因此,vim-gutentags需要确定是否需要生成tags标签文件,又需要告诉ctags软件自身生成的tags文件的具体路径信息 (因为从Vim使用ctags实现函数跳转一文已知,默认情况下,生成的tags文件必须在vim运行的当前目录才能在vim里面正确跳转)。

2.1 gutentags配置

为了提供上述信息给vim-gutentags,安装完gutentags后,需要在vim配置文件中增加以下必要的配置项。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
" gutentags搜索工程目录的标志,碰到这些文件/目录名就停止向上一级目录递归 "
let g:gutentags_project_root = ['.root', '.svn', '.git', '.project']

" 所生成的数据文件的名称 "
let g:gutentags_ctags_tagfile = '.tags'

" 将自动生成的 tags 文件全部放入 ~/.cache/tags 目录中,避免污染工程目录 "
let s:vim_tags = expand('~/.cache/tags')
let g:gutentags_cache_dir = s:vim_tags
" 检测 ~/.cache/tags 不存在就新建 "
if !isdirectory(s:vim_tags)
silent! call mkdir(s:vim_tags, 'p')
endif

" 配置 ctags 的参数 "
let g:gutentags_ctags_extra_args = ['--fields=+niazS', '--extra=+q']
let g:gutentags_ctags_extra_args += ['--c++-kinds=+pxI']
let g:gutentags_ctags_extra_args += ['--c-kinds=+px']
  • 变量 gutentags_project_root 是vim-gutentags提供的用于搜索工程目录的标志,gutentags插件启动后,会从文件当前路径递归往上查找 gutentags_project_root 中指定的文件或目录名,直到第一次找到对应目标文件或目录名停止。若没有找到 gutentags_project_root 变量指定的文件或目录名,则gutentags不会生成tag文件。

  • 变量 gutentags_ctags_tagfilegutentags_cache_dir 分别用于告诉ctags要使用的tag文件目录tag文件名后缀,tag文件名的生成规则默认是根据生成tag文件的工程绝对路径按 - 分割而成。

  • 变量 gutentags_ctags_extra_args 用于配置ctags生成tag标签的参数,具体参数含义可参考文章ctags参数介绍

所以,上面的gutentags配置指定了从当前路径向上递归查找是否有 .root.svn.git.project 等标志性文件来确定当前文档所属的工程目录;而ctags要使用的tag标签文件的路径为 ~/.cache/tags,文件后缀为 .tags

ctags 软件需要使用命令 :set tags+=tags文件路径 显式地指定tag文件路径,从文件 ~/plugged/vim-gutentags/autoload/gutentags/ctags.vim 可以看出,gutentags执行了命令 setlocal tags+= 来添加变量 gutentags_ctags_tagfile 指定的tag文件到局部 tags 搜索列表中。
vim-gutentags

2.2 gutentags示例

安装了gutentags并且进行了上面的设置后,平时打开vim编辑文件基本感觉不到 tags 文件的生成过程了,只要文件修改过,gutentags 都在后台默默分析是否需要更新数据文件,还会帮你:setlocal tags+=… 添加到局部 tags 搜索列表中。得益于 Vim 8 的异步机制,你可以任意随时使用 ctags 相关功能,并且数据库都是最新的。

就像下面的vim视频教程一样,假设已经在vim配置文件中添加了上面的配置项,在当前目录新建文件 .project 后再打开当前目录下的任意文件,再退出vim后可以看到,gutentags已经为当前目录生成了tags文件 ~/.cache/tags/home-vim-vim.ink-libevent-.tags

vim-gutentags

需要注意的是,gutentags 需要靠上面定义的 gutentags_project_root 判断文件所在的工程,如果一个文件没有保存在包含 .git.svn.root等 定义在 gutentags_project_root 中的文件,gutentags就不会为该文件生成 tags。

想要避免的话,你可以在你的野文件目录中放一个名字为 .root 的空白文件,主动告诉 gutentags 这里就是工程目录。

2.3 基于gutentags实现跳转

在为当前目录生成tags文件后,可以通过按键 Ctrl + ] 跳转到对应的定义位置,再使用命令 Ctrl + o 回退到原来的位置。关于跳转的具体应用,可以参考Vim使用ctags实现函数跳转

vim函数跳转

另外,建议多使用 Ctrl + W + ] 用新窗口打开并查看光标下符号的定义,或者 Ctrl -W } 使用 preview 窗口预览光标下符号的定义。

嗯,扫一扫就可以找到小女子我啦~