|
| 1 | +## Running ds2 |
| 2 | + |
| 3 | +### Running on a remote host |
| 4 | + |
| 5 | +Launch ds2 in platform mode (not supported on Windows): |
| 6 | +```sh |
| 7 | +$ ./ds2 platform --server --listen localhost:4242 |
| 8 | +``` |
| 9 | + |
| 10 | +Launch ds2 as a single-instance gdb server debugging a program: |
| 11 | +```sh |
| 12 | +$ ./ds2 gdbserver localhost:4242 /path/to/executable |
| 13 | +``` |
| 14 | + |
| 15 | +In both cases, ds2 is ready to accept connections on port 4242 from LLDB. |
| 16 | + |
| 17 | +### Running on an Android device |
| 18 | + |
| 19 | +When debugging Android NDK programs or applications, an Android device or |
| 20 | +emulator must be must be connected to the host machine and accessible via `adb`: |
| 21 | +```sh |
| 22 | +$ adb devices |
| 23 | +List of devices attached |
| 24 | +emulator-5554 device |
| 25 | +``` |
| 26 | + |
| 27 | +The port that ds2 is listening on must be forwarded to the connected host |
| 28 | +using `adb forward`: |
| 29 | +```sh |
| 30 | +$ adb forward tcp:4242 tcp:4242 |
| 31 | +``` |
| 32 | + |
| 33 | +To use ds2 on the Android target, copy the locally built ds2 binary to the |
| 34 | +`/data/local/tmp` directory on the Android target using `adb push` and launch it |
| 35 | +from there: |
| 36 | +```sh |
| 37 | +$ adb push build/ds2 /data/local/tmp |
| 38 | +$ adb shell /data/local/tmp/ds2 platform --server --listen *:4242 |
| 39 | +``` |
| 40 | + |
| 41 | +> [!NOTE] |
| 42 | +> If built on a Windows host, the ds2 executable file must also be marked |
| 43 | +> executable before launching it: |
| 44 | +> ```sh |
| 45 | +> $ adb shell chmod +x /data/local/tmp/ds2 |
| 46 | +> ``` |
| 47 | +
|
| 48 | +When debugging an Android application, the ds2 binary must be copied from |
| 49 | +`/data/local/tmp` into the target application's sandbox directory. This can be |
| 50 | +done using Android's `run-as` command: |
| 51 | +```sh |
| 52 | +$ adb shell run-as com.example.app cp /data/local/tmp/ds2 ./ds2 |
| 53 | +$ adb shell run-as com.example.app ./ds2 platform --server --listen *:4242 |
| 54 | +``` |
| 55 | +
|
| 56 | +> [!NOTE] |
| 57 | +> When running in an Android application's sandbox, the target application must |
| 58 | +> have internet permissions or ds2 will fail to open a port on launch: |
| 59 | +> ```xml |
| 60 | +> <uses-permission android:name="android.permission.INTERNET" /> |
| 61 | +> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> |
| 62 | +> ``` |
| 63 | +
|
| 64 | +### Run LLDB client on the local host |
| 65 | +
|
| 66 | +#### Platform Mode |
| 67 | +If ds2 was launched in `platform` mode (not supported on Windows), LLDB can |
| 68 | +connect to it using `platform` commands. |
| 69 | +
|
| 70 | +For a remote Linux host: |
| 71 | +``` |
| 72 | +$ lldb |
| 73 | +(lldb) platform select remote-linux |
| 74 | +(lldb) platform connect connect://localhost:4242 |
| 75 | +``` |
| 76 | +
|
| 77 | +For a remote Android host: |
| 78 | +``` |
| 79 | +$ lldb |
| 80 | +(lldb) platform select remote-android |
| 81 | +(lldb) platform connect connect://localhost:4242 |
| 82 | +(lldb) platform settings -w /data/local/tmp |
| 83 | +``` |
| 84 | +
|
| 85 | +> [!NOTE] |
| 86 | +> When running in an Android application's sandbox, the `platform settings -w` |
| 87 | +> command, which sets the working directory, is not necessary because the |
| 88 | +> it is already set to the root of the application's writable sandbox directory. |
| 89 | +
|
| 90 | +Once connected in platform mode, you can select the program to be run using the |
| 91 | +`file` command, run, and debug. |
| 92 | +``` |
| 93 | +(lldb) file /path/to/executable |
| 94 | +(lldb) b main |
| 95 | +(lldb) run |
| 96 | +``` |
| 97 | +
|
| 98 | +#### GDB Server Mode |
| 99 | +If ds2 was launched in `gdbserver` mode, LLDB can connect to it with the |
| 100 | +`gdb-remote` command: |
| 101 | +``` |
| 102 | +$ lldb /path/to/executable |
| 103 | +Current executable set to '/path/to/executable' (x86_64). |
| 104 | +(lldb) gdb-remote localhost:4242 |
| 105 | +Process 8336 stopped |
| 106 | +* thread #1: tid = 8336, 0x00007ffff7ddb2d0, name = 'executable', stop reason = signal SIGTRAP |
| 107 | + frame #0: 0x00007ffff7ddb2d0 |
| 108 | +-> 0x7ffff7ddb2d0: movq %rsp, %rdi |
| 109 | + 0x7ffff7ddb2d3: callq 0x7ffff7ddea70 |
| 110 | + 0x7ffff7ddb2d8: movq %rax, %r12 |
| 111 | + 0x7ffff7ddb2db: movl 0x221b17(%rip), %eax |
| 112 | +(lldb) b main |
| 113 | +Breakpoint 1: where = executable`main + 29 at test.cpp:6, address = 0x000000000040096d |
| 114 | +[...] |
| 115 | +(lldb) c |
| 116 | +Process 8336 resuming |
| 117 | +Process 8336 exited with status = 0 (0x00000000) |
| 118 | +(lldb) |
| 119 | +``` |
| 120 | +
|
| 121 | +### Command-Line Options |
| 122 | +
|
| 123 | +ds2 accepts the following options: |
| 124 | +
|
| 125 | +``` |
| 126 | +usage: ds2 [RUN_MODE] [OPTIONS] [[HOST]:PORT] [-- PROGRAM [ARGUMENTS...]] |
| 127 | + -a, --attach ARG attach to the name or PID specified |
| 128 | + -f, --daemonize detach and become a daemon |
| 129 | + -d, --debug enable debug log output |
| 130 | + -F, --fd ARG use a file descriptor to communicate |
| 131 | + -g, --gdb-compat force ds2 to run in gdb compat mode |
| 132 | + -o, --log-file ARG output log messages to the file specified |
| 133 | + -N, --named-pipe ARG determine a port dynamically and write back to FIFO |
| 134 | + -n, --no-colors disable colored output |
| 135 | + -D, --remote-debug enable log for remote protocol packets |
| 136 | + -R, --reverse-connect connect back to the debugger at [HOST]:PORT |
| 137 | + -e, --set-env ARG... add an element to the environment before launch |
| 138 | + -S, --setsid make ds2 run in its own session |
| 139 | + -E, --unset-env ARG... remove an element from the environment before lauch |
| 140 | + -l, --listen ARG specify the [host]:port to listen on |
| 141 | + [host]:port the [host]:port to connect to |
| 142 | +``` |
| 143 | +
|
| 144 | +After building ds2 for your host, run it with the binary to debug, or attach |
| 145 | +to an already running process. Then, start LLDB as usual and attach to the ds2 |
| 146 | +instance with the `gdb-remote` command. |
| 147 | +
|
| 148 | +The run mode and port number must be specified, where run mode is either |
| 149 | +`g[dbserver]` or `p[latform]`. In most cases, the `g[dbserver]` option is desired. |
0 commit comments