Introduction

The “Editor War” (Editor War) is an endless debate between Vim and Emacs. But in my opinion, as long as the editor is configured and put into daily production, die-hard fans of either Vim or Emacs can gain great experience. The reason for this thought is that I had a painful experiment with Vim. In particular, the configuration of YouCompleteMe, a plugin whose name even sounds a bit ambiguous, did its best to make me feel its maliciousness.

While this article does not faithfully recreate the whole process of falling into the pits, I have tuned the order of operations, but I have kept the description of where the problems might occur and also explained the solutions.

Vim version & configuration environment

The version of Vim I want to compile and install is the latest 8.1 in the official Github repository

The installed OS environment is Debian GNU/Linux provided by Windows Subsystem for Linux in Windows 10 version 17134. So Debian here is the stable version of 9/Stretch.

Debian 9 provided by Windows Subsystem for Linux (hereafter WSL) has certain peculiarities, mainly in the fact that the environment is more streamlined and clean compared to larger distributions, but this does not affect how the installation process of Vim is represented.

Compiling and installing Vim 8

Why compile and install

In fact, except in the case of a missing package, downloading and installing software from a source should be the preferred option. The package manager will take care of the dependencies properly and will not tend to dirty up the system. So the recommended approach on Debian-based distributions should be.

1

sudo apt install vim

However, some Vim plugins (such as YouCompleteMe for this article) require Vim support for Python which are not enabled by default.

So how do you enable it? This article uses a compiled installation with the option to enable Python support to get a Vim that meets the requirements. Other solutions such as vim-nox are out of scope.

Downloading Vim source code

Install Git first. While it is possible to go directly to the official Vim repository to get the source code, Git should be the first to install, given that most Vim plugin managers also rely on Git to install and upgrade their plugins.

1

sudo apt install git

You don’t need to do a complicated configuration of Git, although you’ll have a lot of need to do so in the future. Here we’ll just use simple commands of Git to get the source code.

1

git clone https://github.com/vim/vim

Not surprisingly, this will take a few seconds of waiting.

Compiling Vim to enable Python 3 support

The need to enable Python support was stated earlier when explaining the reason for compiling and installing, so I won’t repeat it here, but first install Python 3 with its support library libpython3-dev

1

sudo apt install python3 libpython3-dev

In theory, major distributions such as Debian should already include Python3 support, but WSL does not, so install it as a supplement.

Go back to the directory where you put the Vim source code and go to the src subdirectory. Before compiling, make sure that the build tools included in build-essential are successfully installed, otherwise you will get an error because you cannot find the build tools.

1

sudo apt-get install build-essential

Once the build tools are ready, you can start compiling and installing. Start the “build triplet”.

1
2
3
4
5
6
7
8

. /configure --with-features=huge \
            --enable-multibyte \
            --enable-python3interp=yes \
            --with-python3-config-dir=/usr/lib/python3.7/config-3.7m-x86_64-linux-gnu \
            --enable-rubyinterp=yes \
            --enable-perlinterp=yes \
            --enable-luainterp=yes \
            --prefix=/usr/local/vim-8.1

For the third and fourth configuration options, I chose to enable Python 3 support and tell you where the config file is located. If you omitted to install libpython3-dev above, the config file may be missing.

Of course, both of these directories will change with the version of Python installed (for example, the installed version is 3.7), so if you get an error, look in the /usr/lib directory for the Python directory and fill in the config field.

If you need Python 2 support, for example if some old plugins still only support Python 2 but there are no other plugins available, you should add.

1
2

--enable-pythoninterp=yes \
--with-python-config-dir=/usr/lib/python2.7/config \

Accordingly, you will need to install Python 2 and libpython2-dev in advance. Note that if you install the required files for Python 3 but incorrectly turn on the enable-pythoninterp option, Vim will fail to enable Python because Python 2 support is turned on and no Python 2 related files are found. So, be careful to install the appropriate version and turn on the appropriate options.

You may also notice that the Ruby, Perl, and Lua support options are turned on, and you can change them accordingly if you are sure you don’t need them.

The directory after -prefix specifies the target directory for the Vim installation.

If you run . /configure and you get an error like this.

1
2
3
4

no terminal library found
checking for tgetent()... configure: error: NOT FOUND!
You need to install a terminal library; for example ncurses.
Or specify the name of the library with -with-tlib.

The solution is to install libncurses5-dev as stated in the error message.

1

sudo apt install libncurses5-dev

If . /configure everything went well, next you just need to execute.

