clang-tags – Quick start guide

This should be done every time the project configuration changes (list of source files, compiler switches, …):

make clean
clang-tags trace make

rm -f main.o
g++ -c -o main.o ../src/main.cxx
g++ -o main main.o

After the compilation database has been generated (at the previous step), it should be loaded into the system:

clang-tags load

Server response:

The first time clang-tags is used for a project, the full sources should be indexed:

clang-tags index

Server response:

-- Indexing project
/home/francois/projets/git/clang-tags/build/tests/src/main.cxx:
  parsing...    0.163754s.
  indexing...
    /home/francois/projets/git/clang-tags/build/tests/src/config.h
  indexing...   0.024179s.
0.311464s.

After source files change, the source index can be updated, which saves some time by only reparsing new content:

clang-tags update

Server response:

-- Indexing project
/home/francois/projets/git/clang-tags/build/tests/src/main.cxx:
  parsing...    0.163754s.
  indexing...
    /home/francois/projets/git/clang-tags/build/tests/src/config.h
  indexing...   0.024179s.
0.311464s.

Find the definition location of the identifier located in main.cxx at offset 849:

clang-tags find-def -r ../src/main.cxx 849

Server response:
-- display -- MemberRefExpr display
   ../src/main.cxx:15-17:8-3: display
   c:@S@MyClass>#d@F@display#

Find all uses of the Cursor::location() method (identified by its USR, as given in the second result of clang-tags find-def above):

clang-tags grep 'c:@S@MyClass>#I@F@display#'

Server response:
../src/main.cxx:21:  void display () {                                      // (defDisplayInt)
../src/main.cxx:33:  b.display();                                           // (display3)
../src/main.cxx:33:  b.display();                                           // (display3)

Open any source file in the project, and activate clang-tags-mode:

M-x clang-tags-mode

The mode-line should display a ct lighter indicating that the mode is active.

Go to any symbol in the source file, and press M-<dot>. A list of possible definition locations for the symbol should be displayed in a dedicated buffer called *ct/find-def*:

Server response:
-- display -- MemberRefExpr display
   ../src/main.cxx:15-17:8-3: display
   c:@S@MyClass>#d@F@display#

This buffer is a type of compilation buffer, meaning that all usual keys are available, especially:

• <tab> and S-<tab>: move to the next/previous entry
• RET: goto the location of the entry at point

While in the *ct/find-def* buffer, press M-<comma> to get a list of all uses of the symbol identified by the entry at point. The symbol uses should be displayed in a dedicated buffer called *ct/grep*, looking like this:

Server response:
../src/main.cxx:21:  void display () {                                      // (defDisplayInt)
../src/main.cxx:33:  b.display();                                           // (display3)
../src/main.cxx:33:  b.display();                                           // (display3)

This buffer displays the same content as if you had grepped your source files for the symbol name, and filtered out all false positives (symbols with the same name, but in different contexts). The buffer uses Emacs' standard grep mode, meaning that all usual features are available. In particular, using wgrep in this buffer can be an efficient refactoring tool to rename a particular symbol.