Wednesday, August 08, 2007

Vim Tips for Java #2: Using exuberant-ctags

ctags is a great tool for programmers. It creates an index to your source code to allow you to trawl through them for cross referencing. While the way it works doesn't look as snazzy as nicely formatted javadoc output like Netbeans, it does its job well enough for you to read up a field or method definition whenever you need it. You'll need to install exuberant-ctags separately, which you can find on its website.

A requirement of using ctags, is that you'll need to have the Java source code available for ctags to parse them into a searchable index file for vim. It's usually located in your Java distribution at $JAVA_HOME/ Unzip the file, and in my case I extract it into the $JAVA_HOME/share directory I've created. Then run exuberant-ctags:

exuberant-ctags -R --language-force=java -f.tags /opt/sun-jdk-

This command generates a '.tags' index file in my home directory. The next thing to do is to allow vim to be able to locate and use the index file. Add the following line into your .vimrc:

autocommand FileType java set tags=~/.tags

This should now allow you to jump to any definition in the Java API, whenever you need to look it up from your code. To test this, create a Java file and put some code in it:

public class TestClass {
String s = new String();

Move your cursor under to the word 'String' and press ctrl-]. Voila, you should now be reading into the source of.. not just yet, it is not java.lang.String! Most probably it is showing you some other classes that has a String object in its field, which is probably not what you are looking for. To cycle through the remaining matches, use the command mode instruction ':ts' to go through the list of matching tags and select the right item you want.

You might also want to be familiarized with the navigation keystrokes, by doing a ':help' on ':ta', ':ts', 'CTRL-L', 'CTRL-]', which may be useful.

A few dissatisfactions that I still have with this method:

1) It doesn't allow me to read the embedded javadocs in code as html. It will be pretty cool if this feature can be linked to lynx and shown in a window within vim, but I'm not certain if it is possible;

2) I don't believe that searching through all the miscellaneous fields of other classes is the best way of using ctags. There may be something that I have not mastered that permits me to fully utilize the power of ctags yet.

I'll be looking further to see if I can learn more tips on using ctags, but in the meantime, if anybody have any suggestions for improvement, I'll appreciate if can leave a suggestion, thanks!

If you like reading this, you may also enjoy:


Unknown said...

The command for generating ctag .tas file does not work on my powerbook (Tiger).

And I'm having problems finding the source..all I kind find id source.jar.

Finally using ctrl-] is not possible on the mac since the ] is generated with the option+9 buttons and when used with the ctrl button just gives you a 9.

That said..thanks for all the good input on using vim with java. I have had much use with your comments.

Unknown said...

Hi consiglieri,

Sorry to hear that the command doesn't work for you, perhaps you can post the output of it so that I can see if I (or anybody else who reads the blog) can help you with the issue?

I think in some versions of the JDK provided, src.jar is where the source code is resided. You'll have to extract that out somewhere, via 'jar xvf source.jar' before running ctags. The jar command should be available bundled together in the 'bin' directory of the java distribution.

Unfortunately I can't give you more information on using in on a Mac, cos I'm not familiar with it myself. If there is any Mac users out there who can give assistance, that'll probably be appreciated.

In any case, thanks for letting me know that my tips have been helpful. It's always nice to know that I'm writing something useful that other's can pick up. Cheers for that, and hope that you'll be checking back in the future for more tips!

Anonymous said...
This comment has been removed by the author.
Anonymous said...


on a mac, src.jar is only provided for 1.3 and 1.4, not 1.5 (the default) and 1.6 (available as a developer preview). No big deal, though...

