1=================== 2Clang-Include-Fixer 3=================== 4 5.. contents:: 6 7One of the major nuisances of C++ compared to other languages is the manual 8management of ``#include`` directives in any file. 9:program:`clang-include-fixer` addresses one aspect of this problem by providing 10an automated way of adding ``#include`` directives for missing symbols in one 11translation unit. 12 13While inserting missing ``#include``, :program:`clang-include-fixer` adds 14missing namespace qualifiers to all instances of an unidentified symbol if 15the symbol is missing some prefix namespace qualifiers. 16 17Setup 18===== 19 20To use :program:`clang-include-fixer` two databases are required. Both can be 21generated 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 28Ideally both databases (``compile_commands.json`` and 29``find_all_symbols_db.yaml``) are linked into the root of the source tree they 30correspond to. Then the :program:`clang-include-fixer` can automatically pick 31them 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, 33so only implementation files can be handled by tools. 34 35.. _How To Setup Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html 36 37Creating a Symbol Index From a Compilation Database 38--------------------------------------------------- 39 40The include fixer contains :program:`find-all-symbols`, a tool to create a 41symbol database in YAML format from a compilation database by parsing all 42source files listed in it. The following list of commands shows how to set up a 43database 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 60Integrate with Vim 61------------------ 62To run `clang-include-fixer` on a potentially unsaved buffer in Vim. Add the 63following 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 69This 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 71key. The `<leader> key 72<http://vim.wikia.com/wiki/Mapping_keys_in_Vim_-_Tutorial_(Part_3)#Map_leader>`_ 73is a reference to a specific key defined by the mapleader variable and is bound 74to backslash by default. 75 76Make 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 81You can customize the number of headers being shown by setting 82``let g:clang_include_fixer_maximum_suggested_headers=5`` 83 84Customized 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 110See ``clang-include-fixer.py`` for more details. 111 112Integrate with Emacs 113-------------------- 114To run `clang-include-fixer` on a potentially unsaved buffer in Emacs. 115Ensure that Emacs finds ``clang-include-fixer.el`` by adding the directory 116containing the file to the ``load-path`` and requiring the `clang-include-fixer` 117in 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 124Within Emacs the tool can be invoked with the command 125``M-x clang-include-fixer``. This will insert the header that defines the 126first undefined symbol; if there is more than one header that would define the 127symbol, the user is prompted to select one. 128 129To include the header that defines the symbol at point, run 130``M-x clang-include-fixer-at-point``. 131 132Make 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 138How it Works 139============ 140 141To get the most information out of Clang at parse time, 142:program:`clang-include-fixer` runs in tandem with the parse and receives 143callbacks from Clang's semantic analysis. In particular it reuses the existing 144support for typo corrections. Whenever Clang tries to correct a potential typo 145it emits a callback to the include fixer which then looks for a corresponding 146file. At this point rich lookup information is still available, which is not 147available in the AST at a later stage. 148 149The identifier that should be typo corrected is then sent to the database, if a 150header file is returned it is added as an include directive at the top of the 151file. 152 153Currently :program:`clang-include-fixer` only inserts a single include at a 154time to avoid getting caught in follow-up errors. If multiple `#include` 155additions are desired the program can be rerun until a fix-point is reached. 156