Contents

• About
  • Feature overview
  • Supported platforms
  • Dependencies
• Configuration
  • Compilation database
    • compile_commands.json
    • compile_flags.txt
• Example of configuration
• FAQ
• Screenshots

About

cxxd is a C/C++ language server which offers rich support for features that aid the process of source code navigation, editing, source code formatting, static analysis etc. One can utilize it, for example, to bring IDE-like features to an editor of your choice.

Feature overview

In essence, the main idea behind it is very much alike to what LSP offers and its implementations like clangd.

Supported platforms

Supported frontends (editors)

Dependencies

Required: Python3, libclang (with Python bindings)

Optional: clang-format, clang-tidy

Configuration

To run cxxd server against the source code one should provide .cxxd_config.json configuration file and put it into the root of the project repository.

This file can be used to provide project-specific configurations such as:

Compilation database

Compilation database is a requirement for cxxd. It can come in two different forms: compile_commands.json (recommended) or compile_flags.txt (should be used only as a fallback when generating compile_commands.json is not possible)

compile_commands.json

TL;DR in CMake projects you would simply add -DCMAKE_EXPORT_COMPILE_COMMANDS=ON to your CMake build invocation call. Or you could bake this setting into the CMakeLists.txt with set(CMAKE_EXPORT_COMPILE_COMMANDS ON). And you're done.

CMake/Bazel/waf/Qbs/ninja/clang have native and built-in support for generating this type of compilation database. Here's a good summary on how to use each of those. If you don't use any of those build systems, then same page provides another good summary on how to try to generate the compilation database in alternative ways.

compile_flags.txt

If generating the compile_commands.json is not possible to achieve within your environment, you can hand-code the build flags yourself and put it into the file named compile_flags.txt. E.g.

-I./lib
-I./include
-DFEATURE_XX
-DFEATURE_YY
-Wall
-Werror

Example of configuration

For completness and quickstart sake here's an example of a config file that I used while hacking on the MySQL database engine at Oracle. You can use it as starting point to create your own.

I used out-of-source builds with plenty of different ways to build and test the code. My regular workflow included running both sanitized (ASAN, UBSAN) and non-sanitized debug or relwithdebinfo builds. Sometimes I also had to test or backport the changes from MySQL 8.x to MySQL 5.x so I also had the build targets for that purpose. Later on I even tweaked the build target commands to include the way to run the build in distributed fashion through distcc and icecream.

clang-format version had to strictly adhere to specific version declared to be used by MySQL. Occassionally this version would be bumped so I also occassionally bumped the version in the config file.

Some parts of the MySQL used non-standard file extensions for the source code such as *.ic, .i or *.tpp. To make them visible to the cxxd indexer I have enumerated them in the extra-file-extensions field. Similarly, I have hinted the cxxd indexer not to index 3rd-party source code that is found in extra directory.

