Creating a Symbol Index From a Compilation Database¶

The include fixer contains find-all-symbols, a tool to create a symbol database in YAML format from a compilation database by parsing all source files listed in it. The following list of commands shows how to set up a database for LLVM, any project built by CMake should follow similar steps.

$ cd path/to/llvm-build
$ ninja find-all-symbols // build find-all-symbols tool.
$ ninja clang-include-fixer // build clang-include-fixer tool.
$ ls compile_commands.json # Make sure compile_commands.json exists.
  compile_commands.json
$ path/to/llvm/source/tools/clang/tools/extra/include-fixer/find-all-symbols/tool/run-find-all-symbols.py
  ... wait as clang indexes the code base ...
$ ln -s $PWD/find_all_symbols_db.yaml path/to/llvm/source/ # Link database into the source tree.
$ ln -s $PWD/compile_commands.json path/to/llvm/source/ # Also link compilation database if it's not there already.
$ cd path/to/llvm/source
$ /path/to/clang-include-fixer -db=yaml path/to/file/with/missing/include.cpp
  Added #include "foo.h"

Integrate with Vim¶

To run clang-include-fixer on a potentially unsaved buffer in Vim. Add the following key binding to your .vimrc:

noremap <leader>cf :pyf path/to/llvm/source/tools/clang/tools/extra/include-fixer/tool/clang-include-fixer.py<cr>

This enables clang-include-fixer for NORMAL and VISUAL mode. Change <leader>cf to another binding if you need clang-include-fixer on a different key. The <leader> key is a reference to a specific key defined by the mapleader variable and is bound to backslash by default.

Make sure vim can find clang-include-fixer:

• Add the path to clang-include-fixer to the PATH environment variable.
• Or set g:clang_include_fixer_path in vimrc: let g:clang_include_fixer_path=path/to/clang-include-fixer

You can customize the number of headers being shown by setting let g:clang_include_fixer_maximum_suggested_headers=5

Customized settings in .vimrc:

• let g:clang_include_fixer_path = "clang-include-fixer"

  Set clang-include-fixer binary file path.

• let g:clang_include_fixer_maximum_suggested_headers = 3

  Set the maximum number of #includes to show. Default is 3.

• let g:clang_include_fixer_increment_num = 5

  Set the increment number of #includes to show every time when pressing m. Default is 5.

• let g:clang_include_fixer_jump_to_include = 0

  Set to 1 if you want to jump to the new inserted #include line. Default is 0.

• let g:clang_include_fixer_query_mode = 0

  Set to 1 if you want to insert #include for the symbol under the cursor. Default is 0. Compared to normal mode, this mode won’t parse the source file and only search the sysmbol from database, which is faster than normal mode.

See clang-include-fixer.py for more details.

Integrate with Emacs¶

To run clang-include-fixer on a potentially unsaved buffer in Emacs. Ensure that Emacs finds clang-include-fixer.el by adding the directory containing the file to the load-path and requiring the clang-include-fixer in your .emacs:

(add-to-list 'load-path "path/to/llvm/source/tools/clang/tools/extra/include-fixer/tool/"
(require 'clang-include-fixer)

Within Emacs the tool can be invoked with the command M-x clang-include-fixer. This will insert the header that defines the first undefined symbol; if there is more than one header that would define the symbol, the user is prompted to select one.

To include the header that defines the symbol at point, run M-x clang-include-fixer-at-point.

Make sure Emacs can find clang-include-fixer:

• Either add the parent directory of clang-include-fixer to the PATH environment variable, or customize the Emacs user option clang-include-fixer-executable to point to the file name of the program.