Skip to content

Commit 7547aca

Browse files
author
Greg Clayton
committedNov 28, 2017
Update remote debugging page with many more details.
llvm-svn: 319213
·
llvmorg-21-initllvmorg-6.0.0-rc1
1 parent 28c65bc commit 7547aca

File tree

1 file changed

+132
-8
lines changed

1 file changed

+132
-8
lines changed
 

‎lldb/www/remote.html

+132-8
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,9 @@ <h2>Remote system</h2>
8686
Once the binaries are in place, you just need to run the <code>lldb-server</code>
8787
in platform mode and specify the port it should listen on. For example, the command
8888
</p>
89-
<code>lldb-server platform --listen *:1234</code>
89+
<code>
90+
remote% <b>lldb-server platform --listen "*:1234" --server</b>
91+
</code>
9092
<p>
9193
will start the LLDB platform and wait for incoming connections from any address to
9294
port 1234. Specifying an address instead of <code>*</code> will only allow
@@ -104,14 +106,35 @@ <h2>Local system</h2>
104106
your remote system. A list of available plug-ins can be obtained through
105107
<code>platform list</code>.
106108
</p>
107-
109+
<code>
110+
local% <b>lldb</b>
111+
<br>(lldb) <b>platform list</b>
112+
<br>Available platforms:
113+
<br>host: Local Mac OS X user platform plug-in.
114+
<br>remote-freebsd: Remote FreeBSD user platform plug-in.
115+
<br>remote-linux: Remote Linux user platform plug-in.
116+
<br>remote-netbsd: Remote NetBSD user platform plug-in.
117+
<br>remote-windows: Remote Windows user platform plug-in.
118+
<br>remote-android: Remote Android user platform plug-in.
119+
<br>remote-ios: Remote iOS platform plug-in.
120+
<br>remote-macosx: Remote Mac OS X user platform plug-in.
121+
<br>ios-simulator: iOS simulator platform plug-in.
122+
<br>darwin-kernel: Darwin Kernel platform plug-in.
123+
<br>tvos-simulator: Apple TV simulator platform plug-in.
124+
<br>watchos-simulator: Apple Watch simulator platform plug-in.
125+
<br>remote-tvos: Remote Apple TV platform plug-in.
126+
<br>remote-watchos: Remote Apple Watch platform plug-in.
127+
<br>remote-gdb-server: A platform that uses the GDB remote protocol as the communication transport.
128+
</code>
108129
<p>
109130
The default platform is the platform <code>host</code> which is used for local
110131
debugging. Apart from this, the list should contain a number of plug-ins, for
111132
debugging different kinds of systems. The remote plug-ins are prefixed with
112-
"<code>remote-</code>". For example, to debug a remote Linux application, you should
113-
run <code>platform select remote-linux</code>.
114-
</p>
133+
"<code>remote-</code>". For example, to debug a remote Linux application:
134+
<br>
135+
<code>
136+
<br>(lldb) <b>patform select remote-linux</b>
137+
</code>
115138

