[libvirt PATCH 05/10] docs: Add config instructions for clangd with libvirt

[Tim Small]

In build environments which use gcc as the default compiler, use of the
clangd LSP server (for enhanced code editing and navigation etc.) with
libvirt requires some additional configuration.  Detail this and link
from `hacking.rst`.

Signed-off-by: Tim Small <tim at seoss.co.uk>
---
 docs/clangd.rst  | 51 ++++++++++++++++++++++++++++++++++++++++++++++++
 docs/hacking.rst |  3 +++
 docs/meson.build |  1 +
 3 files changed, 55 insertions(+)
 create mode 100644 docs/clangd.rst

diff --git a/docs/clangd.rst b/docs/clangd.rst
new file mode 100644
index 0000000000..93570ae178
--- /dev/null
+++ b/docs/clangd.rst
@@ -0,0 +1,51 @@
+=========================
+Using Clangd with Libvirt
+=========================
+
+`clangd <https://clangd.llvm.org/>`__ is an implementation of the
+`language server protocol
+<https://en.wikipedia.org/wiki/Language_Server_Protocol>`__ for C
+and C++.
+
+When paired with an LSP-compatible editor or IDE (e.g. emacs,
+vim, vscode), ``clangd`` can helpful when working with libvirt's
+C sources e.g. navigating the code base.
+
+Whilst other C LSPs are available, ``clangd`` should work
+correctly with the libvirt because clang is a supported compiler
+for libvirt, and ``clangd`` is part of the same code base as
+clang.
+
+If clang is the default compiler on your system, then ``clangd``
+can be used as soon as ``meson setup`` has been run.
+
+If gcc is your build environment's default compiler, then
+additional steps are required to use ``clangd``:
+
+``clangd`` looks for a ``compile_commands.json`` file in the top
+level directory of the project and also in the ``build/``
+subdirectory to discover which include paths, compiler flags etc.
+should be used when it parses each source file.
+
+Meson creates a ``compile_commands.json`` in the build directory.
+Meson defaults to the system's default C compiler. When the
+default compiler is gcc, its ``compile_commands.json`` output
+cannot be used with ``clangd`` due to differences in compiler
+invocation flags when building libvirt.
+
+Create a separate build directory with a ``clangd`` compatible
+``compile_commands.json`` as follows:
+
+::
+
+   CC=clang CXX=clang++ meson setup build-clang
+
+Point ``clangd`` (v12 or later) at the correct
+``compile_commands.json`` by placing the following into a
+``.clangd`` file in the root of the project:
+
+::
+
+   ---
+   CompileFlags:
+     CompilationDatabase: "build-clang"
diff --git a/docs/hacking.rst b/docs/hacking.rst
index a04da9cb58..11cd21223a 100644
--- a/docs/hacking.rst
+++ b/docs/hacking.rst
@@ -28,6 +28,9 @@ The `"Git checkout" section <compiling.html#git-checkout>`__
 of the libvirt installation instructions give an overview of the
 compilation process.
 
+Optionally, `Clangd with libvirt <clangd.html>`__ can be used to
+navigate the code base etc. within most code editors (and IDEs).
+
 Preparing patches
 =================
 
diff --git a/docs/meson.build b/docs/meson.build
index 201fd4c984..70d271ec6e 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -32,6 +32,7 @@ docs_rst_files = [
   'ci',
   'ci-dashboard',
   'ci-runners',
+  'clangd',
   'coding-style',
   'committer-guidelines',
   'compiling',
-- 
2.39.2