[Lldb-commits] [lldb] [lldb][Docs] Add page about debugging lldb itself (PR #65332)
David Spickett via lldb-commits
lldb-commits at lists.llvm.org
Wed Sep 6 01:10:45 PDT 2023
https://github.com/DavidSpickett updated https://github.com/llvm/llvm-project/pull/65332:
>From 5b094742811697096f6e614eca28b0ca5729dc4c Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Tue, 5 Sep 2023 15:04:05 +0100
Subject: [PATCH 1/3] [lldb][Docs] Add page about debugging lldb itself
We have docs about how to use lldb on other programs,
this tells you how to use lldb on ldlb and lldb-server.
Lacking any Mac experience I've not included any debugserver
information apart from stating it will be similar but not
the same.
I plan for this page to include sections on debugging tests
and other things but this initial commit is purely about
the two main binaries involved.
---
lldb/docs/index.rst | 1 +
lldb/docs/resources/debugging-lldb.rst | 254 +++++++++++++++++++++++++
2 files changed, 255 insertions(+)
create mode 100644 lldb/docs/resources/debugging-lldb.rst
diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst
index e12a4569cfdd2e..500800d4eaa1c0 100644
--- a/lldb/docs/index.rst
+++ b/lldb/docs/index.rst
@@ -148,6 +148,7 @@ interesting areas to contribute to lldb.
resources/contributing
resources/build
resources/test
+ resources/debugging-lldb
resources/fuzzing
resources/sbapi
resources/extensions
diff --git a/lldb/docs/resources/debugging-lldb.rst b/lldb/docs/resources/debugging-lldb.rst
new file mode 100644
index 00000000000000..7d49b1cdad7e4c
--- /dev/null
+++ b/lldb/docs/resources/debugging-lldb.rst
@@ -0,0 +1,254 @@
+Debugging LLDB
+==============
+
+This page details various ways to debug LLDB itself and other LLDB tools. If
+you want to know how to use LLDB in general, please refer to
+:doc:`/use/tutorial`.
+
+As LLDB is generally split into 2 tools, ``lldb`` and ``lldb-server``
+(``debugserver`` on Mac OS), the techniques shown here will not always apply to
+both. With some knowledge of them all, you can mix and match as needed.
+
+In this document we refer to the initial ``lldb`` as the debugger and the
+program being debugged as the debugee.
+
+Building For Debugging
+----------------------
+
+To build LLDB with debugging information add the following to your CMake
+configuration:
+
+::
+
+ -DCMAKE_BUILD_TYPE=Debug \
+ -DLLDB_EXPORT_ALL_SYMBOLS=1
+
+Note that the ``lldb`` you will use to do the debugging does not itself need to
+have debug information.
+
+Then build as you normally would.
+
+Debugging ``lldb``
+------------------
+
+The simplest scenario is where we want to debug a local execution of ``lldb``
+like this one:
+
+::
+
+ ./bin/lldb test_program
+
+LLDB is like any other program, so you can use the same approach.
+
+::
+
+ ./bin/lldb -- ./bin/lldb /tmp/test.o
+
+That's it. At least, that's the minimum. There's nothing special about LLDB
+being a debugger that means you can't attach another debugger to it like any
+other program.
+
+What can be an issue is that both debuggers have command line interfaces which
+makes it very confusing which one is which:
+
+::
+
+ (the debugger)
+ (lldb) run
+ Process 1741640 launched: '<...>/bin/lldb' (aarch64)
+ Process 1741640 stopped and restarted: thread 1 received signal: SIGCHLD
+
+ (the debugee)
+ (lldb) target create "/tmp/test.o"
+ Current executable set to '/tmp/test.o' (aarch64).
+
+Another issue is that when you resume the debugee, it will not print the
+``(lldb)`` prompt because as far as it knows it hasn't changed state. A quick
+way around that is to type something that is clearly not a command and hit
+enter.
+
+::
+
+ (lldb) Process 1742266 stopped and restarted: thread 1 received signal: SIGCHLD
+ Process 1742266 stopped
+ * thread #1, name = 'lldb', stop reason = signal SIGSTOP
+ frame #0: 0x0000ffffed5bfbf0 libc.so.6`__GI___libc_read at read.c:26:10
+ (lldb) c
+ Process 1742266 resuming
+ notacommand
+ error: 'notacommand' is not a valid command.
+ (lldb)
+
+You could just remember whether you are in the debugger or the debugee but
+it's thinking overhead, and for interrupt based events you simply may not be
+able to know.
+
+Here are some better approaches. First, you could use another debugger like GDB
+to debug LLDB. Perhaps an IDE like XCode or Visual Studio Code. Something which
+runs LLDB under the hood so you don't have to type in commands to the debugger
+yourself.
+
+Or you could change the prompt text for the debugger and/or debugee.
+
+::
+
+ $ ./bin/lldb -o "settings set prompt \"(lldb debugger) \"" -- \
+ ./bin/lldb -o "settings set prompt \"(lldb debuggee) \"" /tmp/test.o
+ <...>
+ (lldb) settings set prompt "(lldb debugger) "
+ (lldb debugger) run
+ <...>
+ (lldb) settings set prompt "(lldb debuggee) "
+ (lldb debuggee)
+
+If you want spacial separation you can run the debugee in one terminal then
+attach to it in another. Remember that while paused in the debugger, the debugee
+will not respond to input so you will have to ``continue`` in the debugger
+first.
+
+::
+
+ (in terminal A)
+ $ ./bin/lldb /tmp/test.o
+
+ (in terminal B)
+ $ ./bin/lldb ./bin/lldb --attach-pid $(pidof lldb)
+
+Placing Breakpoints
+*******************
+
+Generally you will want to hit some breakpoint in the debugee ``lldb``. To place
+that breakpoint you must first stop the debugee.
+
+If you're debugging from another window this is done with ``process interrupt``.
+The debugee will stop, you place the breakpoint and then ``continue``. Go back
+to the debugee and input the command that should trigger the breakpoint.
+
+If you are running debugger and debugee in the same window, input ``ctrl+c``
+instead of ``process interrupt`` and then folllow the rest of the steps.
+
+If you are doing this with ``lldb-server`` and find your breakpoint is never
+hit, check that you are breaking in code that is actually run by
+``lldb-server``. There are cases where code only used by ``lldb`` ends up
+linked into ``lldb-server``, so the debugger can break there but the breakpoint
+will never be hit.
+
+Debugging ``lldb-server``
+-------------------------
+
+Note: If you are on MacOS you are likely using ``debugserver`` instead of
+``lldb-server``. The spirit of these instructions applies but the specifics will
+be different.
+
+We suggest you read :doc:`/use/remote` before attempting to debug ``lldb-server``
+as working out exactly what you want to debug requires that you understand its
+various modes and behaviour. While you may not be literally debugging on a
+remote target, think of your host machine as the "remote" in this scenario.
+
+The ``lldb-server`` options for your situation will depend on what part of it
+or mode you are interested in. To work out what those are, recreate the scenario
+first without any extra debugging layers. Let's say we want to debug
+``lldb-server`` during the following command:
+
+::
+
+ $ ./bin/lldb /tmp/test.o
+
+We can treat ``lldb-server`` as we treated ``lldb`` before, running it under
+``lldb``. The equivalent to having ``lldb`` launch the ``lldb-server`` for us is
+to start ``lldb-server`` in the ``gdbserver`` mode.
+
+The following commands recreate that, while debugging ``lldb-server``:
+
+::
+
+ $ ./bin/lldb -- ./bin/lldb-server gdbserver :1234 /tmp/test.o
+ (lldb) target create "./bin/lldb-server"
+ Current executable set to '<...>/bin/lldb-server' (aarch64).
+ <...>
+ Process 1742485 launched: '<...>/bin/lldb-server' (aarch64)
+ Launched '/tmp/test.o' as process 1742586...
+
+ (in another terminal)
+ $ ./bin/lldb /tmp/test.o -o "gdb-remote 1234"
+
+Note that the first ``lldb`` is the one debugging ``lldb-server``. The second
+``lldb`` is debugging ``/tmp/test.o`` and is only used to trigger the
+interesting code path in ``lldb-server``.
+
+This is another case where you may want to layout your terminals in a
+predictable way, or change the prompt of one or both copies of ``lldb``.
+
+If you are debugging a scenario where the ``lldb-server`` starts in ``platform``
+mode, but you want to debug the ``gdbserver`` mode you'll have to work out what
+subprocess it's starting for the ``gdbserver`` part. One way is to look at the
+list of runninng processes and take the command line from there.
+
+In theory it should be possible to use LLDB's
+``target.process.follow-fork-mode`` or GDB's ``follow-fork-mode`` to
+automatically debug the ``gdbserver`` process as it's created. However this
+author has not been able to get either to work in this scenario so we suggest
+making a more specific command wherever possible instead.
+
+Output From ``lldb-server``
+***************************
+
+As ``lldb-server`` often launches subprocesses, output messages may be hidden
+if they are emitted from the child processes.
+
+You can tell it to enable logging using the ``--log-channels`` option. For
+example ``--log-channels "posix ptrace"``. However that is not passed on to the
+child processes.
+
+The same goes for ``printf``. If it's called in a child process you won't see
+the output.
+
+In these cases consider either interactive debugging ``lldb-server`` or
+working out a more specific command such that it does not have to spawn a
+subprocess. For example if you start with ``platform`` mode, work out what
+``gdbserver`` mode process it spawns and run that command instead.
+
+Remote Debugging
+----------------
+
+If you want to debug part of LLDB running on a remote machine, the principals
+are the same but we will have to start debug servers, then attach debuggers to
+those servers.
+
+In the example below we're debugging an ``lldb-server`` ``gdbserver`` mode
+command running on a remote machine.
+
+For simplicity we'll use the same ``lldb-server`` as the debug server
+and the debugee, but it doesn't need to be that way. You can use ``gdbserver``
+(as in, GDB's debug server program) or a system installed ``lldb-server`` if you
+suspect your local copy is not stable. As is the case in many of these
+scenarios.
+
+::
+
+ $ <...>/bin/lldb-server gdbserver 0.0.0.0:54322 -- \
+ <...>/bin/lldb-server gdbserver 0.0.0.0:54321 -- /tmp/test.o
+
+Now we have a debug server listening on port 54322 of our remote (``0.0.0.0``
+means it's listening for external connections). This is where we will connect
+``lldb`` to, to debug the second ``lldb-server``.
+
+To trigger behaviour in the second ``lldb-server``, we will connect a second
+``lldb`` to port 54321 of the remote.
+
+This is the final configuration:
+
+::
+
+ Host | Remote
+ --------------------------------------------|--------------------
+ lldb A debugs lldb-server on port 54322 -> | lldb-server A
+ | (which runs)
+ lldb B debugs /tmp/test.o on port 54321 -> | lldb-server B
+ | (which runs)
+ | /tmp/test.o
+
+You would use ``lldb A`` to place a breakpoint in the code you're interested in,
+then ``lldb B`` to trigger ``lldb-server B`` to go into that code and hit the
+breakpoint. ``lldb-server A`` is only here to let us debug ``lldb-server B``
+remotely.
>From ecb34e1b07b29efac95c0e9fb0193e2c3e2ddd24 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Wed, 6 Sep 2023 09:03:51 +0100
Subject: [PATCH 2/3] Respond to review comments
* Renamed page to just "debug", renamed the file.
* Link back to build documentation
* Fix Xcode naming.
* Note assertions option.
---
lldb/docs/index.rst | 2 +-
.../{debugging-lldb.rst => debugging.rst} | 16 +++++++++++-----
2 files changed, 12 insertions(+), 6 deletions(-)
rename lldb/docs/resources/{debugging-lldb.rst => debugging.rst} (94%)
diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst
index 500800d4eaa1c0..ab67531d415401 100644
--- a/lldb/docs/index.rst
+++ b/lldb/docs/index.rst
@@ -148,7 +148,7 @@ interesting areas to contribute to lldb.
resources/contributing
resources/build
resources/test
- resources/debugging-lldb
+ resources/debugging
resources/fuzzing
resources/sbapi
resources/extensions
diff --git a/lldb/docs/resources/debugging-lldb.rst b/lldb/docs/resources/debugging.rst
similarity index 94%
rename from lldb/docs/resources/debugging-lldb.rst
rename to lldb/docs/resources/debugging.rst
index 7d49b1cdad7e4c..fff64325bf99e4 100644
--- a/lldb/docs/resources/debugging-lldb.rst
+++ b/lldb/docs/resources/debugging.rst
@@ -1,5 +1,5 @@
-Debugging LLDB
-==============
+Debugging
+=========
This page details various ways to debug LLDB itself and other LLDB tools. If
you want to know how to use LLDB in general, please refer to
@@ -21,12 +21,17 @@ configuration:
::
-DCMAKE_BUILD_TYPE=Debug \
- -DLLDB_EXPORT_ALL_SYMBOLS=1
+ -DLLDB_EXPORT_ALL_SYMBOLS=ON
Note that the ``lldb`` you will use to do the debugging does not itself need to
have debug information.
-Then build as you normally would.
+Then build as you normally would according to :doc:`/resources/build`.
+
+If you are going to debug in a way that doesn't need debug info (printf, strace,
+etc.) we recommend adding ``LLVM_ENABLE_ASSERTIONS=ON`` to Release build
+configurations. This will make LLDB fail earlier instead of continuing with
+invalid state (assertions are enabled by default for Debug builds).
Debugging ``lldb``
------------------
@@ -84,7 +89,7 @@ it's thinking overhead, and for interrupt based events you simply may not be
able to know.
Here are some better approaches. First, you could use another debugger like GDB
-to debug LLDB. Perhaps an IDE like XCode or Visual Studio Code. Something which
+to debug LLDB. Perhaps an IDE like Xcode or Visual Studio Code. Something which
runs LLDB under the hood so you don't have to type in commands to the debugger
yourself.
@@ -252,3 +257,4 @@ You would use ``lldb A`` to place a breakpoint in the code you're interested in,
then ``lldb B`` to trigger ``lldb-server B`` to go into that code and hit the
breakpoint. ``lldb-server A`` is only here to let us debug ``lldb-server B``
remotely.
+
>From 4fb778535d6bbd76539243398ab74ad4346e56cc Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Wed, 6 Sep 2023 09:08:14 +0100
Subject: [PATCH 3/3] Replace "debugee" with "inferior"
---
lldb/docs/resources/debugging.rst | 38 +++++++++++++++----------------
1 file changed, 19 insertions(+), 19 deletions(-)
diff --git a/lldb/docs/resources/debugging.rst b/lldb/docs/resources/debugging.rst
index fff64325bf99e4..0cd310e079c23f 100644
--- a/lldb/docs/resources/debugging.rst
+++ b/lldb/docs/resources/debugging.rst
@@ -9,8 +9,8 @@ As LLDB is generally split into 2 tools, ``lldb`` and ``lldb-server``
(``debugserver`` on Mac OS), the techniques shown here will not always apply to
both. With some knowledge of them all, you can mix and match as needed.
-In this document we refer to the initial ``lldb`` as the debugger and the
-program being debugged as the debugee.
+In this document we refer to the initial ``lldb`` as the "debugger" and the
+program being debugged as the "inferior".
Building For Debugging
----------------------
@@ -63,11 +63,11 @@ makes it very confusing which one is which:
Process 1741640 launched: '<...>/bin/lldb' (aarch64)
Process 1741640 stopped and restarted: thread 1 received signal: SIGCHLD
- (the debugee)
+ (the inferior)
(lldb) target create "/tmp/test.o"
Current executable set to '/tmp/test.o' (aarch64).
-Another issue is that when you resume the debugee, it will not print the
+Another issue is that when you resume the inferior, it will not print the
``(lldb)`` prompt because as far as it knows it hasn't changed state. A quick
way around that is to type something that is clearly not a command and hit
enter.
@@ -84,30 +84,30 @@ enter.
error: 'notacommand' is not a valid command.
(lldb)
-You could just remember whether you are in the debugger or the debugee but
-it's thinking overhead, and for interrupt based events you simply may not be
-able to know.
+You could just remember whether you are in the debugger or the inferior but
+it's more for you to remember, and for interrupt based events you simply may not
+be able to know.
Here are some better approaches. First, you could use another debugger like GDB
to debug LLDB. Perhaps an IDE like Xcode or Visual Studio Code. Something which
runs LLDB under the hood so you don't have to type in commands to the debugger
yourself.
-Or you could change the prompt text for the debugger and/or debugee.
+Or you could change the prompt text for the debugger and/or inferior.
::
$ ./bin/lldb -o "settings set prompt \"(lldb debugger) \"" -- \
- ./bin/lldb -o "settings set prompt \"(lldb debuggee) \"" /tmp/test.o
+ ./bin/lldb -o "settings set prompt \"(lldb inferior) \"" /tmp/test.o
<...>
(lldb) settings set prompt "(lldb debugger) "
(lldb debugger) run
<...>
- (lldb) settings set prompt "(lldb debuggee) "
- (lldb debuggee)
+ (lldb) settings set prompt "(lldb inferior) "
+ (lldb inferior)
-If you want spacial separation you can run the debugee in one terminal then
-attach to it in another. Remember that while paused in the debugger, the debugee
+If you want spacial separation you can run the inferior in one terminal then
+attach to it in another. Remember that while paused in the debugger, the inferior
will not respond to input so you will have to ``continue`` in the debugger
first.
@@ -122,14 +122,14 @@ first.
Placing Breakpoints
*******************
-Generally you will want to hit some breakpoint in the debugee ``lldb``. To place
-that breakpoint you must first stop the debugee.
+Generally you will want to hit some breakpoint in the inferior ``lldb``. To place
+that breakpoint you must first stop the inferior.
If you're debugging from another window this is done with ``process interrupt``.
-The debugee will stop, you place the breakpoint and then ``continue``. Go back
-to the debugee and input the command that should trigger the breakpoint.
+The inferior will stop, you place the breakpoint and then ``continue``. Go back
+to the inferior and input the command that should trigger the breakpoint.
-If you are running debugger and debugee in the same window, input ``ctrl+c``
+If you are running debugger and inferior in the same window, input ``ctrl+c``
instead of ``process interrupt`` and then folllow the rest of the steps.
If you are doing this with ``lldb-server`` and find your breakpoint is never
@@ -224,7 +224,7 @@ In the example below we're debugging an ``lldb-server`` ``gdbserver`` mode
command running on a remote machine.
For simplicity we'll use the same ``lldb-server`` as the debug server
-and the debugee, but it doesn't need to be that way. You can use ``gdbserver``
+and the inferior, but it doesn't need to be that way. You can use ``gdbserver``
(as in, GDB's debug server program) or a system installed ``lldb-server`` if you
suspect your local copy is not stable. As is the case in many of these
scenarios.
More information about the lldb-commits
mailing list