Source code browsing using GNU ID and Emacs

Source code comprehension programs are amongst the most important tools that every software developer needs to master. Using these tools in an integrated way from the comfort of you favourite editor is important to minimise the context switches that kill the developer’s productivity (you know, “the zone…”).

Here it is a short HowTo on how I use GNU ID Utils from Emacs. This assumes some Linux/Debian derivative (in my case Ubuntu 12.04) and a C/C++ project, but other languages like Perl or Java are also supported by GNU ID.

Verify that the id-utils Debian package is installed

$ dpkg -l | grep id-utils
ii  id-utils  4.5-3  Fast, high-capacity, identifier database tool

Alternatively, install it

$ sudo apt-get install id-utils

Download idutils.el and put it somewhere in your Emacs search path

The idutils source distribution comes with idutils.el, an Emacs interface to gid, the utility that comes with idutils and that let’s you query the ID database from the command line. At the time of writing, 4.6 is the latest version of the idutils package. However, it probably is safer to use the idutils.el from the same release as the idutils package installed on your system (in my case that is 4.5).

$ cd ~/temp
$ wget
$ xz -d idutils-4.5.tar.xz
$ tar xvf idutils-4.5.tar
$ cp idutils-4.5/lisp/idutils.el "somewhere where emacs can find it"

Update your Emacs config

Add the following to your dotemacs file:

;; Emacs GNU ID utils interface
;; M-x gid to run the command
;; more info at
(autoload 'gid "idutils" nil t)

Build the ID database

The next step is to run mkid to build the identifier database. The following commands will produce an ID file in you project’s root directory. This will index your system headers as well as your project’s source code. E.g.:

$ cd "your favorite project"
$ mkid -s /usr/include/ .

Run gid from within Emacs

Open up any source file from your project, point your cursor at some identifier and run M-x gid. Emacs will ask you something like this:

Run gid (with args): thread_mutex_create

Just hit enter and Emacs will bring up a *compilation* buffer with the results:

-*- mode: gid; default-directory: "/home/juanrubio/3rdparty/icecast/src/" -*-
Gid started at Wed Apr 10 12:57:01

gid thread_mutex_create
thread/thread.h:104:#define thread_spin_create(x)  thread_mutex_create(x)
thread/thread.h:111:#define thread_mutex_create(x) thread_mutex_create_c(x,__LINE__,__FILE__)
thread/thread.h:136:# define thread_mutex_create_c _mangle(thread_mutex_create)
auth.c:683:        thread_mutex_create (&auth->lock);
cfgfile.c:94:    thread_mutex_create(&_locks.relay_lock);
connection.c:147:    thread_mutex_create(&move_clients_mutex);
format_mp3.c:122:    thread_mutex_create (&state->url_lock);
global.c:45:    thread_mutex_create(&_global_mutex);
slave.c:139:    thread_mutex_create (&_slave_mutex);
source.c:106:        thread_mutex_create(&src->lock);
stats.c:134:    thread_mutex_create(&_stats_mutex);
stats.c:138:    thread_mutex_create(&_global_event_mutex);
stats.c:864:    thread_mutex_create (&(listener.mutex));
util.c:719:         thread_mutex_create (&localtime_lock);
xslt.c:101:    thread_mutex_create(&xsltlock);
yp.c:282:    thread_mutex_create (&yp_pending_lock);
net/resolver.c:41:#define thread_mutex_create(x) do{}while(0)
net/resolver.c:206:        thread_mutex_create (&_resolver_mutex);
thread/thread.c:164:    thread_mutex_create(&_threadtree_mutex);
thread/thread.c:165:    thread_mutex_create(&_library_mutex);    

Gid finished at Wed Apr 10 12:57:01

The results can be navigated with the usual Emacs commands M-x next-error and M-x previous-error, (usually assigned to M-g n and M-g p)

Similar tools

There are a number of other source browsing/navigation tools that are specific for Emacs or that also integrate well with Emacs, some of them are:

5 Replies to “Source code browsing using GNU ID and Emacs”

  1. Hi…Thanks for the tutorial.
    Do you know if there is a way to exclude comments from being searched?
    Sometimes when searching for a variable or function that is also part of a C comment it shows up unnecessarily in the ID search.

    1. That’s a good question. mkid by default includes the C, C++, and asm language scanners when it builds the ID database. I believe if you ask mkid to remove the ‘asm’ scanner from that list, C and C++ comments should not be accounted for during the token search. So I guess you would create your ID db like this:

      mkid -s -i C /usr/include .

  2. I have 2 servers and access the same sandbox (source code) from 2 different mount points on 2 different servers. Although I run mkid from server1, I would like to use gid from both the servers. Is there a way to force mkid to use relative path to create ID file rather than the absolute path?

    Server 1 path is: /b/mountPoint1/user1/myCommonSandbox/src
    Server 2 path is: /b/mountPoint2/user1/myCommonSandbox /src

Leave a Reply

Your email address will not be published. Required fields are marked *