Make Vim and Ctag play nice together

The classic tutorial of Ctags + Vim will go something like:

• - Install exuberant ctags


• - Generate tags for your project


• - Also install the tag list plugin


• - Use ^] and ^T to jump around the code

In this post I will try to go a little further and show how I manage tags in vim for real and large C projects.

Note that I mostly program in C (not C++), Ruby and Bash so I cannot guarantee my method works for all languages. In special Ctags has problems supporting C++. On the other side I have worked in small projects in Java and Python and I had no problems navigating them with my method.

Pre requisites

The following instructions were tested on a Linux machine installed using Kubuntu 8.10, 9.04 and 9.10. The first step is of course to make sure you have installed Vim and exuberant-ctags in you machine:

sudo aptitude install vim-ruby vim-scripts vim-common exuberant-ctags

If you are new to Vim then you should take some time to set your minimal configuration. You may follow mine if you want link.

Generate system wide ctags

All large projects will use at some point external libraries. My C projects usually use the Linux/FreeBSD system calls, SDL, OpenGL, libavcodec and libavformat among others.

To be able to jump to these libraries we must generate tags for each of them. I usually generate them inside my vim directory but you may create them in a system wide folder.

This is extremely useful to easily find out the members of libavcodec large structs or to quickly find out what are the arguments of SDL functions or system calls.

Ctags for Linux System Calls

mkdir -p ~/.vim/tags
sudo aptitude install linux-headers-`uname -r`
ctags -R -f ~/.vim/tags/kerneltags /usr/src/linux-headers-`uname -r`

Ctags for Ruby core and gem libraries

mkdir -p ~/.vim/tags
ctags -R -f ~/.vim/tags/rbtags /usr/lib/ruby

Ctags Java libraries

# For the java tags to work you need to install java source package.
# In Kubuntu/Ubuntu follow these instructions:
mkdir -p ~/.vim/tags
sudo aptitude install sun-java6-source
sudo mkdir -p /usr/lib/jvm/java-6-sun/src
sudo unzip -d /usr/lib/jvm/java-6-sun/ /usr/lib/jvm/java-6-sun/src.zip
ctags -R -f ~/.vim/tags/javatags /usr/lib/jvm/java-6-sun/src

At this you should be able to create tags for all the libraries you use in your projects. Simply get the source code or development packages of the library and run ctags on the folder that contains the source code and save the tags in a file you can access.

TODO: I really need to research what are the best ctags flags for each language in order to generate the most information possible per tag.

Updating your system wide ctags

Here we have three options:

• Update your system/library tags manually each time you upgrade them


• Use a cron job to update them every certain period of time (e.g. once a week).
• 
  
• Use incrontab to monitor changes in the system/library folders and automatically update the tags every time these folders change.

Personally I use the cron job method and for some libraries that I update often (e.g. libavcodec from subversion) I manually generate the tags soon after I update the library.

I found about incrontab just recently and I think will be the best way to update system wide tags. It behaves mostly like crontab but instead of triggering actions based on time periods it triggers by file system events like file change, move, save, etc. It should be easy to monitor the folders containing the libraries of interest and regenerate the tags for each library based on change events in the folder contents. The tricky part would be to determine what file system event we must listen to decide if we should regenerate or not the tags.

Generating ctags for your own libraries/projects

Now we need to generate tags for projects/libraries we are developing at the moment. These projects are constantly changing so we need to update them as soon as possible.

This is a common problem that lot's of people solve in different ways. See for example these links:

• Vim auto-generate ctags


• Vim+ctags tips and tricks


• TagsParser : Automatic tagfile updating and tag viewer


• vim with ctags for multi-level directory hierarchy


• http://vim.wikia.com/wiki/Tags_generation_for_current_file


• Auto tags by project.vim

Most methods I found do the same more or less: they set some auto commands to autogenerate tag files when a file is edited and set the search path in a way it can find the generated tags.

I used to have some autocommands in vim to generate tags every time I modified a file in a project. Unfortunately I never figured out how to generate a single tags file per project/library. I always ended with a global tag file for all projects or a single tag file per folder.

Another methods worked by adding tags generation commands to the build system so the tags get generated when we recompile the project (e.g. Makefile, Ant, CMake) and others simply created scripts per project and executed them manually from the project root directory or within vim using a key map.

Since I use the Project.vim plugin it is natural for me to use it to generate the tags files as it is done here. My method is a lot different in that I do not use a Makefile to generate the tags and I only re-generate them when a file has been edited, not every time we open a file.

Auto-generating Ctags Using the Project.vim plugin

Anyone that has used the Project.vim plugin is familiar with the snippet shown below:

 myproj=<src-path> in=in.vim out=out.vim CD=<src-path> {
   CMakeLists.txt
   in.vim
   out.vim
   include----------------- 
   src---------------------
   test--------------------
   tools-------------------
 }

This corresponds to a project entry called "myproj" with root directory set to "src-path". Here the important parts are the "in", "out" and "CD" parameters.

The "CD" parameter makes sure that you are at the project root directory when editing a file from that project. This is useful to have a single tags file per project.

The "in" and "out" parameters are simple vim scripts. The "in" script is executed when opening a file from the project and the "out" script when leaving the file. In these scripts is where I set/unset the autocommands that take care of generating the tags files per project.

Every time I create a new project using the Project.vim plugin I also create these in.vim and out.vim scripts:

