Using LXR for browsing C/C++ Programs in HTML

:: Using LXR for browsing C/C++ Programs in HTML ::
HOME

Using LXR for browsing C/C++ Programs in HTML

Linux Cross Referencing or LXR is a very versatile tool for generating cross-referenced HTML files for source-codes in C (and C++, I think). For example, you can browse through the linux source code, as indicated here.
I wanted to use LXR for providing HTML cross-referenced files for many different source trees. In the below recipe, I will explain, how I made use of LXR to create such files.
Download the lxr tarball and install it using the instructions given in the $basedir/INSTALL file. I have chosen to install LXR in /var/www/cgi-bin/lxr, and hence I made the necessary changes to INSTALLPREFIX in $basedir/Makefile.
```
lxr-0.3# cat Makefile
# 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/cgi-bin/lxr
--SNIP--
```
One has to place the following .htaccess file in /var/www/cgi-bin/lxr/http, so that the cgi-scripts in this directory are executed by the web server (apache) rather than just passing it back as a text file.
```
var/www/cgi-bin/lxr/http/# cat .htaccess 
<Files ~ (search|source|ident|diff)$>
  SetHandler cgi-script
</Files>
```
Restart the apache web server using apachectl restart

I then edited the file /var/www/cgi-bin/lxr/http/lxr.conf to suite my needs as indicated below:

1.  [papers@mia http]# cat lxr.conf
2.  # Configuration file.

3.  # Define typed variable "v", read valueset from file.
4.  variable: v, Version, [/var/www/cgi-bin/lxr/source/versions], [/var/www/cgi-bin/lxr/source/defversion]

5.  # Define the base url for the LXR files.
6.  baseurl: http://mia.ece.uic.edu/cgi-bin/lxr/http/

7.  # These are the templates for the HTML heading, directory listing and
8.  # footer, respectively.
9.  htmlhead: /var/www/cgi-bin/lxr/http/template-head
10. htmltail: /var/www/cgi-bin/lxr/http/template-tail
11. htmldir:  /var/www/cgi-bin/lxr/http/template-dir

12. # The source is here.
13. sourceroot: /home/shashank/temp/$v
14. srcrootname: VPN_Solutions

15. # "#include " is mapped to this directory (in the LXR source
16. # tree)
17. incprefix: /usr/include

18. # The database files go here.
19. dbdir: /var/www/cgi-bin/lxr/source/$v


20. # Glimpse can be found here.
21. glimpsebin: /usr/local/bin/glimpse

22. # The power of regexps.  This is pretty Linux-specific, but quite
23. # useful.  Tinker with it and see what it does.  (How's that for
24. # documentation?)
25. map: /include/asm[^\/]*/ /include/asm-$a/
26. map: /arch/[^\/]+/ /arch/$a/

NOTE: the following lines:

Line 4: I have defined the variable version to take value from files: /var/www/cgi-bin/lxr/source/versions, and default value from /var/www/cgi-bin/lxr/source/defversion. (Actually both are the same). Since I want to generate HTML cross references for different projects, I put all such project name in these files, one on each line. For example:
```
# cat /var/www/cgi-bin/lxr/source/versions
linvpn-2.6-pre1
htun-0.9.5
--SNIP--
```
Line 6: Note the base URL (with the ending /)
Line 13: The sourceroot variable tells lxr where the root of the source tree for the project is located. I have kept all the source trees in /home/shashank/temp/$v, where $v is the value linvpn-2.6-pre, htun-0.9.5 and so on.
Line 14: Give any name you want.
Line 17: The source C files have #include <stdio.h> macros. The incprefix variable tells lxr, which include files does this refer to.
Line 19: This tells LXR where the database index files are located for each project. I have chosen to keep all these files in /var/www/cgi-bin/lxr/source/$v, where $v takes the values linvpn-2.6-pre, htun-0.9.5 and so on.
Line 21: Gives the path to glimpse binary.

For lxr version 0.3 make sure that you create the following links using ln -s command.

lrwxrwxrwx 1 apache apache    8 Oct 10 12:27 difflxr.conf -> lxr.conf
lrwxrwxrwx 1 apache apache    8 Oct 10 12:27 findlxr.conf -> lxr.conf
lrwxrwxrwx 1 apache apache    8 Oct 10 12:27 identlxr.conf ->
lxr.conf
lrwxrwxrwx 1 apache apache    8 Oct 10 12:28 searchlxr.conf ->
lxr.conf
lrwxrwxrwx 1 apache apache    8 Oct 10 12:14 sourcelxr.conf ->
lxr.conf

Make sure that you modify the diff file in /var/www/cgi-bin/lxr/http/diff line 133 as:
```
    close(DIFF)
    
```
instead of
```
    close(<DIFF>)
    
```
otherwise your diff will not work!
For each project you will have to generate index files and keep them in their respective directories. For example, for linvpn-2.6-pre1, I keep the index files in /var/www/cgi-bin/lxr/source/linvpn-2.6-pre1

The index files are generated using the following commands:

# cd /var/www/cgi-bin/lxr/source/linvpn-2.6-pre1/
# /var/www/cgi-bin/lxr/bin/genxref /home/shashank/temp/linvpn-2.6-pre1/
  Starting pass 1: Collect identifier definitions.
 (Pass 1) src/lib/pwd.c (1774), file 1 of 39...
 (Pass 1) src/lib/vpnlib.h (3002), file 2 of 39...
 (Pass 1) src/lib/version.c (1399), file 3 of 39...
 (Pass 1) src/lib/edit.c (2550), file 4 of 39...
--SNIP--
-----------------------------------------------------------------------------
#glimpseindex -H . /home/shashank/temp/linvpn-2.6-pre1/
--SNIP--
  Indexing "/home/shashank/temp/linvpn-2.6-pre1/" ...
  Size of files being indexed = 1242531 B, Total #of files = 77
  Index-directory: "/var/www/cgi-bin/lxr/source/linvpn-2.6-pre1"
  Glimpse-files created here:
   -rwxrwxrwx    1 apache   apache       4282 Jul 25 18:42 .glimpse_filenames
   --SNIP--

NOTE: After all the index files are generate make sure that they belong to apache. Use the following command

#chown -R apache:apache /var/www/cgi-bin/lxr/source/linvpn-2.6-pre1/

Repeat the above steps for all your projects.
Modify the /var/www/cgi-bin/lxr/http/(template-head, template-tail, template-dir) files as required.
Thats it!!!. Now point your browser to http://mia.ece.uic.edu/cgi-bin/lxr/http/source, and start cross-referencing.

I have also created a simple perl script to do all the above steps. This is listed below:

[shashank@mia source]# cat refreshindex.pl
#!/usr/bin/perl

$infile = "./versions";
open (INFH, $infile);

while ($lines = <INFH>){
    if ($lines =~ /^\s*$/){
        last;
    }
    chomp $lines;
    if (-e $lines) {
        print "File/Directory $lines is already present... Not updating\n";
    }else{
        #print "File $lines is NOT present. \n";
        print "Making a new directory $lines.\n";
        mkdir("$lines",0755) || die "cannot mkdir $lines: $!";
        print "Changing to new directory $lines.\n";
        chdir("$lines") || die "cannot cd to $lines ($!)";
        system "/var/www/cgi-bin/lxr/bin/genxref /home/shashank/temp/$lines";
        system "glimpseindex -H . /home/shashank/temp/$lines";
        system "chown -R apache:apache .";
    }
};