clang-tools-extra/docs/clang-include-fixer.rst

   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.