LXR Guide

LXR, shortened for Linux Cross-Reference, is a perl web application that lets you read different versions of the Linux kernel source code with the added benefit of quickly searching the source and having static values and functions cross-referenced with each other.

Step by Step Guide

The installation of LXRng are detailed in this guide for a CentOS 7 server. We will be using:

• LXRng
• PostgreSQL (as a fulltext index)
• Apache 2.4 / mod_perl

Prerequisites

On a clean install of CentOS 7, install the following dependencies. A few Perl modules must be installed outside of yum and I recommend using cpanm.

# yum install postgresql postgresql-server \
perl-App-cpanminus \
xapian-core xapian-core-devel \
perl-DBI perl-DBD-Pg \
perl-Term-ProgressBar \
perl-Pod-POM \
perl-CGI \
perl-HTML-Template \
perl-XML-Parser \
perl-XML-NamespaceSupport \
perl-XML-LibXML \
perl-XML-SAX-Base \
perl-Image-Xbm \
perl-Image-Base \
perl-Template-Toolkit \
perl-Linux-Pid \
perl-BSD-Resource \
make gcc gcc-c++  \
ctags \
httpd \
mod_perl mod_ssl \
git \
screen

lxr expects it as ctag as ctags-exuberant.

# ln -s /usr/bin/ctags /usr/bin/ctags-exuberant

Install the missing dependencies through cpanm:

# cpanm Search::Xapian
# cpanm Test::More
# cpanm Devel::Size

Pull the lxrng source into /var/www. Apache will own everything since the web server will need to run the web application.

# cd /var/www
# chgrp apache .
# sudo -u apache git clone git://lxr.linux.no/git/lxrng.git

If this repository is down, a copy is also available at https://git.steamr.com/leo/lxrng.git

Setting up PostgreSQL

With PostgreSQL installed, set it up with a lxrng database. You may want to set up permissions as well, but I will be using the root account.

# postgresql-setup initdb
# systemctl start postgresql
# systemctl enable postgresql

By default, Postgres should be configured to use system accounts for authentication. Since we will have the Apache web server running as apache, we will create a Postgres account named apache that should have access to the lxrng database.

# su postgres
$ createuser -d apache

LXRng Setup

The lxrng.conf configuration file located at /var/www/lxrng/lxrng.conf should contain the following:

# -*- mode: perl -*-
# Configuration file
#
#

use LXRng::Index::PgBatch;
use LXRng::Repo::Git;
use LXRng::Search::Xapian;

my $gitrepo = LXRng::Repo::Git
    ->new('/var/www/lxrng/repos/linux-2.6/.git',
          release_re => qr/^v[^-]*$/,
          author_timestamp => 0);

my $index   = LXRng::Index::PgBatch->new(db_spec => 'dbname=lxrng;port=5432',
                                         db_user => "apache", db_pass => "",
                                         # table_prefix => 'lxr'
                                         );
my $search  = LXRng::Search::Xapian->new('/var/www/lxrng/text-db/linux-2.6');

return {
    'linux' => {
        'repository'  => $gitrepo,
        'index'       => $index,
        'search'      => $search,

        'base_url'    => 'http://lxr.cpsc.ucalgary.ca/',
        # Must be writable by httpd user:
        'cache'       => '/var/www/lxrng/cache',

        'fs_charset'  => 'iso-8859-1',
        # Tried successively
        'content_charset' => ['utf-8', 'iso-8859-1'],

        'languages'   => ['C', 'GnuAsm', 'Kconfig'],
        #'ctags_flags' => ["-I\@$LXRng::ROOT/lxr-ctags-quirks"],
        'ver_list'    => [$gitrepo->allversions],

        'ver_default' => 'v4.9',

        'include_maps' =>
            [
             [qr|^arch/(.*?)/|, qr|^asm/(.*)|,
              sub { "include/asm-$_[0]/$_[1]" }],
             [qr|^include/asm-(.*?)/|, qr|^asm/(.*)|,
              sub { "include/asm-$_[0]/$_[1]" }],
             [qr|^|, qr|^asm/(.*)|,
              sub { map { "include/asm-$_/$_[0]" }
                    qw(i386 alpha arm ia64 m68k mips mips64),
                    qw(ppc s390 sh sparc sparc64 x86_64) }],
             [qr|^|, qr|(.*)|,
              sub { "include/$_[0]" }],
             ],
    },
};

There are a few important values which you may want to change:

• $gitrepo defines where the source code (as a git repo) will be placed. In our case, /var/www/lxrng/repos should contain a directory called linux-2.6/.git containing the git repository.
• $search defines where the text index should reside
• base_url is the URL of the web application
• cache is the cache directory used by lxr.

Create these directories, and ensure they are readable and writable by apache:

# cd /var/www/lxrng
# mkdir repos
# mkdir -p text-db/linux-2.6
# mkdir cache
# chmod 777 cache

Fetch the Kernel Source

Get the source code either via git or from an existing tarball.

# cd /var/www/lxrng/repos
# git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git

## or for the newest post-2.6 kernels:
# git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

Start the indexing process:

# cd /var/www/lxrng/
# sudo -u apache sh
$ ./lxr-db-admin linux --init
$ ./lxr-genxref linux
## Or alternatively, run it in screen: screen -d -m ./lxr-genxref linux
##  and then view progress by running screen -r

Setting up Apache

# cd /export/lxrng
# cp apache2-site.conf-dist-mod_perl /etc/httpd/conf.d/lxrng.conf
# sed -i "s/@@LXRROOT@@/\/export\/lxrng/g" /etc/httpd/conf.d/lxrng.conf
# sed -i "s/@@LXRURL@@/lxr/g" /etc/httpd/conf.d/lxrng.conf
# sed -i "s/^[\(^#\)]*/# /" /etc/httpd/conf.d/welcome.conf
# /etc/init.d/httpd start
# chkconfig httpd on --level 345

Updating Kernel Source

# cd repos
# git pull git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git master

Then, rerun the xref to update.

$ ./lxr-genxref linux