1
2

sudo make
sudo make install

Registering Vim as Editor

Debian has the following usage to register Vim as an editor.

1

sudo update-alternatives --install /usr/bin/editor editor /usr/local/vim-8.1/bin/vim 1

Use the generic softlink chain on vim.

1

sudo ln -s /usr/local/vim-8.1/bin/vim /usr/bin/vim

This allows you to run Vim by typing vim on the command line.

At this point, to ensure that Python support of Vim is enabled as planned, the following command can be verified.

1

vim --version | grep python

Not surprisingly, two of the output results are

1
2

-python
+python3

The presence of a plus sign in front of the item indicates that it is enabled, and the presence of a minus sign means that it is not enabled. So here Python 3 support is successfully enabled.

Installing the YouCompleteMe plugin

YouCompleteMe (YCM for short) is a powerful and malicious auto-completion plugin for Vim. In the issues of YCM Official Repository, its author Valloric takes great pains to remind issues authors to read the official documentation properly, so follow the official Installation Instructions and check out the User Guide after you hit a hole – that’s the process we should stick to next.

The goal of this article is to configure YCM to support auto-completion for C/C++, and other languages are beyond the scope of this article. It is worth mentioning that for C Family semantic autocompletion, it is officially specified that you must read this document.

Installing the vim-plug plugin manager

Although our goal is only to install YCM, the great help of using a plugin manager for future use of Vim should not be overlooked. Here we choose vim-plug, the Vim plugin manager with the second most stars on Github, which supports asynchronous installation.

You need to download the plug.vim file from the repository and put it in the autoload directory.

The autoload folder exists in the ~/.vim directory, and both directories can simply be created if they do not exist.

Edit the ~/.vimrc file (if it doesn’t exist, create a new one) and add a reference to YCM.

1

Plug 'Valloric/YouCompleteMe'

The use of vim-plug is well covered in the official repository in README. Simply put, you can change the content between the single quotes in the line of configuration above to the address of another plugin (in the format of “Username/Plugname “) to reference the plugin.

If you are not familiar with Vim now, you can use nano to make changes to ~/.vimrc.

Installing Clang

For C Family semantic completion, YCM uses the Clang semantic search engine. Although it comes with libclang, the documentation gives the recommendation to compile it yourself to get libclang. This means that it is a prerequisite that Clang is properly configured on this computer.

Clang, being a LLVM based compiler, also requires the LLVM framework system to be installed. You can install it using the software source (the latest version at the time of writing is 6.0).

1

sudo apt install clang-6.0

This is the quickest and easiest way to install Clang + LLVM. If you download the source code separately and compile and install it, it is not really tedious. Of course, LLVM also provides pre-compiled packages for different distributions on the Download Page. So, you can also move the downloaded precompiled package to /usr/local, which is next to the Vim installation directory.

The following version is replaced by xxxxxxx, please refer to the actual downloaded file name.

1

sudo mv /path/to/package/clang+llvm_xxxxxxx /usr/local

Don’t forget to link to clang and clang++.

1
2

sudo ln -s /usr/local/clang+llvm_xxxxxxx/bin/clang /usr/bin/clang
sudo ln -s /usr/local/clang+llvm_xxxxxxx/bin/clang++ /usr/bin/clang++

At this point, Clang is ready. And libclang is quietly hidden in /usr/local/clang+llvm_xxxxxxx/x86_64-linux-gnu/lib.

Installing Cmake

Cmake is the default compiler supported by YCM, so using Cmake to compile YCM is the safest and most secure way. If you don’t install Cmake to compile ycm_core, Vim will give you an error after startup:

1

The ycmd server SHUT DOWN (restart with ':YcmRestartServer'). Unexpected error while loading the YCM core library.

Also, the good news is that Cmake provides the installation script for the shell, just look for your platform in the Download Page and download it. After downloading, you can reach the directory where the script is located, move it to /usr/local, and install it.

1
2

sudo mv /path/to/cmake-x.xx.x-Linux-x86_64.sh /usr/local
sudo /usr/local/.cmake-x.xx.x-Linux-x86_64.sh

x.xx.x refers to the version number, based on the downloaded file.

Enter y to accept the agreement and enter y again when prompted to install to a separate subdirectory of the directory you are in.

So, Cmake is ready to go.

Installing YCM with vim-plug

The YCM installation script requires Cmake to generate some configuration files and compile them by itself, so it will save us a lot of work if we run the installation script after Cmake is installed.

