docs: Add a section to HACKING.md on using mkosi and clangd together

While it's perfectly possible today to completely rely on mkosi for
building and testing systemd, to get code completion and other IDE
niceties to work properly, it's still necessary to build systemd
locally.

Recently, mkosi gained the ability to allow external programs to
communicate with the build script. We can use this feature to run
the clangd language server in the mkosi build image via a custom
build script to provide IDE features in editors without requiring
developers to build systemd on the host or install any of systemd's
build dependencies locally.

This commit adds the necessary information on how to set this up
to HACKING.md.

1 files changed, 80 insertions, 0 deletions

diff --git a/docs/HACKING.md b/docs/HACKING.md
index d25be843dc..f6b1f047db 100644
--- a/docs/HACKING.md
+++ b/docs/HACKING.md
@@ -136,3 +136,83 @@ For more details on building fuzzers and integrating with OSS-Fuzz, visit:
 
 - [Setting up a new project - OSS-Fuzz](https://google.github.io/oss-fuzz/getting-started/new-project-guide/)
 - [Tutorials - OSS-Fuzz](https://google.github.io/oss-fuzz/reference/useful-links/#tutorials)
+
+## mkosi + clangd
+
+[clangd](https://clangd.llvm.org/) is a language server that provides code completion, diagnostics and more
+right in your editor of choice (with the right plugin installed). When using mkosi, we can run clangd in the
+mkosi build container to avoid needing to build systemd on the host machine just to make clangd work. To
+achieve this, create a script with the following contents in systemd's project directory on the host:
+
+```sh
+#!/usr/bin/env sh
+tee mkosi-clangd.build > /dev/null << EOF
+#!/usr/bin/env sh
+exec clangd \\
+        --compile-commands-dir=/root/build \\
+        --path-mappings=\\
+"\\
+$(pwd)=/root/src,\\
+$(pwd)/mkosi.builddir=/root/build,\\
+$(pwd)/mkosi.includedir=/usr/include,\\
+$(pwd)/mkosi.installdir=/root/dest\\
+" \\
+        --header-insertion=never
+EOF
+chmod +x mkosi-clangd.build
+exec sudo mkosi --source-file-transfer=mount --incremental --skip-final-phase --build-script mkosi-clangd.build build
+```
+
+Next, mark the script as executable and point your editor plugin to use this script to start clangd. For
+vscode's clangd extension, this is done via setting the `clangd.path` option to the path of the
+mkosi-clangd.sh script.
+
+To be able to navigate to include files of systemd's dependencies, we need to make the /usr/include folder of
+the build image available on the host. mkosi supports this by setting the `IncludeDirectory` option in
+mkosi's config. The easiest way to set the option is to create a file 20-local.conf in mkosi.default.d/ and
+add the following contents:
+
+```
+[Packages]
+IncludeDirectory=mkosi.includedir
+```
+
+This will make the contents of /usr/include available in mkosi.includedir in the systemd project directory.
+We already configured clangd to map any paths in /usr/include in the build image to mkosi.includedir/ on the
+host in the mkosi-clangd.sh script.
+
+We also need to make sure clangd is installed in the build image. To have mkosi install clangd in the build
+image, edit the 20-local.conf file we created earlier and add the following contents under the `[Packages]`
+section:
+
+```
+BuildPackages=<clangd-package>
+```
+
+Note that the exact package containing clangd will differ depending on the distribution used. Some
+distributions have a separate clangd package, others put the clangd binary in a clang-tools-extra package and
+some bundle clangd in the clang package.
+
+Because mkosi needs to run as root, we also need to make sure we can enter the root password when the editor
+plugin tries to run the mkosi-clangd.sh script. To be able to enter the root password in non-interactive
+scripts, we use an askpass provider. This is a program that sudo will launch if it detects it's being
+executed from a non-interactive shell so that the root password can still be entered. There are multiple
+implementations such as gnome askpass and KDE askpass. Install one of the askpass packages your distro
+provides and set the `SUDO_ASKPASS` environment variable to the path of the askpass binary you want to use.
+If configured correctly, a window will appear when your editor plugin tries to run the mkosi-clangd.sh script
+allowing you to enter the root password.
+
+Due to a bug in btrfs, it's currently impossible to mount two mkosi btrfs images at the same time. Because of
+this, trying to do a regular build while the clangd image is running will fail. To circumvent this, use ext4
+instead of btrfs for the images by adding the following contents to 20-local.conf:
+
+```
+[Output]
+Format=gpt_ext4
+```
+
+Finally, to ensure clangd starts up quickly in the editor, run an incremental build with mkosi to make sure
+the cached images are initialized (`mkosi -i`).
+
+Now, your editor will start clangd in the mkosi build image and all of clangd's features will work as
+expected.