The “Editor War” is a never-ending battle between Vim and Emacs. But it seems to me that once the editors are configured and put into daily production, they do pretty good for both Vim and Emacs diehards. The reason for this idea is that I had a painful experience with Vim. In particular, configuring YouCompleteMe, a plugin with a name that even sounds ambiguous, did its best to make me feel malicious.

While this article does not faithfully retell the entire process of installing, I tuned the order of operations, retained descriptions of where problems may occur and explains solutions to those.

Vim version & configuration environment

The version of Vim to be compiled and installed is the latest 8.1 from the official Github repository.

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

The Debian 9 provided by Windows Subsystem for Linux (hereinafter called WSL) is somewhat unique in that it is a cleaner environment than the larger distributions, but this does not affect the installation process of Vim.

Compiling and installing Vim 8

Why compile and install

In fact, except for the case that the packages which need to be installed are missing in the software repository, downloading and installing software from software repositories should generally be the preferred solution. The package manager will take care of the dependencies well, and is less likely to dirty up the system. So the recommended practice on Debian-based distributions should be.

1
sudo apt install vim

However, some Vim plug-ins (like YouCompleteMe in this article) require Vim with Python support. The default installation of Vim does not enable Python/Lua/Ruby support by default.

So how do you enable it? In this article, we compile and install Vim with the option to enable Python support, so that we can get a Vim that meets our requirements. Other solutions such as vim-nox are not in the scope of our discussion.

Download Vim source code

Install Git first. You can also go directly to the Vim repositories to get the source code, but since most Vim plugin managers rely on Git to install and upgrade their plugins, Git should be the first thing you install.

1
sudo apt install git

You don’t need to do any complicated Git configuration, although there is a good chance that you will need to in the future. All you need to do is get the source code using a simple Git command.

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

If nothing else, this is going to take a few seconds of waiting.

Compiling Vim to enable Python 3 support

The need to enable Python support has already been explained in the compile-and-install section, so I won’t repeat it here, but first install Python 3 and its supporting library libpython3-dev.

1
sudo apt install python3 libpython3-dev

Theoretically, mainstream distributions such as Debian should already include Python3 support, but WSL does not, so I’ll install it.

Go back to the directory where you put the Vim source code, and go to the src subdirectory. Make sure that the build-essential compilation tool is installed before you compile, otherwise you will get errors because you can’t find it.

1
sudo apt-get install build-essential

Once the compilation tool is ready, you can compile and install it. Start to do the following three steps.

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

In the third and fourth configuration options, I chose to enable Python 3 support and tell the directory where the config file is located. Omitting the installation of libpython3-dev above may cause the config file to be missing.

Of course, the above two directories also change depending on the version of Python installed (e.g., version 3.7 is installed here), so if an error comes up, look under /usr/lib for the Python directory in the folder that contains the config field and fill it in.

If you need Python 2 support, such as some older plugins that still only support Python 2 but have 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 mistakenly enable the enable-pythoninterp option, Vim will fail to enable Python because it can’t find Python 2 related files when Python 2 support is enabled. So, be sure to install the appropriate version and enable the appropriate options.

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

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

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

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 just install libncurses5-dev as the error hint says.

1
sudo apt install libncurses5-dev

If all goes well with . /configure everything is fine, all you have to do next is to run:

1
2
sudo make
sudo make install

Register Vim as an Editor

The following methods are available for registering Vim as an editor for Debian.

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

Using a generic soft link to vim.

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

This way, you can run Vim by typing vim on the command line.

At this point, to ensure that Vim’s Python support is enabled as planned, the following commands can verified that.

1
vim --version | grep python

Two of the unsurprising output results are.

1
2
-python
+python3

This is enabled if there is a plus sign before the item, not enabled if there is a minus sign. So Python 3 support is successfully enabled here.

Installing the YouCompleteMe Plugin

YouCompleteMe (YCM for short) is a powerful but malicious autocomplete plugin for Vim. In the issues of YCM Official Repository, its author, Valloric, takes pains to remind issues authors to read the official documentation, so following the official Installation Instructions and checking the User Guide first after meeting a trouble – is the next step we should take. Adhering to the process.

The goal of configuring YCM in this article is to have it support C/C++ autocomplete, other languages are out of the scope of this article. It should be noted that for enabling C Family’s semantic autocomplete, to read this document is officially recommended.

Installing the vim-plug plug-in manager