Open Vim, type : to enter command mode, type PlugInstall and enter to confirm. At this point vim-plug starts fetching each plugin through Git and handling the installation directory properly. Only one plugin is currently referenced, so there should only be one YouCompleteMe installation in the task list.

YCM is a more complex Vim plugin, so it has its own unique process of fetching dependency packages from Github after downloading it, which takes some time.

Execute the install script and add the --clang-completer parameter

This step is an important one in adding semantic completion support for C-Family to YCM. So what you need to do is to run install.sh in its directory and add the -clang-completer parameter.

1
2

cd ~/.vim/plugged/YouCompleteMe
. /install.sh --clang-completer

Accordingly, there are parameters such as --js-completer, --java-completer and --rust-completer, which can be added as needed.

If you browse through the YCM directory, you may find a Python script called -install.py. So if you want to use this script, this is also a viable option.

1
2

cd ~/.vim/plugged/YouCompleteMe
python3 install.py --clang-completer

If you are using the vundle plugin manager, the YCM installation directory should be under ~/.vim/bundle, not ~/.vim/plugged as specified by vim-plug.

Compiling ycm_core

Theoretically, the installation of YCM is complete after the previous step, but you may still get several errors from YCM when you start Vim. Among other things, it can make finding a Python runtime library quite difficult.

The errors given by YCM here appear to be in many forms on the web, mostly mentioning Couldn’t load various Python modules.

Don’t forget to also let YCM use the libclang we just installed. So compile ycm_core with the relevant arguments for the directory where Python is located and include -DEXTERNAL_LIBCLANG_PATH as well.

1
2
3
4
5
6

cmake -G "Unix Makefiles" ~/.vim/plugged/YouCompleteMe/third_party/ycmd/cpp/ \
    -DUSE_SYSTEM_BOOST=ON \
    -DEXTERNAL_LIBCLANG_PATH=/usr/local/clang+llvm-xxxxxxx/lib/libclang.so \
    -DPYTHON_LIBRARY=/usr/lib/python3.7 \
    -DPYTHON_INCLUDE_DIR=/usr/include/python3.7 \
    -DUSE_PYTHON2=OFF

LIBCLANG_PATH refers to the location of the libclang.so file, depending on the directory chosen for the previous installation of Clang.

PYTHON_LIBRARY and PYTHON_INCLUDE_DIR are related to the Python version number (in this case, 3.7) or the installation directory.

In particular, it is worth noting that YCM’s Makefile here is compiled with Python 2 by default, so if you don’t have Python 2 installed and you set the Python runtime libraries and headers to the Python 3 directory, you will get the error.

You set USE_PYTHON2 to make CMake find python2 libs only, but CMake found python3 libs instead. necessary python2 headers.

The solution is to add a line -DUSE_PYTHON2=OFF after the Cmake command, as shown in the last line of the given reference. Of course, if you are using Python 2 from the beginning, you should remove this line and just execute the command.

Specify .ycmextraconf.py

If you open a C/C++/ObjC/ObjC++ file with Vim at this point, there is a certain chance that you will also see an error like this, also from YCM:

No .ycm_extra_conf.py file detected, so no compile flags are available. Thus no semantic support for C/C++/ObjC/ObjC++. See the docs for details.

Take a deep breath, this issue exists in various descriptions in YCM’s repository issues list. This is the result of YCM not finding the most critical C-Family autocomplete configuration file. In fact, the ycm_extra_conf.py file is located in this well-hidden directory.

1

~/.vim/plugged/YouCompleteMe/third_party/ycmd/cpp/ycm

Just specify where it is in ~/.vimrc.

1

let g:ycm_global_ycm_extra_conf = '~/.vim/plugged/YouCompleteMe/third_party/ycmd/cpp/ycm/.ycm_extra_conf.py'

Some people also choose to copy the ycm_extra_conf.py file out of the deep directory and into a shallower part of the YCM home directory, and then modify the g:ycm_global_ycm_extra_conf variable.

Take it a step further

If nothing else happens, the installation should complete without incident. My description of the process of installing Vim and the YouCompleteMe plugin comes to an end. Apart from some strange issues in issues, this article basically covers the classic issues.

The beautification and further configuration of Vim is not covered in this article, so I recommend everyone to read:

  • The official Vim Tips Wiki

  • .vimrc with large number of stars on Github

The most important thing is not to spend too much time on tuning the tool, but to get familiar with Vim’s keystrokes and get the tool into production as soon as possible.

Thanks for reading 💗