DXR

DXR is a smart source code browser, along the lines of MXR, that uses instrumented compilers to determine information about every variable, type, and function in your code for an enhanced browsing experience.

Obtaining source code

The official source code for DXR can be found on hg.mozilla.org or on github, the clang branch (the two should be direct mirrors of each other). The current main development fork of DXR is this branch, which contains insufficiently-baked features not considered ready for production use.

Prerequisites

In addition to the source code, the following programs are necessary:

• sqlite3
• python (with python-sqlite package)
• glimpse
• gcc-4.5 with dehydra plugin (if using dehydra)
• LLVM and clang (if using clang)
• A web server capable of running python as cgi (a standard apache2 install should work)

Setting up

For the purposes of the rest of this documentation, dxrsrc refers to the directory which contains the source code for DXR, and wwwdir the directory from which the web information will be stored. These should not be the same directory.

Configuring the webserver

The following is an example configuration in use for apache2 for the webserver:

<VirtualHost *:80>
  DocumentRoot wwwdir # Non-root installs currently have issues
  AddHandler cgi-script .cgi
  <Directory wwwdir>
    Options Indexes FollowSymLinks MultiViews
    Options +ExecCGI
    AllowOverride None
    Order allow,deny
    allow from all
  </Directory>
</VirtualHost>

The most important thing here is that wwwdir should be readable by the web server.

Set up wwwdir

In the wwwdir, you will need to copy or symlink the following files and directory:

export DXRSRC=dxrsrc
ln -s -t wwwdir $DXRSRC/www/* $DXRSRC/templates $DXRSRC/xref-scripts

Create dxr.config

The example dxr.config in dxrsrc is a guideline for how to start, but it is not immediately adaptable to all systems. I recommend you put this file in the wwwdir directory. Some notes on important values:

The [DXR] section contains links that are used in some scripts. A simple substitution of "/var/www/html/dxr" for your own srcdir should be sufficient. for xrefscripts and templates. The glimpse and glimpseindex entries are the full paths to the glimpse and glimpseindex binaries.

The [Web] section contains setup information for your webserver, so that DXR knows how to generate links.

Any other section contains information on a build-tree. The sourcedir is the full path to the source root, the objdir the full path to the build root, and mozconfig is a value which can be anything you want. Note that currently, the sourcedir and objdir need to be the same for the clang xref tool, because it always dumps the SQL output to the source directory.

An example configuration is as follows:

[DXR]
xrefscripts=/src/dxr/dxr-clang/xref-scripts
templates=/src/dxr/dxr-clang/templates
glimpse=/src/dxr/glimpse-4.18.6/bin/glimpse
glimpseindex=/src/dxr/glimpse-4.18.6/bin/glimpseindex

[Web]
wwwdir=/src/dxr/www
virtroot=/
hosturl=http://xochiquetzal

[git]
sourcedir=/src/dxr/git-1.7.5.3
objdir=/src/dxr/git-1.7.5.3
mozconfig=

Producing DXR output

The following instructions break for dehydra, and require the dxr-clang development branch.

If you are using clang (need dxr-clang development branch), you will need to do the following to set up your environment before building:

# Necessary, since I haven't finished dedumbifying scripts yet
export DXRSRC=dxrsrc # Not necessary, but it can save some typing
. $DXRSRC/setup-env.sh

Now configure and build your program as you want. Most build systems should sensibly handle the exported $CC and $CXX, however some crazier build systems (tmake?) appear not to. After building, you need to generate the web-directory:

cd wwwdir
python $DXRSRC/dxr-index.py

When that is done, you can then point your web browser at your DXR installation and start navigating the source code. Your source file will be located at virtroot/tree/path/to/file.c.html, e.g., http://<server>/git/ws.c.html.