C family Semantic Completion through libclang

Preface

Even though for the vast majority of users the clangd is a better option, for projects that use unity builds (for example) will have to stay on the libclang completer. For more information, see clangd/clangd#45.

Quick install instructions

1. Go into your YouCompleteMe directory and rebuild YCM while passing --clang-completer to the install.py script:

   python3 install.py --clang-completer

2. If you previously had clangd-based completer previously enabled, disable it in your [vimrc][]:

   let g:ycm_use_clangd = 0

3. To take advantage of support for unity builds, you will need a custom .ycm_extra_conf.py. The ycmd README has detailed instructions on what a .ycm_extra_conf.py can contain. A very simple example:

def Settings(**kwargs):
  return { 'flags': list_of_compiler_flags,
           'override_filename': path_to_actually_compiled_file }

Amendments to the Full Installation Guide

If for some reason the quick start did not work for you (for example, you're on some exotic OS/CPU), you'll have to follow the full installation guide, but with the step 3 and 4 changed.

Step 3 - Download libclang

Download the latest version of libclang. Clang is an open-source compiler that can compile C-family languages. The libclang library it provides is used to power the YCM semantic completion engine for those languages. YCM is designed to work with libclang version 9.0.0 or higher.

You can use the system libclang only if you are sure it is version 9.0.0 or higher, otherwise don't. Even if it is, we recommend using the official binaries from llvm.org if at all possible. Make sure you download the correct archive file for your OS.

We STRONGLY recommend AGAINST use of the system libclang or clangd instead of the upstream compiled binaries. Random things may break. Save yourself the hassle and use the upstream pre-built libclang or clangd.

Step 4 - Recompile ycm_core with libclang support

We'll assume you downloaded a binary distribution of LLVM+Clang from llvm.org in step 3 and that you extracted the archive file to folder ~/ycm_temp/llvm_root_dir (with bin, lib, include etc. folders right inside that folder). On Windows, you can extract the files from the LLVM+Clang installer using 7-zip.

NOTE: This only works with a downloaded LLVM binary package, not a custom-built LLVM! See docs below for EXTERNAL_LIBCLANG_PATH when using a custom LLVM build.

With that in mind, run the following command in the ycm_build directory:

cmake -G "<generator>" -DPATH_TO_LLVM_ROOT=~/ycm_temp/llvm_root_dir . ~/.vim/bundle/YouCompleteMe/third_party/ycmd/cpp

with <generator> replaced as in the other full installation guide.

Now that configuration files have been generated, compile the libraries using this command:

cmake --build . --target ycm_core --config Release

The --config Release part is specific to Windows and will be ignored on a Unix OS.

For those who want to use the system version of libclang, you would pass -DUSE_SYSTEM_LIBCLANG=ON to cmake instead of the -DPATH_TO_LLVM_ROOT=... flag.

NOTE: We STRONGLY recommend AGAINST use of the system libclang instead of the upstream compiled binaries. Random things may break. Save yourself the hassle and use the upstream pre-built libclang.

You could also force the use of a custom libclang library with -DEXTERNAL_LIBCLANG_PATH=/path/to/libclang.so flag (the library would end with .dylib on macOS). Again, this flag would be used instead of the other flags. If you compiled LLVM from source, this is the flag you should be using.

Running the cmake command will also place the libclang.[so|dylib|dll] in the YouCompleteMe/third_party/ycmd folder for you if you compiled with clang support (it needs to be there for YCM to work).