cxxtags is a tool to tag and index C/C++ source files based on clang. The major difference from ctags is C++ syntax(ex. class, namespace, template, etc.) support and capability of generating cross reference information.

Several IDEs(Visual Studio, Eclipse, Xcode, etc.) already have this tagging(indexing) feature though, those are tightly built-in and not portable. cxxtags aims to be light-weight and portable source code tagging system.

• llvm and clang libs and headers
  • http://llvm.org/
• leveldb library and C/C++ headers.
  • https://code.google.com/p/leveldb/
• py-leveldb
  • Thread-safe Python bindings for LevelDB.
  • https://code.google.com/p/py-leveldb/

cxxtags is developped and tested on Ubuntu 14.04, python-2.7.6 and clang(LLVM)-3.4. But it is expected to be able to run on other Unix-like systems inluding cygwin.

• Install the dependent libraries

• Check out the repository

    $ git clone https://github.com/katonori/cxxtags.git
  

• Build the project using cmake

  • Run cmake and run build. Make sure that llvm-config is in your PATH.

  • You need to specify a variable LEVELDB_HOME if libleveldb is not under the default compiler search path.

      $ mkdir -p build && cd build
      $ cmake -DLEVELDB_HOME=/usr/local ../
      $ make
      $ make install
    

• Install

  • Copy the contents of ${CXXTAGS_REPOSITORY_ROOT}/bin directory to your installation path

• See README.cygwin.md for more information for cygwin.

Generate a tag database by using cxxtags.

    $ cxxtags _db a.cpp

To retrieve information from the database use cxxtags_query. For example, if you want to know where an item refered at line #30 and column #8 in file a.cpp is declared. invoke these command

    $ cxxtags_query def _db a.cpp 30 8

If a.cpp is like this

#include <iostream>
namespace NS0 {
    class C0 {
        public:
            void f0() { std::cout << "C0::f0\n"; }
            void f1() { std::cout << "C0::f1\n"; }
    };
    class C1 {
        public:
            void f0() { std::cout << "C1::f0\n"; }
            void f1() { std::cout << "C1::f1\n"; }
    };
};
namespace NS1 {
    class C0 {
        public:
            void f0() { std::cout << "C0::f0\n"; }
            void f1() { std::cout << "C0::f1\n"; }
    };
    class C1 {
        public:
            void f0() { std::cout << "C1::f0\n"; }
            void f1() { std::cout << "C1::f1\n"; }
    };
};

int main()
{
    NS1::C0 c0;
    c0.f1();
    return 0;
}

you will get output like this.

    f1|/home/user0/devel/cxxtags/src/build/a.cpp|18|18|            void f1() { std::cout << "C0::f1\n"; }

For vim users, the wrapper plugin of cxxtags_query cxxtags-vim is available.

cxxtags needs compile options such as "-I" "-D" to retrieve correct informations. If your project uses cmake, You can generate tag database by steps below.

• Run cmake with -DCMAKE_EXPORT_COMPILE_COMMANDS=1 option and build as usual. This generate a file "compile_commands.json" which contains the list of built files and their build options and working directory.

• Generate the tag database of the project to directory "_db" by cxxtags_run_proj

    $ cxxtags_run_proj _db compile_commands.json
  

Or you can also use Bear to generate the compialtion database.

For more information about the compilation database, see clang sitehttp://clang.llvm.org/docs/JSONCompilationDatabase.html.

Generate tag database from a compilation database generated by cmake. This command runs cxxtags internally.

usage: cxxtags_run_proj [-J] [-j N] [-e exclude_list] database_dir file_name

• -j N
  • Runs cxxtags on N threads.
• -J
  • Detect the number of CPUs on system and use it as the number of cxxtags threads.
• -e
  • Directories should be excluded from tagging. Directories are separated by ':' like "/usr/include:/usr/local/include".
• database_dir
  • output directory
• file_name
  • compilation database file name

Generates a database file.

usage: cxxtags [-e exclude_list] database_dir input_file [-- compiler_arguments]

• -e
  • Directories should be excluded from tagging. Directories are separated by ':' like "/usr/include:/usr/local/include".
• database_dir
  • output directory.
• input_file
  • input file.
• compiler_arguments
  • Compiler arguments needed to compile the input file.

perform a query to the database.

usage: cxxtags_query query_type[decl/def/ref/override] database_dir file_name line_no column_no

• query_type: Specify the type of query. Listed below are acceptable.
  • decl: Run query about declarations of a specified item.
  • def: Run query about definitions of a specified item.
  • ref: Run query about references of a specified item.
  • override: Run query about overridings of a specified item.
• database_dir: Database directory generated by cxxtags command. You can specify multiple database directory separated by ',' like "db0,db1,db2".
• line_no: Specify the line number the item is located in.
• column_no: Specify the column number the item is located in.