From: Daan De Meyer <daan.j.demeyer@gmail.com>
Date: Thu, 18 Aug 2022 12:38:19 +0000 (+0200)
Subject: docs: Add guide to debug binaries in vscode that need to run as root
X-Git-Tag: v252-rc1~401^2
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F24350%2Fhead;p=thirdparty%2Fsystemd.git

docs: Add guide to debug binaries in vscode that need to run as root
---

diff --git a/docs/HACKING.md b/docs/HACKING.md
index 1a90e7b395f..33b5ac166a4 100644
--- a/docs/HACKING.md
+++ b/docs/HACKING.md
@@ -271,6 +271,30 @@ 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.
 
+## Debugging binaries that need to run as root in vscode
+
+When trying to debug binaries that need to run as root, we need to do some custom configuration in vscode to
+have it try to run the applications as root and to ask the user for the root password when trying to start
+the binary. To achieve this, we'll use a custom debugger path which points to a script that starts `gdb` as
+root using `pkexec`. pkexec will prompt the user for their root password via a graphical interface. This
+guide assumes the C/C++ extension is used for debugging.
+
+First, create a file `sgdb` in the root of the systemd repository with the following contents and make it
+executable:
+
+```
+#!/bin/sh
+exec pkexec gdb "$@"
+```
+
+Then, open launch.json in vscode, and set `miDebuggerPath` to `${workspaceFolder}/sgdb` for the corresponding
+debug configuration. Now, whenever you try to debug the application, vscode will try to start gdb as root via
+pkexec which will prompt you for your password via a graphical interface. After entering your password,
+vscode should be able to start debugging the application.
+
+For more information on how to set up a debug configuration for C binaries, please refer to the official
+vscode documentation [here](https://code.visualstudio.com/docs/cpp/launch-json-reference)
+
 ## Debugging systemd with mkosi + vscode
 
 To simplify debugging systemd when testing changes using mkosi, we're going to show how to attach