From 7a6e8b9a88422cb309ab2dfbf0ec11cde450e5a9 Mon Sep 17 00:00:00 2001 From: Jan Haller Date: Mon, 14 Aug 2023 08:38:11 +0200 Subject: [PATCH] Add summary and a few follow-up changes to Debugging page --- src/SUMMARY.md | 1 + src/gdext/advanced/debugging.md | 35 +++++++++++++++++++++++---------- 2 files changed, 26 insertions(+), 10 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index e04e3f9..338a7eb 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -9,6 +9,7 @@ - [Advanced topics](gdext/advanced/index.md) - [Compatibility and stability](gdext/advanced/compatibility.md) - [Selecting a Godot version](gdext/advanced/godot-version.md) + - [Debugging](gdext/advanced/debugging.md) - [Contributing to gdext](gdext/contribute/index.md) - [Dev tools and testing](gdext/contribute/dev-tools.md) - [Code and API conventions](gdext/contribute/conventions.md) diff --git a/src/gdext/advanced/debugging.md b/src/gdext/advanced/debugging.md index d901398..2b83266 100644 --- a/src/gdext/advanced/debugging.md +++ b/src/gdext/advanced/debugging.md @@ -1,10 +1,16 @@ # Debugging -Godot-Rust based GDExtensions can be debugged using LLDB in a similar manner to other Rust programs. The primary difference is that the executable which LLDB will launch or attach to needs to be the Godot executable (either Godot editor or your custom compiled Godot executable). Godot will, in turn, load your GDExtension (itself a dynamic library). The process for launching or attaching LLDB will vary based on your IDE and platform. Also keep in mind that, unless you are using a debug version of Godot itself, you'll only have symbols for stack frames in Rust code. +Extensions written in gdext can be debugged using LLDB, in a similar manner to other Rust programs. The primary difference is that LLDB will +launch or attach to the Godot C++ executable: either the Godot editor or your custom Godot application. +Godot then loads your extension (itself a dynamic library), and with it your Rust code. -## Launching with VSCode +The process for launching or attaching LLDB varies based on your IDE and platform. Unless you are using a debug version of Godot itself, +you will only have symbols for stack frames in Rust code. -Here is an example launch configuration for Visual Studio Code. Launch configurations should be added to `./.vscode/launch.json` relative to your project's root. This example assumes you have the [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) extension installed, which is common for Rust development. +## Launching with VS Code + +Here is an example launch configuration for Visual Studio Code. Launch configurations should be added to `./.vscode/launch.json` relative +to your project's root. This example assumes you have the [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) extension installed, which is common for Rust development. ```jsonc { @@ -15,7 +21,7 @@ Here is an example launch configuration for Visual Studio Code. Launch configura "request": "launch", "cwd": "${workspaceFolder}", "args": [ - "-e", // run editor (remove this if you want to launch the scene directly) + "-e", // run editor (remove this to launch the scene directly) "-w", // windowed mode ], "linux": { @@ -25,7 +31,8 @@ Here is an example launch configuration for Visual Studio Code. Launch configura "program": "C:\\Program Files\\Godot\\Godot_v4.1.X.exe", }, "osx": { - // NOTE: on Mac the Godot.app needs to be manually re-signed to enable debugging (see below) + // NOTE: on macOS the Godot.app needs to be manually re-signed + // to enable debugging (see below) "program": "/Applications/Godot.app/Contents/MacOS/Godot", } } @@ -33,12 +40,15 @@ Here is an example launch configuration for Visual Studio Code. Launch configura } ``` -## Debugging on MacOS +## Debugging on macOS -Attaching a debugger to an executable that wasn't compiled locally (the Godot editor, in this example) requires special considerations on MacOS due to its System -Integrity Protection (SIP) security feature. Even though your extension is compiled locally, LLDB will be unable to attach to the Godot *host process* without manual re-signing. +Attaching a debugger to an executable that wasn't compiled locally (the Godot editor, in this example) requires special considerations on macOS +due to its _System Integrity Protection_ (SIP) security feature. Even though your extension is compiled locally, LLDB will be unable to attach +to the Godot _host process_ without manual re-signing. -In order to re-sign, simply create a file called `editor.entitlements` with the following contents. Be sure to use the `editor.entitlements` file below rather than the one from the [Godot Docs](https://docs.godotengine.org/en/stable/contributing/development/debugging/macos_debug.html) as it includes the required `com.apple.security.get-task-allow` key not currently present in Godot's instructions. +In order to re-sign, simply create a file called `editor.entitlements` with the following contents. Be sure to use the `editor.entitlements` file +below rather than the one from the [Godot Docs](https://docs.godotengine.org/en/stable/contributing/development/debugging/macos_debug.html), +as it includes the required `com.apple.security.get-task-allow` key not currently present in Godot's instructions. ```xml @@ -65,4 +75,9 @@ In order to re-sign, simply create a file called `editor.entitlements` with the ``` -Once this file is created, you can run `codesign -s - --deep --force --options=runtime --entitlements ./editor.entitlements /Applications/Godot.app` in Terminal to complete the re-signing process. It is recommended to check this file in since each dev will need to re-sign their local install if you have a team. It should only need to be done once per Godot install though. +Once this file is created, you can run +```bash +codesign -s - --deep --force --options=runtime --entitlements ./editor.entitlements /Applications/Godot.app +``` +in Terminal to complete the re-signing process. It is recommended to check this file into version control, since each developer needs to +re-sign their local installation if you have a team. This process should only be necessary once per Godot installation though.