[Howto] LXRng on Ubuntu 7.10

It's been a long time since my last post and also since my latest linux-kernel development activity. I'm getting close to graduation and college is taking all of my time. My latest work on any non-college related stuff dates back to November, which is a very long three months period. Before this period I helped in developing some small parts of SMACK [1]. I remember those days very well, since this was my first time to contribute something not related to kernel janitors stuff and simple one-liner bug fixing. I was very happy in this active smack development period.

Now I'm trying to get back in the kernel development mood by following LKML, testing development trees and continue editing my kernel notes. I'll try not to quit this time even if I have the most complicated CS courses in one semester, errr.

While hacking the Linux Kernel, LXR is my main friend. It helps me in getting info about any function or structure in a matter of seconds. Due to some internet connection problems here in Egypt, I decided to deploy it locally. LXR's main author, Arne Georg, forked a new lxr version named LXRng which I decided to give it a try. Unfortunately the project is relatively new and the documentation was not very user friendly. The build process made me scratch my head for a while and I felt it's very worthy to write a simple ubuntu installation howto.

So without further ado, here we go:

1- Install 'git' scm and clone lxr's developer git tree as follows:
$ sudo apt-get install git-core
$ git-clone git://lxr.linux.no/git/lxrng.git

2- Install the postgresql database and it's client apps:
$ sudo apt-get install postgresql-8.2
$ sudo apt-get install postgresql-client-8.2

3- Install the Xapian search engine library and its Perl bindings:
$ sudo apt-get install libxapian15
$ sudo apt-get install libsearch-xapian-perl

4- Install apache and its perl module and as mentioned in documentation, install some of the HTML/Web Perl modules:
$ sudo apt-get install apache2 libapache2-mod-perl2
$ sudo apt-get install libcgi-simple-perl libcgi-ajax-perl libhtml-parser-perl libtemplate-perl

5- Install two more CPAN modules needed by the indexing process. One of them is used to check the memory usage and the second to draw a shiny toolbar.
$ sudo apt-get install libterm-progressbar-perl libdevel-size-perl

6- Now assuming 'ahmed' is your username that you are actually logged in with and the one that you did all the above commands with, run:
$ sudo -i
$ su - postgres
$ createuser ahmed # Answer 'yes' when asked about superprivileged access
$ exit

7- Create a suitable database for LXR and add the HTTP daemon user as an unprivileged DB user as follows:
$ createdb lxrng
$ createuser www-data

8- Now we are getting close to some of the interesting parts. We'll copy the template configuration file and modify it to represent our needs:
$ cp lxrng.conf-dist lxrng.conf
$ vim lxrng.conf

9- A lot of options can be specified in the config file, which is a perl script that you'll need to carefully modify. First you have two options, either to use a git repository, so you can cross-reference all of your project's history or you can cross-reference a single source directory.

You'll need to edit libXapian search files path, initialized in $search. Make sure the specified path exists with suitable permissions for current user or following steps will fail.

For referencing a whole git repository:
You'll need to edit below variables:
.... a- Your git repository path, initialized in $gitrepo
.... b- Your default version, where LXR will directly open, initialized in the line 'ver_default' => 'v2.6.20.3'.
.... c- If your git repository contains much more history than what you actually need, you can only specify the needed versions to be cross referenced by editing the line 'ver_list' => ['v2.6.23', 'v2.6.24'].
.... d- The version names given at points b and c must exactly exist in the listing of the command "$git-tag -l". Otherwise, you'll face several failure points during the build and running time.

For referencing an isolated source directory (like a kernel.org-release tar file):
Assuming:
@@Source@@: an absolute path to desired project's source dire
@@Project_Name@@: Desired project name/alias
@@LXR_ROOT@@: Absolute path to downloaded lxrng source

$ mkdir source
$ (cd source && ln -s @@Source@@ @@Project_Name@@)
$ sed -i 's/$gitrepo/$plainrepo/g' lxrng.conf

Write directly after the end of conf file 'Use' statements:
use LXRng::Repo::Plain;
my $plainrepo = LXRng::Repo::Plain ->new('@@Source@@');

Then modify below variables as stated:
ver_list => ['@@Project_Name@@']
ver_default => '@@Project_Name@@'

10- Create database tables and cross-reference your source repository:
$ ./lxr-db-admin linux --init
$ ./lxr-genxref linux

11- Have a break and hang out with your friends for a while if you have a huge source repository like the Linux kernel.

12- Last step is to configure apache to point to lxr cgi scripts. This is simply done by the following steps:
$ cp apache2-site.conf-dist-perl apache2-site.conf
$ ln -s $pwd/apache2-site.conf /etc/apache2/sites-enabled/010-lxrng
$ vim apache2-site.conf
$ # Replace @@LXRROOT@@ with LXR source directory root.
$ # Assure that user www-data has read permissions to LXRROOT files.

13- Congratulations!. At last, we're done. You can begin exploring kernel sources at: http://localhost/lxr. Enjoy your time.

Thanks to Arne Georg Gleditsch for providing this amazingly useful peace of software.
See you the next post :).

[1]: You can know more about SMACK from the SMACK homepage. You can also check a linux.conf.au conference video explaining its uses and features.