Read Source Code the HTML Way

Every decent programmer has to study source code at some time or other. Sometimes it's to learn new coding styles. Sometimes it's to get an idea of how something works. Regardless of the reason, no programmer can do without it. Studying the source code of small projects is not difficult. You easily can do without formal methods. However, when you want to study the source code of large projects, keeping track of the various functions, variables and their definitions becomes a huge problem. People are lucky if they can find the source code on-line—doing so means they can use tools to process the source code and help them study it. Such tools give people studying source code advantages and flexibility never before dreamed of. One such tool is the LXR (Linux Cross-Reference) tool.

Developed originally as a testbed application for a general hypertext cross-referencing tool in Norway, its flagship achievement is cross-referencing the Linux kernel source code. The code is available at lxr.linux.no/source for browsing. Other projects are at lxr.mozilla.org/seamonkey, where the Mozilla source code is available for browsing, and the FreeBSD source code is available at fxr.watson.org. LXR gives users the capability to jump to function definitions, search for usages and so forth with only a single click. It also supports indexing of e-mail and hypertext links.

The project is based on stock Web technology, so it can be accessed via any Web browser. On the server side, it was developed using Apache but should work with any Web browser supporting CGI-scripting capabilities. The scripts that actually do all the work were developed using Perl and rely heavily on Perl's powerful regular expression libraries.

Probably the best feature of this software is that it is presented to users in HTML format. Because of the HTML format, it is easy to link various portions of the code to others. It is written in Perl, so theoretically, it can run on any operating system that has a Perl interpreter. What is really great about this tool is that it supports multiple languages. This means it doesn't matter which language your program is written in; you still can use this tool to cross-reference and browse your code.

LXR is actually quite simple and clean. The users use a utility called genxref to generate an index of the complete source code. Once this is done, users access a Perl script called source through a Web browser that reads the index files and generates the HTML for the cross-referenced source code dynamically. Users then can browse the source code as they want.

Installing and configuring LXR is pretty simple once you know a bit about how it works and what the various configuration options are. First, download the source tarball from sourceforge.net/projects/lxr. At the time of this writing, lxr-0.3 is the stable release. Once you have downloaded the tarball, extract it using:

bash# tar -xvf lxr-0.3.tar.gz

After extracting the source, cd to the newly created directory, and open the Makefile for editing with the text editor of your choice. You need to set two variables here: INSTALLPREFIX and PERLBIN. PERLBIN refers to the executable binary of the perl5 interpreter. In my case, it was in /usr/bin/perl. INSTALLPREFIX is the directory where LXR will be installed. It should be in a location that is accessible via a Web browser. On my system, that's Apache 1.3.33, and I chose to install it under /var/www/htdcos/. Thus, my Makefile looked something like this:

# Makefile for installation and configuration of LXR

# The location of your perl5 binary

PERLBIN=/usr/bin/perl

# LXR will be installed here

INSTALLPREFIX=/var/www/htdocs/lxr

# End of configuration parameters

CGISCRIPTS=find ident search diff source

PERLMODULES=SimpleParse.pm Common.pm Config.pm

....

....

....

Leave the rest of the Makefile unchanged. At the console, type:

bash# make install

and LXR is installed in the specified directory.

Now, cd to the directory where LXR was installed (in my case that was /var/www/htdocs/lxr). Three subdirectories should be there: bin, http and source. Although the source code you want to cross-reference can be placed anywhere, I prefer to put it under the $INSTALLPREFIX/source subdirectory. I put the glibc-2.3.5 and OpenMOSIX-2.4.26 source code here. Now, we have to generate the index files that LXR will use to generate the cross-referenced source code. So, cd to the directory with the source code, and execute the genxref script in $INSTALLPREFIX/bin:

bash# /var/www/htdocs/lxr/bin/genxref .

The . at the end tells the script that the source code is contained within the current directory. Next, sit back and enjoy the ride until the parsing is complete. Once it's done, you should have two new files in the current directory—the directory containing your source code—fileidx and xref. These two files are the ones lxr needs to generate the cross-referenced source code when you browse it. Make sure that others have read permission for these files. To do so, type the following while still in the source directory:

bash# ls -l fileidx xref

The output should be something like:

-r--r--r-- 1 nobody root 671744 2006-08-24 05:06 fileidx*

-r--r--r-- 1 nobody root 8425472 2006-08-24 05:06 xref*

The third r should be set. If it isn't, you can set it by doing the following:

bash# chmod o+x fileidx xref

Now, it's time to configure LXR for use. Change directory to $INSTALLPREFIX/http/ (in my case, that is /var/www/htdocs/lxr/http/), and open the lxr.conf file for editing. The lxr.conf file is the most important file you need. It has several different configuration options.