kbobyrev created this revision. kbobyrev added reviewers: ioeric, ilya-biryukov, sammccall. kbobyrev added a project: clang-tools-extra. Herald added subscribers: kadircet, arphaman, jkorous, MaskRay.
https://reviews.llvm.org/D51297 Files: clang-tools-extra/docs/clangd-vim.rst clang-tools-extra/docs/index.rst clang/docs/ClangFormat.rst
Index: clang/docs/ClangFormat.rst =================================================================== --- clang/docs/ClangFormat.rst +++ clang/docs/ClangFormat.rst @@ -94,6 +94,16 @@ Available style options are described in :doc:`ClangFormatStyleOptions`. +Clangd Integration +================== + +Most editors have :program:`Clangd <https://clang.llvm.org/extra/clangd.html>`_ +integration and :program:`Clang-Format` can be invoked with the formatting +request. It is advised to use :program:`Clangd` editor integration to get the +best user experience. A complete example of setting up :program:`Clangd` for +:program:`vim`: `Clangd Vim integration +<https://clang.llvm.org/extra/clangd-vim.html>`_. + Vim Integration =============== Index: clang-tools-extra/docs/index.rst =================================================================== --- clang-tools-extra/docs/index.rst +++ clang-tools-extra/docs/index.rst @@ -26,6 +26,7 @@ pp-trace clang-rename clangd + clangd-vim clang-doc Index: clang-tools-extra/docs/clangd-vim.rst =================================================================== --- /dev/null +++ clang-tools-extra/docs/clangd-vim.rst @@ -0,0 +1,171 @@ +====================== +Clangd Vim integration +====================== + +.. contents:: + +.. toctree:: + :maxdepth: 1 + +:program:`Clangd` can be used within (Neo)Vim. + +=============== +Vim LSP plugins +=============== + +There are several existing LSP plugins for (Neo)Vim, most notably: + +* `LanguageClient-neovim <https://github.com/autozimu/LanguageClient-neovim>`_ + is probably the one getting most traction at the moment. It supports more + features than its counterparts and also works better for NeoVim users + (despite the name it also works for regular Vim). +* `vim-lsc <https://github.com/natebosch/vim-lsc>`_ provides convenient key + bindings and has a lot of options, but lacks few important features such as + `code formatting <https://github.com/natebosch/vim-lsc/issues/98>`_ which can + be used instead to invoke + `Clang-Format <https://clang.llvm.org/docs/ClangFormat.html>`_. +* `vim-lsp <https://github.com/prabirshrestha/vim-lsp>`_ is another (Neo)Vim + async plugin which offers LSP integration, but it also lacks several features + like `code actions <https://github.com/prabirshrestha/vim-lsp/issues/155>`_ ( + needed for applying Fix-Its). + +Given that `LanguageClient-neovim` supports more features at the moment, this +document will focus on setting up this plugin in your (Neo)Vim. + +Setting up `LanguageClient-neovim` +================================== + +You can see the generic setup guide in `plugin's README +<https://github.com/autozimu/LanguageClient-neovim#quick-start>`_. +Here we will focus on a way to build a complete :program:`Clangd` setup. + +The recommended way of installing plugins is `vim-plug +<https://github.com/junegunn/vim-plug>`_ which offers various ``Plug`` options +used for easier plugin setup. + +.. code-block:: vim + + Plug 'autozimu/LanguageClient-neovim', { + \ 'branch': 'next', + \ 'do': 'bash install.sh', + \ } + +Next step is to specify :program:`Clangd` invokation command. The easiest way to +do that is just telling ``LanguageClient-neovim`` to run :program:`clangd` +binary (assuming it is already in the ``$PATH``): + +.. code-block:: vim + + let g:LanguageClient_serverCommands = { + \ 'cpp': ['clangd'], + \ } + +That's all, this is a complete ``LanguageClient-neovim`` setup! However, it is +recommended to use few other plugins and setup custom key bindings for better +user experience. Please refer to the `Recommended Settings` section. + +Recommended settings +==================== + +``LanguageClient-neovim`` has multiple options for the completion management: + +* `deoplete <https://github.com/Shougo/deoplete.nvim>`_ +* `ncm2 <https://github.com/ncm2/ncm2>`_ +* Vim's ``omnifunc`` (used by default) + +For best experience, it is advised to use ``deoplete``. This is one of the most +advanced completion manager which is very flexible and has numerous nice-to-have +features such as snippets integration (if you are a +`UltiSnips <https://github.com/SirVer/ultisnips>`_ user). You can install it via + +.. code-block:: vim + + if has('nvim') + Plug 'Shougo/deoplete.nvim', { 'do': ':UpdateRemotePlugins' } + else + Plug 'Shougo/deoplete.nvim' + Plug 'roxma/nvim-yarp' + Plug 'roxma/vim-hug-neovim-rpc' + endif + + let g:deoplete#enable_at_startup = 1 + +Also, by default ``LanguageClient-neovim`` comes without key bindings. Typing +``call LanguageClient#textDocument_rename()`` each time user would like to +rename a symbol is not the best experience. Suggested way of a consistent setup +with the `<leader> key +<http://vim.wikia.com/wiki/Mapping_keys_in_Vim_-_Tutorial_(Part_3)#Map_leader>`_: + +.. code-block:: vim + + function SetLSPShortcuts() + nnoremap <leader>ld :call LanguageClient#textDocument_definition()<CR> + nnoremap <leader>lr :call LanguageClient#textDocument_rename()<CR> + nnoremap <leader>lf :call LanguageClient#textDocument_formatting()<CR> + nnoremap <leader>lt :call LanguageClient#textDocument_typeDefinition()<CR> + nnoremap <leader>lx :call LanguageClient#textDocument_references()<CR> + nnoremap <leader>la :call LanguageClient_workspace_applyEdit()<CR> + nnoremap <leader>lc :call LanguageClient#textDocument_completion()<CR> + nnoremap <leader>lm :call LanguageClient#LanguageClient_contextMenu()<CR> + nnoremap <leader>lh :call LanguageClient#textDocument_hover()<CR> + nnoremap <leader>ls :call LanguageClient_textDocument_documentSymbol()<CR> + endfunction() + + augroup LSP + autocmd! + autocmd FileType cpp,c call SetLSPShortcuts() + augroup END + +This will ensure that LSP shortcuts are enabled only for source files in C++ or +C. If you use other language servers for ``LanguageClient-neovim``, just add +more filetypes to the ``autocmd``. + +Another great addition to the setup is `FZF <https://github.com/junegunn/fzf>`_ +integration. It will enable user to use fuzzy matching for something like +searching through workspace or document symbols. For ``FZF``, +``LanguageClient-neovim`` will take care of the configuration. All user has to +do is to install the plugin: + +.. code-block:: vim + + Plug 'junegunn/fzf', { 'dir': '~/.fzf', 'do': './install --all' } + Plug 'junegunn/fzf.vim' + +`echodoc <https://github.com/Shougo/echodoc.vim>`_ can handle the function +signatures displaying: + +.. code-block:: vim + + Plug 'Shougo/echodoc.vim' + + set cmdheight=2 + let g:echodoc#enable_at_startup = 1 + let g:echodoc#type = 'signature' + + +``signcolumn`` will appear each time :program:`Clangd` sends a warning or +provides a diagnostic and the text will be shifted by one column each time +``signcolumn`` is triggered. To prevent this shift and always show the +``signcolumn``, use + +.. code-block:: vim + + " Always draw the signcolumn. + set signcolumn=yes + + +For documentation, see `LanguageClient.txt +<https://github.com/autozimu/LanguageClient-neovim/blob/next/doc/LanguageClient.txt>` +or simply call ``:help LanguageClient``. + +Troubleshooting +=============== + +FIXME(kbobyrev): Add references on how to write logs, errs and mirror files to +/tmp/ and how to report failures. + +Bonus: building static index +============================ + +FIXME(kbobyrev): Explain the process of setting up global static index with the +:program:`global-symbol-builder.`
_______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
