From 09a3bc06a4b3ff5485dde06678867c042a6d236d Mon Sep 17 00:00:00 2001 From: Florian Xaver Date: Tue, 9 Nov 2021 21:32:37 +0100 Subject: [PATCH] How to use ccls with build containers --- Project-Setup.md | 45 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/Project-Setup.md b/Project-Setup.md index b4a7322..4b0556e 100644 --- a/Project-Setup.md +++ b/Project-Setup.md @@ -1,7 +1,9 @@ -ccls typically indexes an entire project. In order for this to work properly, +`ccls` typically indexes an entire project. In order for this to work properly, `ccls` needs to be able to obtain the source file list and their compilation command lines. +### How `ccls` obtains sources and compilation commands + There are two main ways this happens: 1. Provide `compile_commands.json` at the project root @@ -12,6 +14,47 @@ There are two main ways this happens: If neither exists, then when ccls starts it will not index anything: instead it will wait for LSP clients to open files and index only those files. +### Using build containers + +Build containers are usually OCI containers and are often managed by Podman or Docker. Toolchains for building might run in these containers for reproducability. + +There are two possibilities: +1. Execute the container for building only. Use `ccls` and your editor/IDE on the host. +2. The build container is running in the background with an installed and running `ccls`. Furthermore, it is using the host network so that editors/IDEs running on the host can connect. + +#### `ccls` on the host + +If you want to use `ccls` on the host, a path mapping has to be applied, since paths and compiler versions will most probably differ. +Thus, paths of following headers have to be translated to the host system: +* system and third-party libraries (if those headers do not already exist, install them. E.g., `openssl-devel` in Linux) +* the compiler's headers + +See following initialization options (`ccls --init='...'`), which uses `build/compile_commands.json` already produced _in_ the container: +``` +{ + "clang": { + "resourceDir": "/usr/lib64/clang/13.0.0", + "pathMappings": [ + "/project_container/>/project_host/", + "/opt/rh/gcc-toolset-10/root>" + ], + "clang.extraArgs": [ + "--gcc-toolchain=/opt/rh/gcc-toolset-10/root/usr" + ] + }, + "compilationDatabaseDirectory": "/project_host/build/" +} +``` +`resourceDir` denotes the directory of the compiler's include files at the host. The compiler version is usually different from the container's. `pathMappings` substitute directories mounted into the container by the related host directories. If you are using `clang(++)` with `--gcc-toolchain=...`, then you have to add the corresponding directory to `pathMappings`, and add `clang.extraArgs`. Here the `compile_commands.json` is in a different directory, and, hence, `compilationDatabaseDirectory` has to be specified. + +Note: On the host, you may have to install additional developer packages (e.g. openssh-devel), which include required headers. If headers are missing, you will see errors in the log file (start `ccls` by `--log-file=/tmp/ccls.log -v=1`) or error labels in your editor. + +#### `ccls` on the container + +1. Install `ccls` in the container +2. Execute the container with `--network=host` (Podman, Docker) such that it continues to run. +3. Start the build process by attaching to the contatiner and executing the build tool (`cmake`, `make`,...) + ## `compile_commands.json` [Guillaume Papin(@Sarcasm)](https://github.com/sarcasm) has [a thorough article about compilation databases](https://sarcasm.github.io/notes/dev/compilation-database.html).