DXR
---
**Warning** this document is **outdated**. The DXR master branch contains DXR as deployed on dxr.mozilla.org, at this point in time new deployments are recommended to use the testing branch.

**Warning** this version will delete the configured www-directory.

Introduction:
-------------

DXR is a source code cross-reference tool that uses static analysis data
collected by instrumented compilers.  DXR was created in order to build on
tools like LXR and MXR.  DXR only runs on Linux for the moment.

Prerequisites:
--------------

You need a copy of python (at least 2.6), python-sqlite, and sqlite 3.7+.
If you want to use the output HTML, you will need a web-server of some kind.
Individual tools have further requirements:

cxx-clang: A copy of clang.

Setup:
------

DXR is primarily a database of source code information.  You need a lot of
space to do this, and a fast computer helps a lot.

DXR uses a configuration file to specify the different build trees and
specifying the commands needed to build those. Check the sample.config
file in the DXR source root directory for examples.

1) Create a wwwdir (e.g., /var/www/html/dxr) for the DXR interface.

2) DXR uses config info from an INI style config file. Copy dxrsrc/dxr.config
to your wwwdir and alter for your environment.

3) Copy (or symlink) the contents of dxrsrc/www to your web dir. If $DXRSRC
is the path to the DXR source code and $WWWDIR is the path to the wwwdir,
you can do:

ln -s -t $WWWDIR $DXRSRC/www/*

4) Copy sample.config and modify to fit your setup

From here on there are 2 ways to build your source tree:

5a) Run dxrsrc/update.sh <config> <tree-name> (eg. update.sh my.config
mozilla-central), this script will pull, build and index the source tree.

Or alternatively, do this step by step:

5b) Run . dxrsrc/setup-env.sh <config> <tree-name> to set up your
environment, where <config> is the path to the dxr.config file to use, and
<tree-name> is the name of the source tree to index as specified in the
configuration file. The single `.' at the beginning is very important; 
otherwise, your shell will not have the necessary variables exported.

6b) Compile and build your program. It is recommended that you use a separate
build directory from your source directory.

If the variable DXR_INDEX_OUTPUT is set on the command line, this will be used
to store the output csv files instead of the original source directory, so it
should match the objdir specified in dxr.config. This can also be specified in
the objdir key for the project entry in dxr.config

7b) Run the cross-reference generator:
dxrsrc/dxr-index.py -f /path/to/web/dir/dxr.config

You can optionally install the sqlite3 command line interface if it is not
already installed on your system.  You don't strictly need it, but it makes 
accessing the database manually easier.

Running:
-------

You can build your source, create the xref database, and create the static HTML content as follows:

dxrsrc/dxr-index.py -f /path/to/web/dir/dxr.config

This will post-process the data into dxr.sqlite.  It will also build the static
html and create a full-text search index.  All these files will be created in
the wwwdir using the name of the tree you provided in dxr.config. You will end
up with the following structure:

/var/www/html/dxr (or whereever your wwwdir is located)
      /index.html (auto-generated during dxr-index.py)
      /tree (symlink to tree-current)
      /tree-current
                   /.dxr_xref
                             /tree.sqlite
                             /index_bob.dat  [A pickle file of plugin data]
                             /file_list.txt  [A list of source files]
                             /file_index.txt [An index of the source files]

More Information:
-----------------

For more information, please see https://wiki.mozilla.org/DXR.