<commit_before>cxxtags
=======

### CAUTION: This project is under development.

What is this?
------------------------
**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(even though Eclipse(CDT) is a open source project). **cxxtags** aims to be light-weight and
portable source code tagging system.

Old **cxxtags** version based on sqlite3 is moved to https://github.com/katonori/cxxtags_sqlite3

Requirement
------------------------
**cxxtags** is written in C/C++ and python and based on the software listed below.

* 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 Mac OS X 10.9.3, python-2.7.5 and clang(LLVM)-3.2.
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 specifying LLVM\_HOME, LEVELDB\_HOME and BOOST\_HOME and run build

                $ mkdir -p build && cd build
                $ cmake -DLLVM_HOME=/pkg/llvm-3.2/ -DLEVELDB_HOME=/pkg/leveldb-1.15.0/ -DBOOST_HOME=/opt/local/ ../
                $ make
                $ make install

* Install
    * copy the contents of ${CXXTAGS\_REPOSITORY\_ROOT}/bin directory to your installation path

* See [README.cygwin.md](README.cygwin.md "") for more information for cygwin.

How to use
------------------------

### Build the database

**cxxtags** needs compile options such as "-I" "-D" to retrieve correct informations.

If you want to generate tags of cmake project, You can generate tags 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 database of the project to directory "\_db" by cxxtags\_run\_proj

        $ cxxtags_run_proj \_db compile_commands.json

Or use wrapper scripts of compilers.
g++.py and gcc.py included in this package are wrapper script of **cxxtags** and compilers.
This generate tag database
and run compilers. You can use this script like below


                $ env CXXTAGS_DB_DST=`pwd`/_db g++.py -O a.cpp
                
or

                $ env CXXTAGS_DB_DST=`pwd`/_db make CXX=g++.py


### 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 #8 and column #12 in file b.c is declared.
invoke this command

                $ cxxtags_query def _db b.c 8 12

If b.c is like this


         int func()
         {
             return 1;
         }

         int main()
         {
             return func() + 1;
         }


you will get output linke this.

                func|/devel/cxxtags/src/b.c|1|5|int func()


Commands
------------------------

### cxxtags
Generates a database file.

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

* -e  
  * Specify directories that contains source/header files that you don't want to generate the tags. Directories are separated by ':' like "/usr/include:/usr/local/include".

Compiler arguments are passed to clang. To get precise information you need to pass correct arguments just like you compile the source.

### cxxtags\_query
perform a query to the database.

    usage: cxxtags_query query_type[decl/def/ref/override/overriden] database_dir item_name file_name line_no column_no'
         : cxxtags_query query_type[name]                                 database_dir item_name'

* query\_type: Specify the type of query. Listed below are acceptable.  
    * decl: Run query information about **declared** location of a specified item.
    * def: Run query information about **defined** location of a specified item.  
    * ref: Run query information about **refered** location of a specified item. 
    * override: Run query information about items that a specified item overrides.
    * overriden: Run query information about items that is overriden by a specified item.
    * name: Search information about all items named *item\_name* in database.
* database\_dir: Database directory generated by **cxxtags** command.  
* item\_name: Specify the name of the item that you want to inspect.  
* line\_no: line number.
* column\_no: column number.
<commit_msg>Update the document.<commit_after>cxxtags
=======

### CAUTION: This project is under development.

What is this?
------------------------
**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(even though Eclipse(CDT) is a open source project). **cxxtags** aims to be light-weight and
portable source code tagging system.

Old **cxxtags** version based on sqlite3 is moved to https://github.com/katonori/cxxtags_sqlite3

Requirement
------------------------
**cxxtags** is written in C/C++ and python and based on the software listed below.

* 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 Mac OS X 10.9.3, python-2.7.5 and clang(LLVM)-3.2.
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 specifying LLVM\_HOME, LEVELDB\_HOME and BOOST\_HOME and run build

                $ mkdir -p build && cd build
                $ cmake -DLLVM_HOME=/pkg/llvm-3.2/ -DLEVELDB_HOME=/pkg/leveldb-1.15.0/ -DBOOST_HOME=/opt/local/ ../
                $ make
                $ make install

* Install
    * copy the contents of ${CXXTAGS\_REPOSITORY\_ROOT}/bin directory to your installation path

* See [README.cygwin.md](README.cygwin.md "") for more information for cygwin.

How to use
------------------------

### Build the database

**cxxtags** needs compile options such as "-I" "-D" to retrieve correct informations.

If you want to generate tags of cmake project, You can generate tags 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 database of the project to directory "\_db" by cxxtags\_run\_proj

        $ cxxtags_run_proj _db compile_commands.json

Or use wrapper scripts of compilers.
g++.py and gcc.py included in this package are wrapper script of **cxxtags** and compilers.
This generate tag database
and run compilers. You can use this script like below


                $ env CXXTAGS_DB_DST=`pwd`/_db g++.py -O a.cpp
                
or

                $ env CXXTAGS_DB_DST=`pwd`/_db make CXX=g++.py


### 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 #8 and column #12 in file b.c is declared.
invoke this command

                $ cxxtags_query def _db b.c 8 12

If b.c is like this


         int func()
         {
             return 1;
         }

         int main()
         {
             return func() + 1;
         }


you will get output linke this.

                func|/devel/cxxtags/src/b.c|1|5|int func()


Commands
------------------------

### cxxtags
Generates a database file.

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

* -e  
  * Specify directories that contains source/header files that you don't want to generate the tags. Directories are separated by ':' like "/usr/include:/usr/local/include".

Compiler arguments are passed to clang. To get precise information you need to pass correct arguments just like you compile the source.

### cxxtags\_query
perform a query to the database.

    usage: cxxtags_query query_type[decl/def/ref/override/overriden] database_dir item_name file_name line_no column_no'
         : cxxtags_query query_type[name]                                 database_dir item_name'

* query\_type: Specify the type of query. Listed below are acceptable.  
    * decl: Run query information about **declared** location of a specified item.
    * def: Run query information about **defined** location of a specified item.  
    * ref: Run query information about **refered** location of a specified item. 
    * override: Run query information about items that a specified item overrides.
    * overriden: Run query information about items that is overriden by a specified item.
    * name: Search information about all items named *item\_name* in database.
* database\_dir: Database directory generated by **cxxtags** command.  
* item\_name: Specify the name of the item that you want to inspect.  
* line\_no: line number.
* column\_no: column number.

{'fraction_non_alphanumeric': 0.10583941605839416, 'fraction_numerical': 0.0056772100567721, 'mean_word_length': 2.749524895477005, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '994392', 'n_tokens_mistral': 2888, 'n_tokens_neox': 2762, 'n_words': 1148}