How to use LXR on Windows NT

Back to Main Page

This document will show you how to set up your own LXR cross-referencing source code browser. It's primarily intended for those who want to browse the Mozilla source without having to connect to lxr.mozilla.org, but it should be easy enough to adapt to any other C/C++ project you may have.

Note that I use emboldened text to indicate settings that are system specific such as file paths. You may need to replace these values with your own settings. 

Note that tools such as Perl, Cygwin32 and Apache prefer Unix style paths specified with forward slashes (e.g. "c:/perl/bin/"). I only use the backslash form (e.g. "c:\perl\bin") when dealing with the NT command prompt.

0. Before you start:

Before you go any further, you need to get the following tools:

Fetch the above tools before proceeding any further.

1. Install Cygwin32, Apache and ActivePerl

Run the installation programs that come with these packages to install them onto your machine. 

Note the paths where you installed the packages.

Add the bin directories for Perl and Cygwin32 to your PATH environment variable ensuring they appear before the Windows paths. E.g.

set PATH=c:\cygnus\cygwin-b20\H-i586-cygwin32\bin;c:\perl\bin;%PATH%

If you do not set these path values, the following steps will not work!

2. Get the DB_File Perl Package

After installation, you need to get a package for Perl called DB_File. This is used by LXR to create and read its keyword database. To get this we use the package manager tool - PPM - that comes with ActivePerl.

If you are behind a firewall, you will need to refer to the PPM documentation to set certain environment variables that let you fetch packages through a proxy.

To fetch the DB_File package:

  1. Type 'ppm' to start PPM.
  2. Type 'install DB_File' to fetch and install the DB_File package.
  3. Type 'quit' to quit PPM.

3. Building LXR

First things first, extract the LXR tar file into its own directory, e.g. c:\lxr-0.3.

Edit the file 'Makefile' with a text editor such as notepad.

Change the line that declares PERLBIN  to point to your Perl bin directory, e.g.:

PERLBIN=c:/perl/bin/perl.exe

Change the line that declares INSTALLPREFIX to point to where you want your LXR keyword database, scripts and template html files to reside, e.g.

INSTALLPREFIX=c:/mozlxr

Save the file.

From a command prompt, type:

c:
cd lxr-0.3
make install

You may see this error:

install --mode 644 http/* c:/mozlxr/http/
install: http/*: No such file or directory
make: *** [install] Error 1

If this happens, type:

copy http\* c:\mozlxr\http

4. Build the keyword database

The next task is to run the LXR tool over the source code to build a keyword database.

To do this, open a command prompt and type:

c:
cd c:/mozlxr/source
perl ../bin/genxref c:/mozilla

This will trawl through the whole of Mozilla, building a big database of keywords. Note that it takes a long time to do! It works best on clean tree where there are no object files to get in the way.

5. Edit lxr.conf

Now you have installed LXR and built the database, it is time to configure it to serve pages to you.

Change to your LXR directory and edit lxr.conf, e.g.:

c:
cd \mozlxr\http
notepad lxr.conf

Fix up the paths in this file to point to the locations where your templates and database are stored. Here is a sample lxr.conf:

# Configuration file.

# Define the base url for the LXR files.
baseurl: http://localhost/lxr/

# These are the templates for the HTML heading, directory listing and
# footer, respectively.
htmlhead: c:/mozlxr/http/template-head
htmltail: c:/mozlxr/http/template-tail
htmldir: c:/mozlxr/http/template-dir

# The source is here.
sourceroot: c:/mozlxr/
srcrootname: Mozilla

# "#include <foo.h>" is mapped to this directory (in the LXR source
# tree)
incprefix: c:/mozilla/dist/include

# The database files go here.
dbdir: c:/mozlxr/source

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

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

Save the new lxr.conf.

6. Configure the web server

This section assumes you have Apache. If you don't you will have to do whatever the equivalent operation is for your web server.

First things first you need to ensure that your lxr folder is visible from your web server. In Apache you must add an alias to its httpd.conf file to see it, e.g.

Alias /lxr/ "c:/mozlxr/http/"

This means that typing http://localhost/lxr will cause the web server to read the contents of c:/mozlxr. 

Your web server also needs to know which files are actually scripts or it won't run them. In Apache this is done by creating a .htaccess file containing a list of scripts. From the command prompt:

c:
cd \mozlxr\http
notepad .htaccess

Add this text and save the file.

<Files ~ (search|source|ident|diff)$>
    SetHandler cgi-script
</Files>

Your web server may need to be restarted. On NT Apache may be running as a service in which case you must stop and start it from the services control panel.

7. Testing it

After restarting your web server, you can test it out. Try typing some URLs such as http://localhost/lxr, http://localhost/lxr/source to see if they work. If not, carefully example the error message to determine where the fault lies. For example, if the web server cannot locate the lxr path it indicates an aliasing problem. If the script runs but reports an error, it indicates a problem in lxr.conf or the keyword database. 

If these work, try typing a longer URL such as http://whippy/lxr/source/mailnews/imap/src/nsIMAPBodyShell.cpp and verify that the file is displayed and correctly hyperlinked.

Back to Main Page