-- markdown --

Building

You'll need llvm and clang, at least 3.3. Trunk should work fine.

The following should build the clang plugin:

% make

Then do the normal build and install of the python bits

% python setup.py build
% python setup.py install

(use --user on the install to install into ~/.local.)

Using

Put emacs/dxr.el somewhere suitable, and add something like the following to ~/.emacs or equivalent:

(autoload 'dxr-decorate-buffer "dxr")
(add-hook 'c-mode-common-hook 'dxr-decorate-buffer)

The indexing script is dxr-index.py and is used to build whatever code you're interested in with the clang plugin. It creates trivial shellscripts called cc, gcc, etc., and puts those first on the PATH. So you can do something like:

% dxr-index.py -s llvm-trunk -b llvm-indexobj \
  "../llvm-trunk; ./configure; make -j4"

and inside llvm-indexobj you'll get a build, and you'll also get llvm-trunk/dxr-xref.sqlite.

The database is a slightly modified and heavily reduced form of the database used by DXR. It contains only information produced by the clang plugin (so no trigram data), and most of the id columns have gone. Instead, dxr-lookup.py correlates entities using file,line,col of the relevant declaration.

Beware that the build directory (given after -b) is normally deleted. If it's the same as the source directory or if it's ., then it's not. (. is something of a special case. You might use it for something like debuild where you want the command run in the currect directory.)

The flag -t can be used to give an alternative temporary directory, should tmp be unsuitable. It may need a fair bit of storage (depending on the size of the code being indexed, obviously). DXR stores CSV files which can really use up space; this variant stores gzipped CSV, so takes much less, at the expense of processing time.

For the trunk of llvm and clang, I find I need about 900M of temporary storage, and the final database takes up 450M.

In some file inside the source, the emace function dxr-decorate-buffer runs dxr-index.py decorate <file>. That sets up overlays and things for symbols; on any such symbol use M-RET or M-g . and you get a buffer showing declaration, definitions and references of the symbol. It also pushes point on to the normal tag ring so after visiting one of the other files M-* will return to the original symbol.

Updating the database (and build)

There's some support for incremental operation, though I won't guarantee it gives entirely correct results:

% dxr-index.py -i -s llvm-trunk -b llvm-indexobj "make"

Known bugs

In builds with C and C++, it's common to share headers between the two. That can cause an issue when an incremental update only rebuilds a C file including that header--you'll lose any C++-only information.