I'm downloading the source for sun's jdk 6 right now (, which should suffice - can't tell yet.

Also make sure that you're using exuberant ctags, not /usr/bin/ctags, which is not very useful to say the least. exuberant ctags can be obtained from macports, fink (i think) and gentoo/alt.

Anonymous said...

Okay, fresh start: What *does* help is this:

Go to (you'll need a free account) -> Downloads -> Java

There's two important downloads there (apart from a running version of java 1.6):

* J2SE 5.0 Release 5 Developer Documentation

and then under Java SE 6.0 [...]:

* Developer Documentation

That so-called documentation includes the src.jar you're looking for, for java 1.5 and 1.6.

Unknown said...

Hi Pipping,

Thanks for the clarifications :) I'm sure it's going to be helpful to all Mac developers, cheers for that and thanks for your input!

Robert Mark Bram said...

Hi Vincent,

Thank you for your article - I hope to get this working! But my output doesn't look right.

On Cygin, I ran:
ctags -f.tags --language-force=java -R /c/Program\ Files/Java/jdk1.6.0_14/src

And this is all I got:
Thu Jul 23 - 05:37 PM > cat .tags
!_TAG_FILE_FORMAT 2 /extended format; --format=1 will not append ;" to lines/
!_TAG_FILE_SORTED 1 /0=unsorted, 1=sorted, 2=foldcase/
!_TAG_PROGRAM_AUTHOR Darren Hiebert /
!_TAG_PROGRAM_NAME Exuberant Ctags //
!_TAG_PROGRAM_URL /official site/

The .java files are all there, in /c/Program\ Files/Java/jdk1.6.0_14/src.

Any clue?


Unknown said...

Hi Rob,

Looks like it's executed fine, but nothing is parsed.

Maybe if you pass the -V (verbose) flag, it may tell you what it's doing, and maybe what is going wrong?

Robert Mark Bram said...

OK, after much cursing and some help from vim_use Google group I sorted out my issues.

Since I am working with Cygwin on Windows and using the Windows version of exuberant ctags, I need to a) provide Windows paths to ctags and b) ensure that the generated tags files do not contain absolute paths (which will be Windows paths that ctags in vim on Cygwin won't understand).

So I run my ctags commands as follows (from Cygwin):

cd 'C:\rob\apps\java\jdksrc\jdk6.14'
ctags -V -f '.tags' --language-force=java -R
cd 'C:\rob\work\projects\nd\ford\tp07\rtb\src\java'
ctags -V -f '.tags' --language-force=java -R

And add the following to my .vimrc - where I can use the Cygwin symbolic links I set up.

autocmd FileType java set tags=/apps/java/jdksrc/jdk6.14/.tags,/wd/src/java/.tags

Note that I had to use autocmd here, not autocommand - the latter was giving me an error in vim.

I have to say that tags is ok - but hard to use when there are many matches i.e. you have to cycle around till you find the right match.

I now need to look through the techniques for browsing tags:

One more question I have though - the .tags files contain the javadocs for the matches.. are the javadocs uses somehow?

Thanks again Vincent - great post!


Robert Mark Bram said...

Actually I needed to compile my own Cygwin version of Exuberant Ctags from source to get ctags (and the taglist plugin) to work correctly.

This is what I did today in Cygwin.

Untar and compile Exuberant Ctags source.

mkdir /apps/ctags58_fromCygwinCompiledSource
tar -xzf /files/oginals/Cygwin/ctags/ctags_source_-5.8.tar.gz -C /apps/ctags58_fromCygwinCompiledSource/
cd /apps/ctags58_fromCygwinCompiledSource/
./configure && make install

I changed my path to put ctags58_fromCygwinCompiledSource in there.

Now generate tags

rm -rf /apps/java/jdksrc/jdk6.14
mkdir -p /apps/java/jdksrc/jdk6.14
unzip /ProgramFiles/Java/jdk1.6.0_14/ -d /apps/java/jdksrc/jdk6.14/
ctags -V -f '/apps/java/jdksrc/jdk6.14/.tags' --language-force=java -R /apps/java/jdksrc/jdk6.14/

ctags -V -f '/work/projects/nd/ford/tp07/rtb/src/java/.tags' --language-force=java -R /work/projects/nd/ford/tp07/rtb/src/java

And add this to my .vimrc:

autocmd FileType java set tags=/apps/java/jdksrc/jdk6.14/.tags,/work/projects/nd/ford/tp07/rtb/src/java/.tags

Unknown said...

Thanks Rob!

I think your detailed input will help other cygwin users immensely as well. I'm surprised that you needed to full recompile to get it to work though - that sounds like a bit of hassle to me, but I'm glad you've managed to get it to work, which is what's important.

Hopefully it'll assist you in using coding more productively, and do keep vimming!


Post a comment