Skip to content

Commit

Permalink
Add summary and a few follow-up changes to Debugging page
Browse files Browse the repository at this point in the history
  • Loading branch information
Bromeon committed Aug 14, 2023
1 parent 0bef45e commit 7a6e8b9
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 10 deletions.
1 change: 1 addition & 0 deletions src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
35 changes: 25 additions & 10 deletions src/gdext/advanced/debugging.md
Original file line number Diff line number Diff line change
@@ -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
{
Expand All @@ -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": {
Expand All @@ -25,20 +31,24 @@ 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",
}
}
]
}
```

## 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
<?xml version="1.0" encoding="UTF-8"?>
Expand All @@ -65,4 +75,9 @@ In order to re-sign, simply create a file called `editor.entitlements` with the
</plist>
```

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.

0 comments on commit 7a6e8b9

Please sign in to comment.