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 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's libindex (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-document root might not work
  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. For the moment, only trees named "mozilla-central" actually work. 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.

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

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

Producing DXR output

If you are using dehydra, I don't have instructions for you yet.

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 CC=gcc # Or your favorite C compiler here
export CXX=g++ # Or your favorite C++ compiler here
export DXRSRC=dxrsrc
make -C $DXRSRC/xref-tools/cxx-clang # Build the indexer
. $DXRSRC/xref-tools/cxx-clang/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 recollect the sql:

cd wwwdir
python xref-scripts/run-dxr.py

When that is done, you can then point your web browser at your DXR installation and start navigating the source code.