Although our goal is just to install YCM, for future use of Vim, the great help of a plugin manager cannot be ignored. Here we have chosen the Vim plugin manager – vim-plug – which is the second most popular on Github and supports asynchronous installation.

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

The autoload folder exists in the ~/.vim directory, but you can simply create a new directory for both if they do not exist.

Edit the ~/.vimrc file (if it does not exist, create a new one) to include a reference to YCM.

1
Plug 'Valloric/YouCompleteMe'

The use of vim-plug is well described in the official repository at README. In short, you can change the single-quotes in the configuration line above to the address of another plugin (in the format of “Username/Plugname “) to reference the plugins.

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

Install Clang

For semantic completion of C Family, YCM uses the Clang semantic search engine. It comes with libclang, but the documentation gives suggestions to compile libclang yourself. This means that Clang is a prerequisite to be configured correctly 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 repository (the latest version is 6.0 when writing this).

1
sudo apt install clang-6.0

This is the fastest and easiest way to install Clang + LLVM. It’s not a big deal if you compile and install the source code separately. Of course, LLVM also has a Download Page where you can download the packages for different systems and distributions. So, you can also move the downloaded packages to /usr/local, which is next to the Vim installation directory.

The following version numbers are 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. The libclang is now quietly hidden in /usr/local/clang+llvm_xxxxxxx/x86_64-linux-gnu/lib.

Installing Cmake

Cmake is YCM’s default compiler, so using Cmake to compile YCM is the safest and most secure way. If you don’t want to 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.

The good news is that Cmake provides an installer script for the Shell, just go to Download Page to find your platform and download it. After downloading, go to the directory where the script is located, move to /usr/local, and then execute the installation.

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, please correct with the downloaded file.

Type y to accept the agreement and when prompted, type y again to install in a separate subdirectory of your directory.

So, Cmake is ready.

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 to execute the installation script after installing Cmake.

Start Vim, type : to enter command mode, type PlugInstall, and then enter to confirm. At this point, vim-plug will start getting each plugin from Git, and will take care of the installation directory. There is only one plugin, so you should only have one item on your task list, YouCompleteMe, to install.

YCM is a complex Vim plugin, so it has its own unique process for getting dependencies from Github once you download it, which can take some time.

Execute the installation script and add the --clang-completer parameter.

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

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

There are --js-completer, --java-completer, and --rust-completer parameters, which you can add as needed.

If you browse through the YCM directory, you’ll probably find a Python script called install.py. So if you want to use that script, that’s 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 the ~/.vim/plugged specified by vim-plug.

Compile ycm_core

Theoretically, the YCM installation is complete after the previous step, but starting Vim at this point may still give you several errors from YCM. Among other things, this can run into considerable difficulty in finding Python’s runtime library.

Errors from YCM here take many forms on the web, most often is couldn’t load various Python modules.

Don’t forget to make YCM use the libclang that you just installed. So compile ycm_core, add the arguments that provide the directory where Python is located, and add -DEXTERNAL_LIBCLANG_PATH to it 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 selected earlier for the Clang installation.

PYTHON_LIBRARY and PYTHON_INCLUDE_DIR relate to the Python version number (3.7 in this case) or to the directory where Clang was installed.

In particular, YCM’s Makefile here is compiled using Python 2 by default, so if you don’t have Python 2 installed and you set up Python’s runtime library and headers directory to be the Python 3 directory, you’ll get the following error.

You set USE_PYTHON2 to make CMake find python2 libs only, but CMake found python3 libs instead. Either don’t set USE_PYTHON2 or install the necessary python2 headers.

The solution is to add a line -DUSE_PYTHON2=OFF after the last line of the Cmake command given. Of course, if you’ve been using Python 2 from the beginning, you should remove this line and just run the command.

Specifying .ycmextraconf.py

Now open a C/C++/ObjC/ObjC++ file with Vim, and chances are you’ll see an error, also from YCM, like this.

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 problem exists in various descriptions in YCM’s repository issues list. It’s caused by YCM not finding the most critical C-Family autocomplete configuration file. In fact, the ycm_extra_conf.py file is located under this very deep directory.

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

You can specify its location in ~/.vimrc.

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

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

Further

If nothing else, the installation should be completed without a hitch. At this point, I’ve described the process of installing the Vim and YouCompleteMe plugins. Aside from the odd issue, this article has pretty much covered the classic troubles.

The customization and further configuration of Vim is not the subject of this article, so here’s what I recommend you read.

  • Official Vim Tips Wiki

  • The .vimrc with a large number of stars on Github

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

Thanks for reading 💗