{
    "configuration" : {
        "type" : "compilation-database",
        "compilation-database" : {
            "target" : {
                "debug" : "../build/trunk/debug",
                "debug_asan" : "../build/trunk/debug_asan",
                "debug_ubsan" : "../build/trunk/debug_ubsan",
                "relwithdebinfo" : "../build/trunk/relwithdebinfo",
                "relwithdebinfo_asan" : "../build/trunk/relwithdebinfo_asan",
                "relwithdebinfo_ubsan" : "../build/trunk/relwithdebinfo_ubsan",
                "debug5" : "../build/5.x/debug",
                "relwithdebinfo5" : "../build/5.x/relwithdebinfo",
             }
        }
    },
    "indexer" : {
        "exclude-dirs" : [
            "extra"
        ],
        "extra-file-extensions" : [
            ".ic",
            ".i",
            ".tpp"
        ]
    },
    "clang-tidy" : {
        "args" : {
            "-checks" : "'-*,bugprone-*,cert-*,clang-analyzer-*,-clang-analyzer-osx*,misc-*,performance-*,portability-*,readability-*",
            "-extra-arg" : "'-Wno-unknown-warning-option'",
            "-header-filter" : ".*"
        }
    },
    "clang-format" : {
        "binary" : "/opt/clang+llvm-8.0.0-x86_64-linux-gnu/bin/clang-format",
        "args" : {
            "-i" : true,
            "--style" : "file"
        }
    },
    "project-builder" : {
        "target" : {
            "debug" : {
                "cmd" : "cmake ../../../trunk -GNinja -DCMAKE_BUILD_TYPE=Debug -DDOWNLOAD_BOOST=ON -DWITH_BOOST=../ -DWITH_UNIT_TESTS=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_COMPILER_LAUNCHER=ccache && ninja"
            },
            "debug_asan" : {
                "cmd" : "cmake ../../../trunk -GNinja -DCMAKE_BUILD_TYPE=Debug -DDOWNLOAD_BOOST=ON -DWITH_BOOST=../ -DWITH_UNIT_TESTS=ON -DWITH_ASAN=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_COMPILER_LAUNCHER=ccache && ninja"
            },
            "debug_ubsan" : {
                "cmd" : "cmake ../../../trunk -GNinja -DCMAKE_BUILD_TYPE=Debug -DDOWNLOAD_BOOST=ON -DWITH_BOOST=../ -DWITH_UNIT_TESTS=ON -DWITH_UBSAN=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_COMPILER_LAUNCHER=ccache && ninja"
            },
            "relwithdebinfo" : {
                "cmd" : "cmake ../../../trunk -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DDOWNLOAD_BOOST=ON -DWITH_BOOST=../ -DWITH_UNIT_TESTS=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_COMPILER_LAUNCHER=ccache && ninja"
            },
            "relwithdebinfo_asan" : {
                "cmd" : "cmake ../../../trunk -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DDOWNLOAD_BOOST=ON -DWITH_BOOST=../ -DWITH_UNIT_TESTS=ON -DWITH_ASAN=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_COMPILER_LAUNCHER=ccache && ninja"
            },
            "relwithdebinfo_ubsan" : {
                "cmd" : "cmake ../../../trunk -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DDOWNLOAD_BOOST=ON -DWITH_BOOST=../ -DWITH_UNIT_TESTS=ON -DWITH_UBSAN=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_COMPILER_LAUNCHER=ccache && ninja"
            },
            "debug5" : {
                "cmd" : "cmake ../../../5.x -GNinja -DCMAKE_BUILD_TYPE=Debug -DDOWNLOAD_BOOST=ON -DWITH_BOOST=../ -DWITH_UNIT_TESTS=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_COMPILER_LAUNCHER=ccache && ninja"
            },
            "relwithdebinfo5" : {
                "cmd" : "cmake ../../../5.x -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DDOWNLOAD_BOOST=ON -DWITH_BOOST=../ -DWITH_UNIT_TESTS=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_COMPILER_LAUNCHER=ccache && ninja"
            },
        }
    },
    "disassembly" : {
        "objdump" : {
            "intermix-with-src-code" : false,
            "visualize-jumps" : true,
            "syntax" : "intel"
        },
        "nm" : {
        },
        "targets-filter" : [".so", ".a", "CMake"]
    }
}

FAQ

How do I make use of this in <insert_environment_of_your_choice>?

Currently there's only a Vim cxxd-vim plugin that I have developed as a PoC and which I have been using as my daily driver since then. On a semi-regular base I try to keep it up to date with the bugfixes and less often with the new features.

To integrate cxxd with another editor one should read through the architecture overview. Also, file a ticket if you need help.

What about clangd and other language server implementations

Fun fact: this project actually started to grow the whole idea and implementation before LSP (and clangd) has been put into life. And I am basically hacking on cxxd and cxxd-vim codebase since then. But I do it only occassionaly and as much as my spare time allows me to.

It turns out that writing a language server implementation on top of the libclang backend is a mine field. Complex C and C++ compilation process doesn't make this situation any easier. Variety of build systems available and multitude of different ways on how you can build a model of your code due to arbitary number of build targets also makes it a bigger challenge. And only because I implemented both the language server side and the UI frontend side that accompanies it, and everything from the scratch, it happens that I find it easier (and more fun!) to hack through my own codebase and learning something new rather than waiting on other similar tools to provide the fixes, if at all. I tried many of them and they all experience from same or similar issues I stumble upon as well. YMMV of course.

I also implemented a non-LSP compatible protocol which means that I am free to decide and integrate whatever I find interesting for a development workflow. One such example is support for arbitrary build targets which happens to have an actual impact on how the language server backend will understand your code or will not. Browsing or indexing or code-completion context isn't the same across "debug" or "debug-with-some-fancy-feature" or "relwithdebinfo" targets. For that reason, cxxd is always started against the specific build target.

Screenshots

To see how it looks like in action you may have a look at the screenshots from cxxd-vim.