116139
<p>
117140
After selecting the platform plug-in, you should receive a prompt which confirms
@@ -121,9 +144,19 @@ <h2>Local system</h2>
121144
command takes a number of arguments (as always, use the <code>help</code> command
122145
to find out more), but normally you only need to specify the address to connect to,
123146
e.g.:
124-
</p>
125-
<code>platform connect connect://host:port</code>
126-
147+
<br>
148+
<code>
149+
<br>(lldb) <b>platform connect connect://remote:1234</b>
150+
<br>&nbsp;&nbsp;Platform: remote-linux
151+
<br>&nbsp;&nbsp;&nbsp;&nbsp;Triple: x86_64-gnu-linux
152+
<br>&nbsp;&nbsp;Hostname: remote
153+
<br>&nbsp;Connected: yes
154+
<br>WorkingDir: /tmp
155+
</code>
156+
<p>
157+
Note that the platform has a working directory of <code>/tmp</code>. This directory
158+
will be used as the directory that executables will be uploaded to by default when
159+
launching a process from <em>local</em>.
127160
<p>
128161
After this, you should be able to debug normally. You can use the
129162
<code>process attach</code> to attach to an existing remote process or
@@ -134,7 +167,98 @@ <h2>Local system</h2>
134167
<code>put-file</code>, <code>mkdir</code>, etc. The environment can be prepared
135168
further using the <code>platform shell</code> command.
136169
</p>
170+
<h3>Launching a locally built process on the remote machine</h3>
171+
<h4>Install and run in the platform working directory</h4>
172+
<p>
173+
To launch a locally built process on the remote system in the
174+
platform working directory:
175+
<br>
176+
<code>
177+
<br>(lldb) <b>file a.out</b>
178+
<br>(lldb) <b>run</b>
179+
</code>
180+
<p>
181+
This will cause LLDB to create a target with the "a.out"
182+
executable that you cross built. The "run" command will cause
183+
LLDB to upload "a.out" to the platform's current working
184+
directory only if the file has changed.
185+
The platform connection allows us to transfer files, but also
186+
allows us to get the MD5 checksum of the file on the other end
187+
and only upload the file if it has changed. LLDB will automatically
188+
launch a lldb-server in gdbremote mode to allow you to debug this
189+
executable, connect to it and start your debug session for you.
190+
</p>
191+
<h4>Changing the platform working directory</h4>
192+
<p>
193+
You can change the platform working directory while connected to
194+
the platform with:
195+
<br>
196+
<code>
197+
<br>(lldb) <b>platform settings -w /usr/local/bin</b>
198+
</code>
199+
<p>
200+
And you can verify it worked using "platform status":
201+
<br>
202+
<code>
203+
<br>(lldb) <b>platform status</b>
204+
<br>&nbsp;&nbsp;Platform: remote-linux
205+
<br>&nbsp;&nbsp;&nbsp;&nbsp;Triple: x86_64-gnu-linux
206+
<br>&nbsp;&nbsp;Hostname: remote
207+
<br>&nbsp;Connected: yes
208+
<br>WorkingDir: /usr/local/bin
209+
</code>
210+
<p>
211+
If we run again, the program will be installed into /usr/local/bin.
212+
</p>
213+
137214

215+
<h4>Install and run by specifying a remote install path</h4>
216+
<p>
217+
If you want the "a.out" executable to be installed into
218+
"/bin/a.out" instead of the platorm's current working directory,
219+
we can set the platform file specification using python:
220+
<br>
221+
<code>
222+
<br>(lldb) <b>file a.out</b>
223+
<br>(lldb) <b>script lldb.target.module['a.out'].SetPlatformFileSpec("/bin/a.out")</b>
224+
<br>(lldb) <b>run</b>
225+
</code>
226+
<p>
227+
Now when you run your program, the program will be uploaded to
228+
"/bin/a.out" instead of the the platform current working directory.
229+
Only the main executable is uploaded to the remote system by
230+
default when launching the application. If you have shared
231+
libraries that should also be uploaded, then you can add the
232+
locally build shared library to the current target and set its
233+
platform file specification:
234+
</p>
235+
<code>
236+
<br>(lldb) <b>file a.out</b>
237+
<br>(lldb) <b>target module add /local/build/libfoo.so</b>
238+
<br>(lldb) <b>target module add /local/build/libbar.so</b>
239+
<br>(lldb) <b>script lldb.target.module['libfoo.so'].SetPlatformFileSpec("/usr/lib/libfoo.so")</b>
240+
<br>(lldb) <b>script lldb.target.module['libbar.so'].SetPlatformFileSpec("/usr/local/lib/libbar.so")</b>
241+
<br>(lldb) <b>run</b>
242+
</code>
243+
<h4>Attaching to a remote process</h4>
244+
<p>
245+
If you want to attach to a remote process, you can first list the
246+
processes on the remote system:
247+
</p>
248+
<code>
249+
<br>(lldb) <b>platform process list</b>
250+
<br>223 matching processes were found on "remote-linux"
251+
<br>PID&nbsp;&nbsp;&nbsp;&nbsp;PARENT&nbsp;USER&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;TRIPLE&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NAME
252+
<br>======&nbsp;======&nbsp;==========&nbsp;========================&nbsp;============================
253+
<br>68639&nbsp;&nbsp;90652&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x86_64-apple-macosx&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;lldb
254+
<br>...
255+
</code>
256+
<p>
257+
Then attaching is as simple as specifying the remote process ID:
258+
</p>
259+
<code>
260+
<br>(lldb) <b>attach 68639</b>
261+
</code>
138262
</div>
139263
<div class="postfooter"></div>
140264
</div>

0 commit comments

Comments
 (0)
Please sign in to comment.