diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 0744bb84e7..c3e16cfe29 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -57,6 +57,7 @@ nav: - Signals: user-guide/signals.md - Functions: user-guide/functions.md - Exporting: user-guide/exporting.md + - Debugging: user-guide/debugging.md - Versioning: user-guide/versioning.md - Supported platforms: user-guide/supported-platforms.md - Advanced: diff --git a/docs/src/doc/assets/img/remote_debug_configuration.png b/docs/src/doc/assets/img/remote_debug_configuration.png new file mode 100644 index 0000000000..df08b3e0a6 Binary files /dev/null and b/docs/src/doc/assets/img/remote_debug_configuration.png differ diff --git a/docs/src/doc/user-guide/advanced/commandline-args.md b/docs/src/doc/user-guide/advanced/commandline-args.md index e3847ad972..f497d441b5 100644 --- a/docs/src/doc/user-guide/advanced/commandline-args.md +++ b/docs/src/doc/user-guide/advanced/commandline-args.md @@ -1,12 +1,13 @@ The following command line args can be supplied to customize the behaviour or the Godot Kotlin/JVM binding: -| Argument | Default value | Description | -| --- | --- | ---| +| Argument | Default value | Description | Example | +| --- | --- | --- | --- | | --java-vm-type | jvm | Defines the VM to run on. Possible values are `jvm` and `graal_native_image`. When set to `graal_native_image` it uses Graal native image. This has no effect on android platform. | -| --jvm-debug-port | | Defines the port to which you can attach a remote debugger. **Note:** the module `jdk.jdwp.agent` is needed in the embedded JRE if you want to debug your application. If you need `jmx`, also the module `jdk.management.agent` is needed | -| --jvm-debug-address | | Defines which adresses are allowed for debugging | -| --jvm-jmx-port | | Defines the jmx port. **Note:** the module `jdk.management.agent` is needed in the embedded JRE to be able to use jmx | -| --jvm-to-engine-max-string-size | 512 | Maximun size of strings sent through the buffer. When above that value, strings are sent with a slower JNI Call. A bigger size means a bigger buffer. Increase if you need a lot of long strings and don't mind using more memory. One buffer exists for each thread | -| --jvm-force-gc | | If set the JVM GC is forced to run when our own GC runs. The interval is defined with `--jvm-gc-thread-period-millis` and defaults to 500ms | -| --jvm-disable-gc | | Disables our GC. **Caution:** If you disable our GC you **will** have memory leaks as all Reference types and Native Types are not Garbage collected anymore | -| --jvm-disable-closing-leaks-warning | | Disables the output of leaked instances when closing the application | +| --jvm-debug-port | | Defines the port to which you can attach a remote debugger. **Note:** the module `jdk.jdwp.agent` is needed in the embedded JRE if you want to debug your application. If you need `jmx`, also the module `jdk.management.agent` is needed | `--jvm-debug-port=5005` | +| --jvm-debug-address | | Defines which adresses are allowed for debugging | `--jvm-debug-address=localhost` | +| --wait-for-debugger | true | Accepted values: `true` or `false`. Defines if the jvm should suspend execution until a remote debugger is attached. Only effective if either `--jvm-debug-port` or `--jvm-debug-address` is set | `--wait-for-debugger=true` | +| --jvm-jmx-port | | Defines the jmx port. **Note:** the module `jdk.management.agent` is needed in the embedded JRE to be able to use jmx | `--jvm-jmx-port=5006` | +| --jvm-to-engine-max-string-size | 512 | Maximun size of strings sent through the buffer. When above that value, strings are sent with a slower JNI Call. A bigger size means a bigger buffer. Increase if you need a lot of long strings and don't mind using more memory. One buffer exists for each thread | `--jvm-to-engine-max-string-size=512` | +| --jvm-force-gc | | If set the JVM GC is forced to run when our own GC runs. | `--jvm-force-gc` | +| --jvm-disable-gc | | Disables our GC. **Caution:** If you disable our GC you **will** have memory leaks as all Reference types and Native Types are not Garbage collected anymore | `--jvm-disable-gc` | +| --jvm-disable-closing-leaks-warning | | Disables the output of leaked instances when closing the application | `--jvm-disable-closing-leaks-warning` | diff --git a/docs/src/doc/user-guide/debugging.md b/docs/src/doc/user-guide/debugging.md new file mode 100644 index 0000000000..96b3749cc7 --- /dev/null +++ b/docs/src/doc/user-guide/debugging.md @@ -0,0 +1,16 @@ +## Prerequisites +In order to debug your code using an embedded JRE, make sure to include the following modules: + +- `jdk.jdwp.agent` + +!!! info + Example: `jlink --add-modules java.base,java.logging,jdk.jdwp.agent --output jre` + +## Run and attach Remote Debugger +Run your game with the commandline option `--jvm-debug-port=<port (normally 5005)>` and attach a remote debugger. + +!!! info + If you specify either `--jvm-debug-port` or `--jvm-debug-address` the execution of the game will suspend until you attach a remote debugger. You can configure this behaviour by specifying `--wait-for-debugger=true` or `--wait-for-debugger=false` + +Example: +![remote debug configuration](../assets/img/remote_debug_configuration.png) diff --git a/src/gd_kotlin.cpp b/src/gd_kotlin.cpp index 4b2c7a0ba1..6bdbf603f1 100644 --- a/src/gd_kotlin.cpp +++ b/src/gd_kotlin.cpp @@ -162,6 +162,7 @@ void GDKotlin::init() { String jvm_jmx_port; bool is_gc_force_mode{false}; bool is_gc_activated{true}; + bool is_waiting_for_debugger{true}; bool should_display_leaked_jvm_instances_on_close{true}; const List<String>& cmdline_args{OS::get_singleton()->get_cmdline_args()}; for (int i = 0; i < cmdline_args.size(); ++i) { @@ -187,6 +188,13 @@ void GDKotlin::init() { } else { break; } + } else if (cmd_arg.find("--wait-for-debugger") >= 0) { + String is_waiting_for_debugger_as_string; + if (_split_jvm_debug_argument(cmd_arg, is_waiting_for_debugger_as_string) == OK) { + is_waiting_for_debugger = is_waiting_for_debugger_as_string == "true"; + } else { + break; + } } else if (cmd_arg.find("--jvm-jmx-port") >= 0) { if (_split_jvm_debug_argument(cmd_arg, jvm_jmx_port) == OK) { if (jvm_jmx_port.empty()) { @@ -225,8 +233,15 @@ void GDKotlin::init() { jvm_debug_port = "5005"; } + String suspend; + if (is_waiting_for_debugger) { + suspend = "y"; + } else { + suspend = "n"; + } + String debug_command{ - "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=" + jvm_debug_address + ":" + + "-agentlib:jdwp=transport=dt_socket,server=y,suspend=" + suspend + ",address=" + jvm_debug_address + ":" + jvm_debug_port}; args.option(debug_command.utf8()); } @@ -373,7 +388,7 @@ void GDKotlin::finish() { auto env = jni::Jvm::current_env(); bootstrap->finish(env); - + delete transfer_context; transfer_context = nullptr; delete bootstrap;