Debugging documentation (#254)

* Add debugging docs and change debug args to suspend game until remote debugger is attached

* Actually link new documentation

* Change prerequisites wording

Co-authored-by: Ranie Jade Ramiso <[email protected]>

* Remove unnecessary line

* Make suspend on debug configurable

* Fix rebasing mistake

Co-authored-by: Ranie Jade Ramiso <[email protected]>

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:

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` |

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)

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;