GlusterFS, cscope, and vim (oh my!)

I’m generally pretty old-school when it comes to programming tools. Many IDE features either leave me cold (auto-complete) or seem actively harmful to understanding the code as it really is (“project” hierarchies). I do like syntax highlighting, though I’d probably like it just as much if the only thing it did was show comments in a distinct color. I suppose I wouldn’t mind some support e.g. for renaming a variable and having all references change without also changing references to a same-named variable somewhere else . . . but I’m not willing to put up with all the other BS just for that.

The one feature that I do find indispensable is cross-referencing. In a codebase as large as GlusterFS (over 00K lines and still growing quite rapidly) being able to jump to a function/structure definition or references is a pretty major productivity boost. Just do the math. When I’m exploring code for a review or in preparation for some change I plan to make, I often traverse chains of three to five calls at a rate of one such chain per minute. Every second counts. If the old grep/open/goto-line dance takes me only five seconds, that’s still a third of my total time plus additional cognitive disruption. If it takes me only a second each time, that’s pretty huge.

For a while I used Source Navigator but got tired of its insane multi-window and history behavior. For a longer while I used kscope, but then it died with KDE4. I tried exploring alternatives for a while, until Larry Stewart suggested I use cscope with the vim bindings. I tried it, and have never looked back. Here’s a really quick overview of how it works for me and will hopefully work for you.

To install, you need to do two things. First, you need to install cscope. That’s usually just a yum or apt-get install away, so no big deal there. Then you need to put cscope_maps.vim in your ~/.vim/plugin directory. That’s it.

To prepare cscope+vim for use in a particular directory, you also need to do two things – generate a list of files, then generate a list of tags (bookmarks) from that. I use the following two commands

$ find . -name '*.[ch]' > cscope.files
$ cscope -b

This is such a common operation that I even created a git checkout hook to do it automatically. Similarly, refreshing tags in the middle of an editing session is so common that you might want to consider binding this combination to a simple key sequence within vim.

:!cscope -b
:cs reset

The first of those calls out to regenerate the cscope.out file that contains all of your tags. It probably only works if you always start your editing session at the top of the source tree (so it can find cscope.files properly). The second command tells the vim part of the combo to re-read the new tags file.

Using cscope from this point on is extremely simple. The most common commands are prefixed with C-\ (control backslash) and implicitly take the identifier under the cursor as an argument. Some others start with with :cs instead (like reset above). The most common ones I use are as follows.

• “C-\ g” jumps to the definition of a function or structure.
• “C-\ c” shows a list of callers for a function, and you can jump to any one of those from the list.
• “C-\ s” shows a list of references for an identifier – usually a function but could also be a structure or variable. This is often necessary in GlusterFS code to find functions which aren’t called but are passed to STACK_WIND as callbacks.
• “C-t” undoes the last C-\ command, leaving you where before.
• “:cs f e <string>” does a regex search through all of the files in cscope.files for <string>. There’s a bit of glitchiness in quoting/escaping/parsing the string, so I generally find it’s best to enclose any possibly-special characters in [] to have them treated as character sets. For example, instead of foo->bar I’ll usually use foo[-][>]bar.
• “:cs f f <string>” will show you a list of files in cscope.files matching <pattern>. Actually I just noticed it while composing this article, and should use it more myself.
• “:cs help” will show you some of the other options.

This setup generally works extremely well for me, but there are a few things particular to the GlusterFS code that don’t work quite as well as they could. For one thing, some symbols just don’t seem to get tagged. I suspect that it has something to do with macros – we overuse those terribly, and the problem always seems to be in files where the abuse is particularly bad – but I’ve never quite nailed it down. Sometimes you just have to do a string/regex search instead. Also, jumping to a type definition with “C-\ g” will often take you to a typedef, and then you have to do it again to get to the real structure definition. I wish there was a way to tell cscope that it should jump through typedefs automatically, but I don’t know of one and I doubt I’ll ever have enough time to patch it myself.

If you find yourself spending too much time on the mechanics of navigating GlusterFS code (or for that matter anything else), please give this technique a try. I’m sure there’s an emacs equivalent, but I don’t know the details off the top of my head; maybe some kind soul will provide some hints as a comment. Happy hacking.