| =================== |
| Clang-Include-Fixer |
| =================== |
| |
| .. contents:: |
| |
| One of the major nuisances of C++ compared to other languages is the manual |
| management of ``#include`` directives in any file. |
| :program:`clang-include-fixer` addresses one aspect of this problem by providing |
| an automated way of adding ``#include`` directives for missing symbols in one |
| translation unit. |
| |
| Setup |
| ===== |
| |
| To use :program:`clang-include-fixer` two databases are required. Both can be |
| generated with existing tools. |
| |
| - Compilation database. Contains the compiler commands for any given file in a |
| project and can be generated by CMake, see `How To Setup Tooling For LLVM`_. |
| - Symbol index. Contains all symbol information in a project to match a given |
| identifier to a header file. |
| |
| Ideally both databases (``compile_commands.json`` and |
| ``find_all_symbols_db.yaml``) are linked into the root of the source tree they |
| correspond to. Then the :program:`clang-include-fixer` can automatically pick |
| them up if called with a source file from that tree. Note that by default |
| ``compile_commands.json`` as generated by CMake does not include header files, |
| so only implementation files can be handled by tools. |
| |
| .. _How To Setup Tooling For LLVM: http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html |
| |
| Creating a Symbol Index From a Compilation Database |
| ------------------------------------------------------ |
| |
| The include fixer contains :program:`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. |
| |
| .. code-block:: console |
| |
| $ 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``: |
| |
| .. code-block:: console |
| |
| map ,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 ``,cf`` to |
| another binding if you need clang-include-fixer on a different key. |
| |
| Make sure vim can find :program:`clang-include-fixer`: |
| |
| - Add the path to :program:`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`` |
| |
| See ``clang-include-fixer.py`` for more details. |
| |
| How it Works |
| ============ |
| |
| To get the most information out of clang at parse time, |
| :program:`clang-include-fixer` runs in tandem with the parse and receives |
| callbacks from Clang's semantic analysis. In particular it reuses the existing |
| support for typo corrections. Whenever Clang tries to correct a potential typo |
| it emits a callback to the include fixer which then looks for a corresponding |
| file. At this point rich lookup information is still available, which is not |
| available in the AST at a later stage. |
| |
| The identifier that should be typo corrected is then sent to the database, if a |
| header file is returned it is added as an include directive at the top of the |
| file. |
| |
| Currently :program:`clang-include-fixer` only inserts a single include at a |
| time to avoid getting caught in follow-up errors. If multiple `#include` |
| additions are desired the program can be rerun until a fix-point is reached. |