Document how to attach a debugger to the server

DEVELOP.md

@@ -268,3 +268,33 @@ For more details, go read the code!
 
 If you find a bug, or have an awesome idea to implement, please discuss and
 contribute ;-)
+
+
+### Debug the server
+
+The server is pushed to the device by the client on startup.
+
+To debug it, enable the server debugger during configuration:
+
+```bash
+meson x -Dserver_debugger=true
+# or, if x is already configured
+meson configure x -Dserver_debugger=true
+```
+
+Then recompile.
+
+When you start scrcpy, it will start a debugger on port 5005 on the device.
+Redirect that port to the computer:
+
+```bash
+adb forward tcp:5005 tcp:5005
+```
+
+In Android Studio, _Run_ > _Debug_ > _Edit configurations..._ On the left, click on
+`+`, _Remote_, and fill the form:
+
+ - Host: `localhost`
+ - Port: `5005`
+
+Then click on _Debug_.

app/meson.build

@@ -115,6 +115,9 @@ conf.set('HIDPI_SUPPORT', get_option('hidpi_support'))
 # disable console on Windows
 conf.set('WINDOWS_NOCONSOLE', get_option('windows_noconsole'))
 
+# run a server debugger and wait for a client to be attached
+conf.set('SERVER_DEBUGGER', get_option('server_debugger'))
+
 configure_file(configuration: conf, output: 'config.h')
 
 src_dir = include_directories('src')

app/src/server.c

@@ -124,6 +124,11 @@ execute_server(struct server *server, const struct server_params *params) {
         "shell",
         "CLASSPATH=/data/local/tmp/" SERVER_FILENAME,
         "app_process",
+#ifdef SERVER_DEBUGGER
+# define SERVER_DEBUGGER_PORT "5005"
+        "-agentlib:jdwp=transport=dt_socket,suspend=y,server=y,address="
+            SERVER_DEBUGGER_PORT,
+#endif
         "/", // unused
         "com.genymobile.scrcpy.Server",
         max_size_string,
@@ -133,6 +138,17 @@ execute_server(struct server *server, const struct server_params *params) {
         "true", // always send frame meta (packet boundaries + timestamp)
         params->control ? "true" : "false",
     };
+#ifdef SERVER_DEBUGGER
+    LOGI("Server debugger waiting for a client on device port "
+         SERVER_DEBUGGER_PORT "...");
+    // From the computer, run
+    //     adb forward tcp:5005 tcp:5005
+    // Then, from Android Studio: Run > Debug > Edit configurations...
+    // On the left, click on '+', "Remote", with:
+    //     Host: localhost
+    //     Port: 5005
+    // Then click on "Debug"
+#endif
     return adb_execute(server->serial, cmd, sizeof(cmd) / sizeof(cmd[0]));
 }
 

meson_options.txt

@@ -5,3 +5,4 @@ option('windows_noconsole', type: 'boolean', value: false, description: 'Disable
 option('prebuilt_server', type: 'string', description: 'Path of the prebuilt server')
 option('portable', type: 'boolean', value: false, description: 'Use scrcpy-server from the same directory as the scrcpy executable')
 option('hidpi_support', type: 'boolean', value: true, description: 'Enable High DPI support')
+option('server_debugger', type: 'boolean', value: false, description: 'Run a server debugger and wait for a client to be attached')