| 1 |
=================== |
| 2 |
Clang-Include-Fixer |
| 3 |
=================== |
| 4 |
|
| 5 |
.. contents:: |
| 6 |
|
| 7 |
One of the major nuisances of C++ compared to other languages is the manual |
| 8 |
management of ``#include`` directives in any file. |
| 9 |
:program:`clang-include-fixer` addresses one aspect of this problem by providing |
| 10 |
an automated way of adding ``#include`` directives for missing symbols in one |
| 11 |
translation unit. |
| 12 |
|
| 13 |
While inserting missing ``#include``, :program:`clang-include-fixer` adds |
| 14 |
missing namespace qualifiers to all instances of an unidentified symbol if |
| 15 |
the symbol is missing some prefix namespace qualifiers. |
| 16 |
|
| 17 |
Setup |
| 18 |
===== |
| 19 |
|
| 20 |
To use :program:`clang-include-fixer` two databases are required. Both can be |
| 21 |
generated with existing tools. |
| 22 |
|
| 23 |
- Compilation database. Contains the compiler commands for any given file in a |
| 24 |
project and can be generated by CMake, see `How To Setup Tooling For LLVM`_. |
| 25 |
- Symbol index. Contains all symbol information in a project to match a given |
| 26 |
identifier to a header file. |
| 27 |
|
| 28 |
Ideally both databases (``compile_commands.json`` and |
| 29 |
``find_all_symbols_db.yaml``) are linked into the root of the source tree they |
| 30 |
correspond to. Then the :program:`clang-include-fixer` can automatically pick |
| 31 |
them up if called with a source file from that tree. Note that by default |
| 32 |
``compile_commands.json`` as generated by CMake does not include header files, |
| 33 |
so only implementation files can be handled by tools. |
| 34 |
|
| 35 |
.. _How To Setup Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html |
| 36 |
|
| 37 |
Creating a Symbol Index From a Compilation Database |
| 38 |
--------------------------------------------------- |
| 39 |
|
| 40 |
The include fixer contains :program:`find-all-symbols`, a tool to create a |
| 41 |
symbol database in YAML format from a compilation database by parsing all |
| 42 |
source files listed in it. The following list of commands shows how to set up a |
| 43 |
database for LLVM, any project built by CMake should follow similar steps. |
| 44 |
|
| 45 |
.. code-block:: console |
| 46 |
|
| 47 |
$ cd path/to/llvm-build |
| 48 |
$ ninja find-all-symbols // build find-all-symbols tool. |
| 49 |
$ ninja clang-include-fixer // build clang-include-fixer tool. |
| 50 |
$ ls compile_commands.json # Make sure compile_commands.json exists. |
| 51 |
compile_commands.json |
| 52 |
$ path/to/llvm/source/clang-tools-extra/clang-include-fixer/find-all-symbols/tool/run-find-all-symbols.py |
| 53 |
... wait as clang indexes the code base ... |
| 54 |
$ ln -s $PWD/find_all_symbols_db.yaml path/to/llvm/source/ # Link database into the source tree. |
| 55 |
$ ln -s $PWD/compile_commands.json path/to/llvm/source/ # Also link compilation database if it's not there already. |
| 56 |
$ cd path/to/llvm/source |
| 57 |
$ /path/to/clang-include-fixer -db=yaml path/to/file/with/missing/include.cpp |
| 58 |
Added #include "foo.h" |
| 59 |
|
| 60 |
Integrate with Vim |
| 61 |
------------------ |
| 62 |
To run `clang-include-fixer` on a potentially unsaved buffer in Vim. Add the |
| 63 |
following key binding to your ``.vimrc``: |
| 64 |
|
| 65 |
.. code-block:: console |
| 66 |
|
| 67 |
noremap <leader>cf :pyf path/to/llvm/source/clang-tools-extra/clang-include-fixer/tool/clang-include-fixer.py<cr> |
| 68 |
|
| 69 |
This enables `clang-include-fixer` for NORMAL and VISUAL mode. Change |
| 70 |
`<leader>cf` to another binding if you need clang-include-fixer on a different |
| 71 |
key. The `<leader> key |
| 72 |
<http://vim.wikia.com/wiki/Mapping_keys_in_Vim_-_Tutorial_(Part_3)#Map_leader>`_ |
| 73 |
is a reference to a specific key defined by the mapleader variable and is bound |
| 74 |
to backslash by default. |
| 75 |
|
| 76 |
Make sure vim can find :program:`clang-include-fixer`: |
| 77 |
|
| 78 |
- Add the path to :program:`clang-include-fixer` to the PATH environment variable. |
| 79 |
- Or set ``g:clang_include_fixer_path`` in vimrc: ``let g:clang_include_fixer_path=path/to/clang-include-fixer`` |
| 80 |
|
| 81 |
You can customize the number of headers being shown by setting |
| 82 |
``let g:clang_include_fixer_maximum_suggested_headers=5`` |
| 83 |
|
| 84 |
Customized settings in `.vimrc`: |
| 85 |
|
| 86 |
- ``let g:clang_include_fixer_path = "clang-include-fixer"`` |
| 87 |
|
| 88 |
Set clang-include-fixer binary file path. |
| 89 |
|
| 90 |
- ``let g:clang_include_fixer_maximum_suggested_headers = 3`` |
| 91 |
|
| 92 |
Set the maximum number of ``#includes`` to show. Default is 3. |
| 93 |
|
| 94 |
- ``let g:clang_include_fixer_increment_num = 5`` |
| 95 |
|
| 96 |
Set the increment number of #includes to show every time when pressing ``m``. |
| 97 |
Default is 5. |
| 98 |
|
| 99 |
- ``let g:clang_include_fixer_jump_to_include = 0`` |
| 100 |
|
| 101 |
Set to 1 if you want to jump to the new inserted ``#include`` line. Default is |
| 102 |
0. |
| 103 |
|
| 104 |
- ``let g:clang_include_fixer_query_mode = 0`` |
| 105 |
|
| 106 |
Set to 1 if you want to insert ``#include`` for the symbol under the cursor. |
| 107 |
Default is 0. Compared to normal mode, this mode won't parse the source file |
| 108 |
and only search the symbol from database, which is faster than normal mode. |
| 109 |
|
| 110 |
See ``clang-include-fixer.py`` for more details. |
| 111 |
|
| 112 |
Integrate with Emacs |
| 113 |
-------------------- |
| 114 |
To run `clang-include-fixer` on a potentially unsaved buffer in Emacs. |
| 115 |
Ensure that Emacs finds ``clang-include-fixer.el`` by adding the directory |
| 116 |
containing the file to the ``load-path`` and requiring the `clang-include-fixer` |
| 117 |
in your ``.emacs``: |
| 118 |
|
| 119 |
.. code-block:: console |
| 120 |
|
| 121 |
(add-to-list 'load-path "path/to/llvm/source/clang-tools-extra/clang-include-fixer/tool/" |
| 122 |
(require 'clang-include-fixer) |
| 123 |
|
| 124 |
Within Emacs the tool can be invoked with the command |
| 125 |
``M-x clang-include-fixer``. This will insert the header that defines the |
| 126 |
first undefined symbol; if there is more than one header that would define the |
| 127 |
symbol, the user is prompted to select one. |
| 128 |
|
| 129 |
To include the header that defines the symbol at point, run |
| 130 |
``M-x clang-include-fixer-at-point``. |
| 131 |
|
| 132 |
Make sure Emacs can find :program:`clang-include-fixer`: |
| 133 |
|
| 134 |
- Either add the parent directory of :program:`clang-include-fixer` to the PATH |
| 135 |
environment variable, or customize the Emacs user option |
| 136 |
``clang-include-fixer-executable`` to point to the file name of the program. |
| 137 |
|
| 138 |
How it Works |
| 139 |
============ |
| 140 |
|
| 141 |
To get the most information out of Clang at parse time, |
| 142 |
:program:`clang-include-fixer` runs in tandem with the parse and receives |
| 143 |
callbacks from Clang's semantic analysis. In particular it reuses the existing |
| 144 |
support for typo corrections. Whenever Clang tries to correct a potential typo |
| 145 |
it emits a callback to the include fixer which then looks for a corresponding |
| 146 |
file. At this point rich lookup information is still available, which is not |
| 147 |
available in the AST at a later stage. |
| 148 |
|
| 149 |
The identifier that should be typo corrected is then sent to the database, if a |
| 150 |
header file is returned it is added as an include directive at the top of the |
| 151 |
file. |
| 152 |
|
| 153 |
Currently :program:`clang-include-fixer` only inserts a single include at a |
| 154 |
time to avoid getting caught in follow-up errors. If multiple `#include` |
| 155 |
additions are desired the program can be rerun until a fix-point is reached. |