These are just a snippet of all that can be found at https://langserver.org/.

Again these are just a snippet of all the available clients, for a more complete list see https://langserver.org/

Ubuntu is using apt as package manager, Fortunately the LLVM guys have added a PPA(Personal package archive) to be able to get the latest clang which can be found here.

So for example if you want to add clang-8 ppa to your sources (for this exercises I'm assuming you are running xenial )

You should add the following to your /etc/apt/sources.list

lsb_release -c | awk '{ print "deb http://apt.LLVM.org/"$2"/ LLVM-toolchain-"$2"-8 main" }' >> /etc/apt/sources.list
lsb_release -c | awk '{ print "deb-src http://apt.LLVM.org/"$2"/ LLVM-toolchain-"$2"-8 main" }' >> /etc/apt/sources.list

This will add the URL to the sources list, of course if you want to run some other version, just exchange the 8 to whatever you want to use.

We need to add the package signature to make sure we are using the the right PPA and add it as trusted. This is done by this command.

wget -O - https://apt.LLVM.org/LLVM-snapshot.gpg.key | sudo apt-key add -

Make sure the fingerprint is the same.

finally install the clang and friends.

apt update

apt-get install clang-8 \
clang-tools-8 \
clang-8-doc \
libclang-common-8-dev \
libclang-8-dev \
libclang1-8 \
clang-format-8 \
python-clang-8

Assuming you have cmake installed. Lets start with creating an out-of-build directory "build" and change directory to that.

mkdir build
cd build

Now we initiate the build.

cmake -DCMAKE_BUILD_TYPE=Release ..

In my build I get the following error:

fatal: No names found, cannot describe anything.

This seems to have something to do with git and its safe to ignore, in other words proceed to make

make -j8

If you want to install the server just type sudo make install

Cmake has a variable that can be set through the command line -DCMAKE_EXPORT_COMPILE_COMMADS=1 here is an example running cmake.

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 ..

it can also be set statically inside the CMakeLists.txt file.

set(CMAKE_EXPORT_COMPILE_COMMANDS 1)

cmake export compile commands

Bear is a tool to generate compilation database, some project might not have the benefit of running cmake, for these projects bear command will intercept the exec call by the build tool.

Here is an example using bear

bear make -j8

The init string can be used to initialize ccls with different options. For a complete list see the link. The init string needs to be a Json string. Here we have the opportunity to add/exclude compiler flags, set another cache directory, set the amount of indexing threads and many other things. This is especially useful if we are in a cross-compiling environment. But let not get ahead of our self's. Lets first create use the information above to create a new cache in e.g tmp, and create it in Json format instead.

lets first create the Json file which we will be using. Lets call it init.json , usually ccls is not run from the command line and the arguments should be provided through the client. But for this exercises we will just run the ccls stand-alone to make sure we understand what happens.

{
    "cache": {
        "directory": "/tmp/ccls-cache",
        "format": "json"
    },
    "index": {"blacklist":
              [
                  "^/usr/(local/)?include/c\\+\\+/[0-9\\.]+/(bits|tr1|tr2|profile|ext|debug)/",
                  "^/usr/(local/)?include/c\\+\\+/*",
                  "^/usr/include/LLVM*",
                  "^/usr/lib/LLVM-[0-9]+/*"
              ]
             },
    "compilationDatabaseDirectory": "build"
}

The above init will set:

Now lets run the indexer with the above init-string

./build/ccls -index=./ --init="`cat init.json`"

We will now end up with a cache in /tmp/ccls-cache with additional .json files that can be inspected. e.g using jq

jq . < /tmp/ccls-cache/@home@ocp@tmp@ccls/src@main.cc.json

All the init string and its meaning can be found at this link.

ccls is a line-based text file at the project root. Its main function is to specify compiler flags needed to properly index your code. This file is especially important when cross compiling. Which will be explained in section cross-compilation.

In this file we can specify for example that all files ending with .h should be considered c++ file. E.g

%h -x
%h c++-header

%compile_command.json% - directive

By default .ccls compiler flags are applied only to files not listed in compile_commands.json. If this directive appears first in .ccls then after compile_commands.json is parsed, the rest of the .ccls arguments will be appended to the compiler flags for files found in compile_commands.json.

Its also possible to add for example target directives for cross-compiling. More on that later.

The first thing we want is to include the compile_commands.json this is done through

%compile_commands.json

This means that for each of the compile commands listed, the flags that we include in this file (.ccls) will be added after the command found in the json file. So for example if we add another -I/tmp/myIncludes. This will be added to the clang++ together with whatever is located in the compile_commands.json line.

So we need this flag.

The next part is trying to get the same system paths as gcc so we will use the same stdlibc++ and such. To retain those flag we need to check what system flags g++ is using. This can be done with the following command.

eval $CXX -v -std=c++17 -xc++ -fsyntax-only /dev/null
.
.
.

This will spit out a whole bunch of things. We are just interested in what is between #include <...> search starts here and End of search list

#include "..." search starts here:
#include <...> search starts here:

.
/opt/sdk/sysroots/cortexa7t2hf-neon-poky-linux-gnueabi/usr/include/
End of search list.

Now for each of the line in between these keywords start and end , copy it and add it to the .ccls file in the following style

-isystem
...
-isystem
...
-isystem
/opt/sdk/sysroots/cortexa7t2hf-neon-poky-linux-gnueabi/usr/include/

The -isystem directives tells clang++ to check that path for system includes.

As mentioned before we had one flag that had an equivalent which we excluded (see Flags), now its time to add it again, but with clang++ manner.

-Wno-uninitialized

Lastly we will add the (architecture) target for which ccls/clang will be using to match g++ This was describe in target example, so all we need to do is add it to the .ccls file

-target
armv7e-unknown-linux-elf

It necessary to put the line exactly as it states in the example.

Here is an example of a .ccls file.

%compile_commands.json
%h -x
%h c++-header
-isystem
/opt/sdk/sysroots/cortexa7t2hf-neon-poky-linux-gnueabi/usr/include/c++/8.2.0
-isystem
/opt/sdk/sysroots/cortexa7t2hf-neon-poky-linux-gnueabi/usr/include/c++/8.2.0/arm-poky-linux-gnueabi
-isystem
/opt/sdk/sysroots/cortexa7t2hf-neon-poky-linux-gnueabi/usr/include/c++/8.2.0/backward
-isystem
/opt/sdk/sysroots/x86_64-ocpsdk-linux/usr/lib/arm-poky-linux-gnueabi/gcc/arm-poky-linux-gnueabi/8.2.0/include
-isystem
/opt/sdk/sysroots/cortexa7t2hf-neon-poky-linux-gnueabi/usr/lib/gcc/arm-poky-linux-gnueabi/8.2.0/include
-isystem
/opt/sdk/sysroots/x86_64-ocpsdk-linux/usr/lib/arm-poky-linux-gnueabi/gcc/arm-poky-linux-gnueabi/8.2.0/include-fixed
-isystem
/opt/sdk/sysroots/cortexa7t2hf-neon-poky-linux-gnueabi/usr/include/
-target
armv7e-unknown-linux-elf

Together with the init json-string

{
    "clang": {
        "excludeArgs": ["-march=armv7ve","-Wno-psabi", "-Wno-maybe-uninitialized"]
    },
    "index": {
        "initialBlacklist":
        [
            "^/usr/(local/)?include/c\\+\\+/[0-9\\.]+/(bits|tr1|tr2|profile|ext|debug)/",
            "^/usr/(local/)?include/c\\+\\+/*",
            "^/usr/include/LLVM*",
            "^/usr/lib/LLVM-[0-9]+/*"
        ]
    }
}

That concludes how to setup ccls for x-compilation environment.