Full installation guide for YMC

Posted 2020-10-02

Full Installation Guide

These are the steps necessary to get YCM working on a Unix OS and on Windows.

Note to Windows users: we assume that you are running the cmd.exe command prompt and that the needed executables are in the PATH environment variable. Do not just copy the shell commands. Replace ~ by %USERPROFILE% in them and use the right Vim home directory. It should be vimfiles by default instead of .vim.

See the FAQ if you have any issues.

Remember: YCM is a plugin with a compiled component. If you update YCM using Vundle and the ycm_core library APIs have changed (happens rarely), YCM will notify you to recompile it. You should then rerun the install process.

Please follow the instructions carefully. Read EVERY WORD.

1. Ensure that your version of Vim is at least 7.4.1578 and that it has support for Python 2 or Python 3 scripting.

   Inside Vim, type :version. Look at the first two to three lines of output; it should say Vi IMproved X.Y, where X.Y is the major version of vim. If your version is greater than 7.4, then you‘re all set. If your version is 7.4 then look below that where it says, Included patches: 1-Z, where Z will be some number. That number needs to be 1578 or higher.

   If your version of Vim is not recent enough, you may need to compile Vim from source (don‘t worry, it‘s easy).

   After you have made sure that you have Vim 7.4.1578+, type the following in Vim: :echo has(‘python‘) || has(‘python3‘). The output should be 1. If it‘s 0, then get a version of Vim with Python support.

   On Windows, check also if your Vim architecture is 32 or 64-bit. This is critical because it must match the Python and the YCM libraries architectures. We recommend using a 64-bit Vim.

2. Install YCM with Vundle (or Pathogen, but Vundle is a better idea). With Vundle, this would mean adding a Plugin ‘Valloric/YouCompleteMe‘ line to your vimrc.

   If you don‘t install YCM with Vundle, make sure you have run git submodule update --init --recursive after checking out the YCM repository (Vundle will do this for you) to fetch YCM‘s dependencies.

3. [Complete this step ONLY if you care about semantic completion support for C-family languages. Otherwise it‘s not necessary.]

   Download the latest version of libclang. Clang is an open-source compiler that can compile C/C++/Objective-C/Objective-C++. 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 3.9 or higher.

   You can use the system libclang only if you are sure it is version 3.9 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 instead of the upstream compiled binaries. Random things may break. Save yourself the hassle and use the upstream pre-built libclang.

4. Compile the ycm_core library that YCM needs. This library is the C++ engine that YCM uses to get fast completions.

   You will need to have cmake installed in order to generate the required makefiles. Linux users can install cmake with their package manager (sudo apt-get install cmake for Ubuntu) whereas other users can download and install cmake from its project site. Mac users can also get it through Homebrew with brew install cmake.

   On a Unix OS, you need to make sure you have Python headers installed. On a Debian-like Linux distro, this would be sudo apt-get install python-dev python3-dev. On Mac they should already be present.

   On Windows, you need to download and install Python 2 or Python 3. Pick the version corresponding to your Vim architecture. You will also need Microsoft Visual C++ (MSVC) to build YCM. You can obtain it by installing Visual Studio. MSVC 12 (Visual Studio 2013), 14 (2015), and 15 (2017) are officially supported.

   Here we‘ll assume you installed YCM with Vundle. That means that the top-level YCM directory is in ~/.vim/bundle/YouCompleteMe.

   We‘ll create a new folder where build files will be placed. Run the following:

   cd ~
   mkdir ycm_build
   cd ycm_build
   

   Now we need to generate the makefiles. If you DON‘T care about semantic support for C-family languages, run the following command in the ycm_build directory:

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

   where <generator> is Unix Makefiles on Unix systems and one of the following Visual Studio generators on Windows:

   • Visual Studio 12 Win64
   • Visual Studio 14 Win64
   • Visual Studio 15 Win64

   Remove the Win64 part in these generators if your Vim architecture is 32-bit.

   For those who want to use the system version of boost, you would pass -DUSE_SYSTEM_BOOST=ON to cmake. This may be necessary on some systems where the bundled version of boost doesn‘t compile out of the box.

   NOTE: We STRONGLY recommend AGAINST use of the system boost instead of the bundled version of boost. Random things may break. Save yourself the hassle and use the bundled version of boost.

   If you DO care about semantic support for C-family languages, then your cmake call will be a bit more complicated. 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
   

   where <generator> is replaced like above.

   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 a Mac). 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).

5. Set up support for additional languages, as desired:

   • C# support: install Mono on non-Windows platforms. Navigate to YouCompleteMe/third_party/ycmd/third_party/OmniSharpServer and run

     msbuild /property:Configuration=Release /property:TargetFrameworkVersion=v4.5
     

     Replace msbuild by xbuild if msbuild is not available. On Windows, be sure that the build utility msbuild is in your PATH.

   • Go support: install Go and add it to your path. Navigate to YouCompleteMe/third_party/ycmd/third_party/gocode and run go build.

   • TypeScript support: as with the quick installation, simply npm install -g typescript after successfully installing Node.js and npm.

   • javascript support: install Node.js and npm. Then navigate to YouCompleteMe/third_party/ycmd/third_party/tern_runtime and run npm install --production

   • Rust support: install Rust. Navigate to YouCompleteMe/third_party/ycmd/third_party/racerd and run cargo build --release.

That‘s it. You‘re done. Refer to the User Guide section on how to use YCM. Don‘t forget that if you want the C-family semantic completion engine to work, you will need to provide the compilation flags for your project to YCM. It‘s all in the User Guide.

YCM comes with sane defaults for its options, but you still may want to take a look at what‘s available for configuration. There are a few interesting options that are conservatively turned off by default that you may want to turn on.