lldb/docs/use/remote.rst

   1 Remote Debugging
   2 ================
   3
   4 Remote debugging refers to the act of debugging a process which is running on a
   5 different system, than the debugger itself. We shall refer to the system
   6 running the debugger as the local system, while the system running the debugged
   7 process will be the remote system.
   8
   9 To enable remote debugging, LLDB employs a client-server architecture. The
  10 client part runs on the local system and the remote system runs the server. The
  11 client and server communicate using the gdb-remote protocol, usually
  12 transported over TCP/IP. More information on the protocol can be found here and
  13 the LLDB-specific extensions are documented in docs/lldb-gdb-remote.txt file
  14 inside LLDB source repository. Besides the gdb-remote stub, the server part of
  15 LLDB also consists of a platform binary, which is responsible for performing
  16 advanced debugging operations, like copying files from/to the remote system and
  17 can be used to execute arbitrary shell commands on the remote system.
  18
  19 In order to reduce code complexity and improve remote debugging experience LLDB
  20 on Linux and macOS uses the remote debugging stub even when debugging a process
  21 locally. This is achieved by spawning a remote stub process locally and
  22 communicating with it over the loopback interface. In the case of local
  23 debugging this whole process is transparent to the user. The platform binary is
  24 not used in this case, since no file transfers are needed.
  25
  26 Preparation for Remote Debugging
  27 ---------------------------------
  28
  29 While the process of actual debugging (stepping, backtraces, evaluating
  30 expressions) is same as in the local case, in the case of remote debugging,
  31 more preparation is needed as the required binaries cannot started on the
  32 remote system automatically. Also, if the remote system runs a different OS or
  33 architecture, the server component needs to be compiled separately.
  34
  35 Remote system
  36 *************
  37
  38 On Linux and Android, all required remote functionality is contained in the
  39 lldb-server binary. This binary combines the functionality of the platform and
  40 gdb-remote stub. A single binary facilitates deployment and reduces code size,
  41 since the two functions share a lot of code. The lldb-server binary is also
  42 statically linked with the rest of LLDB (unlike lldb, which dynamically links
  43 to liblldb.so by default), so it does not have any dependencies on the rest of
  44 lldb. On macOS and iOS, the remote-gdb functionality is implemented by the
  45 debugserver binary, which you will need to deploy alongside lldb-server.
  46
  47 The binaries mentioned above need to be present on the remote system to enable
  48 remote debugging. You can either compile on the remote system directly or copy
  49 them from the local machine. If compiling locally and the remote architecture
  50 differs from the local one, you will need to cross-compile the correct version
  51 of the binaries. More information on cross-compiling LLDB can be found on the
  52 build page.
  53
  54 Once the binaries are in place, you just need to run the lldb-server in
  55 platform mode and specify the port it should listen on. For example, the
  56 command
  57
  58 ::
  59
  60    remote% lldb-server platform --listen "*:1234" --server
  61
  62 will start the LLDB platform and wait for incoming connections from any address
  63 to port 1234. Specifying an address instead of * will only allow connections
  64 originating from that address. Adding a --server parameter to the command line
  65 will fork off a new process for every incoming connection, allowing multiple
  66 parallel debug sessions.
  67
  68 Local system
  69 ************
  70
  71 On the local system, you need to let LLDB know that you intend to do remote
  72 debugging. This is achieved through the platform command and its sub-commands.
  73 As a first step you need to choose the correct platform plug-in for your remote
  74 system. A list of available plug-ins can be obtained through platform list.
  75
  76 ::
  77
  78    local% lldb
  79    (lldb) platform list
  80    Available platforms:
  81    host: Local macOS user platform plug-in.
  82    remote-freebsd: Remote FreeBSD user platform plug-in.
  83    remote-linux: Remote Linux user platform plug-in.
  84    remote-netbsd: Remote NetBSD user platform plug-in.
  85    remote-windows: Remote Windows user platform plug-in.
  86    remote-android: Remote Android user platform plug-in.
  87    remote-ios: Remote iOS platform plug-in.
  88    remote-macosx: Remote macOS user platform plug-in.
  89    ios-simulator: iOS simulator platform plug-in.
  90    darwin-kernel: Darwin Kernel platform plug-in.
  91    tvos-simulator: Apple TV simulator platform plug-in.
  92    watchos-simulator: Apple Watch simulator platform plug-in.
  93    remote-tvos: Remote Apple TV platform plug-in.
  94    remote-watchos: Remote Apple Watch platform plug-in.
  95    remote-gdb-server: A platform that uses the GDB remote protocol as the communication transport.
  96
  97 The default platform is the platform host which is used for local debugging.
  98 Apart from this, the list should contain a number of plug-ins, for debugging
  99 different kinds of systems. The remote plug-ins are prefixed with "remote-".
 100 For example, to debug a remote Linux application:
 101
 102 ::
 103
 104    (lldb) platform select remote-linux
 105
 106 After selecting the platform plug-in, you should receive a prompt which
 107 confirms the selected platform, and states that you are not connected. This is
 108 because remote plug-ins need to be connected to their remote platform
 109 counterpart to operate. This is achieved using the platform connect command.
 110 This command takes a number of arguments (as always, use the help command to
 111 find out more), but normally you only need to specify the address to connect
 112 to, e.g.:
 113
 114 ::
 115
 116    (lldb) platform connect connect://remote:1234
 117      Platform: remote-linux
 118        Triple: x86_64-gnu-linux
 119      Hostname: remote
 120     Connected: yes
 121    WorkingDir: /tmp
 122
 123 Note that the platform has a working directory of /tmp. This directory will be
 124 used as the directory that executables will be uploaded to by default when
 125 launching a process from local.
 126
 127 After this, you should be able to debug normally. You can use the process
 128 attach to attach to an existing remote process or target create, process launch
 129 to start a new one. The platform plugin will transparently take care of
 130 uploading or downloading the executable in order to be able to debug. If your
 131 application needs additional files, you can transfer them using the platform
 132 commands: get-file, put-file, mkdir, etc. The environment can be prepared
 133 further using the platform shell command.
 134
 135 When using the "remote-android" platform, the client LLDB forwards two ports, one
 136 for connecting to the platform, and another for connecting to the gdbserver.
 137 The client ports are configurable through the environment variables
 138 ANDROID_PLATFORM_LOCAL_PORT and ANDROID_PLATFORM_LOCAL_GDB_PORT, respectively.
 139
 140 Launching a locally built process on the remote machine
 141 -------------------------------------------------------
 142
 143 Install and run in the platform working directory
 144 *************************************************
 145
 146 To launch a locally built process on the remote system in the platform working
 147 directory:
 148
 149 ::
 150
 151    (lldb) file a.out
 152    (lldb) run
 153
 154 This will cause LLDB to create a target with the "a.out" executable that you
 155 cross built. The "run" command will cause LLDB to upload "a.out" to the
 156 platform's current working directory only if the file has changed. The platform
 157 connection allows us to transfer files, but also allows us to get the MD5
 158 checksum of the file on the other end and only upload the file if it has
 159 changed. LLDB will automatically launch a lldb-server in gdbremote mode to
 160 allow you to debug this executable, connect to it and start your debug session
 161 for you.
 162
 163 Changing the platform working directory
 164 ***************************************
 165
 166 You can change the platform working directory while connected to the platform
 167 with:
 168
 169 ::
 170
 171    (lldb) platform settings -w /usr/local/bin
 172
 173 And you can verify it worked using "platform status":
 174
 175 ::
 176
 177    (lldb) platform status
 178      Platform: remote-linux
 179        Triple: x86_64-gnu-linux
 180      Hostname: remote
 181     Connected: yes
 182    WorkingDir: /usr/local/bin
 183
 184 If we run again, the program will be installed into ``/usr/local/bin``.
 185
 186 Install and run by specifying a remote install path
 187 ***************************************************
 188
 189 If you want the "a.out" executable to be installed into "/bin/a.out" instead of
 190 the platform's current working directory, we can set the platform file
 191 specification using python:
 192
 193 ::
 194
 195    (lldb) file a.out
 196    (lldb) script lldb.target.module['a.out'].SetPlatformFileSpec("/bin/a.out")
 197    (lldb) run
 198
 199 Now when you run your program, the program will be uploaded to "/bin/a.out"
 200 instead of the platform current working directory. Only the main executable is
 201 uploaded to the remote system by default when launching the application. If you
 202 have shared libraries that should also be uploaded, then you can add the
 203 locally build shared library to the current target and set its platform file
 204 specification:
 205
 206 ::
 207
 208    (lldb) file a.out
 209    (lldb) target module add /local/build/libfoo.so
 210    (lldb) target module add /local/build/libbar.so
 211    (lldb) script lldb.target.module['libfoo.so'].SetPlatformFileSpec("/usr/lib/libfoo.so")
 212    (lldb) script lldb.target.module['libbar.so'].SetPlatformFileSpec("/usr/local/lib/libbar.so")
 213    (lldb) run
 214
 215 Attaching to a remote process
 216 *****************************
 217
 218 If you want to attach to a remote process, you can first list the processes on
 219 the remote system:
 220
 221 ::
 222
 223    (lldb) platform process list
 224    223 matching processes were found on "remote-linux"
 225    PID    PARENT USER       TRIPLE                   NAME
 226    ====== ====== ========== ======================== ============================
 227    68639  90652             x86_64-apple-macosx      lldb
 228    ...
 229
 230 Then attaching is as simple as specifying the remote process ID:
 231
 232 ::
 233
 234    (lldb) attach 68639