source code tagging tool for C/C++
Python C++ Makefile Other
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
test
LICENSE.txt
README.cygwin.md
README.ja.md
README.md

README.md

cxxtags

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.

Prerequisite

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.

How to build

  • 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.

How to use

Build the database

Generate a tag database by using cxxtags.

    $ cxxtags _db a.cpp

Run query to the database

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.

Generate a tag database from CMakeLists.txt

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.

Commands

cxxtags_run_proj

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

cxxtags

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.

cxxtags_query

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.