in.vim

" let ctags_cmd='/usr/local/bin/exctags'   " Use this one in FreeBSD

let ctags_cmd='/usr/bin/ctags'             " Use this one in Linux

let proj_path = escape(getcwd(), ' ')

let _ctagargs_ = " --fields=+iaS --extra=+q -R "

let _ctag_ = ctags_cmd . _ctagargs_ . " -f " . proj_path . "/.tags " . proj_path

au BufWritePost <buffer> call system(_ctag_)

out.vim

au! * <buffer>

Now every time you open a file from a project an autocommand will be created for that file that will regenerate tags for the whole project every time the file is saved. The generated tags file is always in the root directory of the project. You may prefer to use the "--append" switch of ctags to generate tags for the current file only but I personally prefer regenerating the tags of the whole project every time.

When you leave the file the autocommand is removed in the out.vim script. If we do not remove the autocommand, it will be created every time we enter the file that results in a lot of autocommands around. I am not really sure if this can cause problems but is better go on the safe side.

Now the last piece of the puzzle is how to tell Vim where to search for the tags.

Tell Vim where to search for tags

To find the per project tags we can simply add this to our vimrc file:

set tags=./.tags;${HOME}

This simple command tells vim to search tag files from the current directory backwards up to our $HOME directory. Since we are sure that we are always at the projects root directory where the tags file is automatically generated we can be sure that vim will always find the tag we are looking for.

There are some system wide tags that we want to always load depending on the language we are developing. For example when I develop in C I would like to have the kernel system calls tag file (that we generated before) or when developing in Ruby/Java I expect to have these languages core tags loaded too.

To do this I load all system wide libraries based on filetype using these commands in my vimrc file:

au BufRead,BufNewFile *.rb setlocal tags+=~/.vim/tags/rbtags

au BufRead,BufNewFile *.cpp,*.h,*.c setlocal tags+=~/.vim/tags/kerneltags

au BufRead,BufNewFile *.rl,*.def setlocal tags+=~/.vim/tags/kerneltags

au BufRead,BufNewFile *.py setlocal tags+=~/.vim/tags/pytags

au BufRead,BufNewFile *.java setlocal tags+=~/.vim/tags/javatags

What these commands do is to load the system wide tag files we generated before depending on the file type. For example when editing a ruby file it loads the Ruby tags file.

We must note that the commands only apply to the current file being edited (e.g. setlocal), not all the files in the project and that we are adding the tags file not replacing the current one (e.g. += ).

Finally how can we add other tag files to the project that are not from the project itself and not system wide?. For example my project requires external libraries like libavcodec and SDL so it would be nice to query the function and struct definitions of these libraries.

To do this I use the "in.vim" script of the Project.vim plugin like:

" let ctags_cmd='/usr/local/bin/exctags'   " Use this one in FreeBSD

let ctags_cmd='/usr/bin/ctags'             " Use this one in Linux

let proj_path = escape(getcwd(), ' ')

let _ctagargs_ = " --c++-kinds=+p --fields=+iaS --extra=+q -R "

let _ctag_ = ctags_cmd . _ctagargs_ . " -f " . proj_path . "/.tags " . proj_path

au BufWritePost <buffer> call system(_ctag_)



" Add external library tag files

setlocal tags+=~/.vim/tags/sdltags

setlocal tags+=~/.vim/tags/ffmpegtags

This is exactly the same "in.vim" script as above with two added lines that include the libavcodec (FFMpeg) and SDL library tags files to the search path of vim for all files in the project. These files were of course generated before the same way we created the system wide tag files and updated via a cron job.

Once you setup this once you don't need to worry about this anymore until you reinstall your computer. The system wide libraries will be always updated if you configured the corresponding cron jobs and once a project is created it will always have the tags files updated and ready to query.

Setting up the TagList Plugin

No blog post about Vim+Ctags is complete without the mighty TagList plugin. To install this plugin go to http://vim-taglist.sourceforge.net/ and download the taglist_45.zip file. Then add it to your vim installation using the command:

unzip -d ~/.vim taglist_45.zip

Then add these commands to your vimrc file:

" let Tlist_Ctags_Cmd='/usr/local/bin/exctags'   " Use this one in FreeBSD

let Tlist_Ctags_Cmd='/usr/bin/ctags'             " Use this one in Linux

let Tlist_Auto_Open=0

let Tlist_Auto_Update=1

let Tlist_Use_Horiz_Window = 0

"let Tlist_Inc_Winwidth=0

"let Tlist_Show_One_File=1

let Tlist_Exist_OnlyWindow=1

let Tlist_Use_Right_Window = 1

let Tlist_Sort_Type="name"

let Tlist_Display_Prototype=0

let Tlist_Compact_Format=1 " Compact?

let Tlist_GainFocus_On_ToggleOpen=1

let Tlist_Display_Tag_Scope=1

let Tlist_Close_On_Select=1

let Tlist_Enable_Fold_Column=1

"let TList_WinWidth=25



" Map a F8 to the TlistToggle command for easy tags list access

nnoremap <silent> <F8> <ESC>:TlistToggle<CR>

Of course I recommend you to read the help file and set the configuration as it fits you better. With my configuration you can press to open the tags list window and when you press on a tag the windows automatically closes. This is specially useful on small screen laptops to allow more code visible all the time.