[Lldb-commits] [lldb] [lldb][Docs] Add page about debugging lldb itself (PR #65332)

Tue Sep 5 07:58:37 PDT 2023

================
@@ -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
----------------
DavidSpickett wrote:

This could be user error but the point is preventing people wasting their time on it if it is indeed not possible.

I'd be happy to be proven wrong.

https://github.com/llvm/llvm-project/pull/65332
