C++ code completion in Sublime Text with LSP and CCLS

Note: These instructions describe installation and setup of LSP and CCLS on Linux. While the commands will most likely differ, the configuration files will probably look the same on Windows and Mac.

I’m a big fan of Sublime Text. It’s been my favorite editor for over five years now, and I’m looking forward to its next release. But like most text editors, it requires some tweaking to make it useful for C++ development.

Full-fledged C++ IDEs have a lot of features, but I was only looking for basics:

  • code completion (the default code completion in Sublime Text is not language or context-aware)
  • definition and reference handling (for easier navigation)

No Sublime Text package offers these by default for C++. Fortunately, you can use the LSP protocol and an external language server - CCLS - to get these features and more.

Language Server Protocol (LSP), defines how a text editor (in this case Sublime Text) can communicate with a dedicated server language (CCLS) to display language- and context-aware information about code. In Sublime Text, you can use LSP through a dedicated package - LSP.

Installation

LSP package

In Sublime Text, open the Command Palette by pressing Ctrl+Shift+P.

If you have never installed any packages, you will first need to install the package manager - Package Control (start with step 4 below if you already have it installed):

  1. Type Package Control.
  2. Select Install Package Control.
  3. Press Enter. This will install the manager.
  4. Open the Command Palette again (Ctrl+Shift+P) and type install package.
  5. Select Package Control: Install Package and press Enter.
  6. Type in LSP when a new box appears.
  7. Make sure LSP is highlighted and press Enter. This will install the LSP package allowing Sublime Text to communicate with CCLS.

CCLS

To install CCLS, you can follow the instructions available on CCLS website. For the most part, you should be able to install it using your operating system’s default package manager. For example, on Arch and Manjaro, use

sudo pacman -S ccls

On Ubuntu 20.10, CCLS is available in the universe repository.

sudo apt install ccls

On an older version, you should be able to install its snap package.

sudo snap install ccls --classic

Configuration

Just like with installation, you will need to configure both tools separately.

Configuring Sublime Text

In Sublime Text, go to Preferences > Package Settings > LSP > Settings. Paste the following code in the LSP.sublime-settings file that appears:

"clients": {
        "ccls": {
            "command": ["ccls"],
            "enabled": true,
            "languageId": "cpp",
            "scopes": ["source.cpp", "source.hpp"],
            "syntaxes": ["Packages/C++/C++.sublime-syntax"],
        }
}

This configures Sublime Text to automatically launch the CCLS server when you access a C++ source file. If that does not happen, you might need to:

  • Add your project directory to a Sublime Text project (Project > Add Folder to Project)
  • Launch the server for your project manually (Tools > LSP > Enable Language Server in Project).

Configuring CCLS

To properly index your project, CCLS needs a compile_commands.json file in your project’s root. If you have already generated this file using CMake, it is probably in your build directory. In this case, you can link to it from your project’s root:

ln -s <your build directory>/compile_commands.json

If you don’t have this file yet, you can generate it along your other CMake files using this command:

cmake -H. -BYourBuildDirectory -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=YES

Replace YourBuildDirectory in the second parameter above with the name of your actual build directory. You can also change the build type to Release if appropriate.

After generating CMake files, be sure to link to compile_commands.json.

Your LSP and CCLS setup is now complete.