Recently building libc++ requires building libunwind too. This updates
the LLDB instructions.
I noticed this recently and it was separately filed as
https://github.com/llvm/llvm-project/issues/84053
This explains a thing that hit me on FreeBSD because the base system
has an ncursesw at one version and I installed from pkg another
version that was simply ncurses (no wide char support).
For whatever reason, when we pass -lcurses to the linker it ends up
picking bits of both installs. This led to lldb crashing immediately
if you tried to use the `gui` command.
In a way that gave little information but I stumbled onto
https://github.com/vifm/vifm/issues/325 which is very similar.
```
ec2-user@freebsd:~/build-llvm $ ldd ./bin/lldb | grep curses
libncursesw.so.9 => /lib/libncursesw.so.9 (0x6a515206e000)
libncurses.so.6 => /usr/local/lib/libncurses.so.6 (0x6a5158e86000)
```
We should only see one version, and it and libpanel etc should
all have "w" or not have "w". This was not the case for my build.
What I can see from the CMake side seemed fine, it found the pkg
installed ncurses in /usr/local. Something else must decide that
-lcurses should pull in the other one.
Regardless, I don't know how to fix that but the solution for most
people is just not to add another ncurses if they already have one.
So I've added a note saying so, and how to check what your lldb
is using.
debugserver will not compress small packets; the overhead of the
compression header makes this useful for larger packets. I default to
384 bytes in debugserver, and added an option for lldb to request a
different cutoff. This option has never been used in lldb in the past
nine years, so I don't think there's any point to keeping it around.
debugserver on arm64 devices can manage both Byte Address Select
watchpoints (1-8 bytes) and MASK watchpoints (8 bytes-2 gigabytes). This
adds a SupportedWatchpointTypes key to the QSupported response from
debugserver with a list of these, so lldb can take full advantage of
them when creating larger regions with a single hardware watchpoint.
Also add documentation for this, and two other lldb extensions, to the
lldb-gdb-remote.txt documentation.
Re-enable TestLargeWatchpoint.py on Darwin systems when testing with the
in-tree built debugserver. I can remove the "in-tree built debugserver"
in the future when this new key is handled by an Xcode debugserver.
The Watchpoint and Breakpoint objects try to track the hardware index
that was used for them, if they are hardware wp/bp's. The majority of
our debugging goes over the gdb remote serial protocol, and when we set
the watchpoint/breakpoint, there is no (standard) way for the remote
stub to communicate to lldb which hardware index was used. We have an
lldb-extension packet to query the total number of watchpoint registers.
When a watchpoint is hit, there is an lldb extension to the stop reply
packet (documented in lldb-gdb-remote.txt) to describe the watchpoint
including its actual hardware index,
<addr within wp range> <wp hw index> <actual accessed address>
(the third field is specifically needed for MIPS). At this point, if the
stub reported these three fields (the stub is only required to provide
the first), we can know the actual hardware index for this watchpoint.
Breakpoints are worse; there's never any way for us to be notified about
which hardware index was used. Breakpoints got this as a side effect of
inherting from StoppointSite with Watchpoints.
We expose the watchpoint hardware index through "watchpoint list -v" and
through SBWatchpoint::GetHardwareIndex.
With my large watchpoint support, there is no *single* hardware index
that may be used for a watchpoint, it may need multiple resources. Also
I don't see what a user is supposed to do with this information, or an
IDE. Knowing the total number of watchpoint registers on the target, and
knowing how many Watchpoint Resources are currently in use, is helpful.
Knowing how many Watchpoint Resources
a single user-specified watchpoint needed to be implemented is useful.
But knowing which registers were used is an implementation detail and
not available until we hit the watchpoint when using gdb remote serial
protocol.
So given all that, I'm removing watchpoint hardware index numbers. I'm
changing the SB API to always return -1.
The instructions for running single tests in the LLDB test suite used an
older directory structure from before the LLVM project became a
monorepo. This commit updates the references to these directories.
This patch updates the documentation to match recent changes and make it
more clear. More specifically, the process for installing sphinx has
changed with the transition to myst with the requirements.txt in
llvm/docs being the preferred method for installation now. In addition,
the docs-lldb-html target is never generated if swig isn't installed, so
having something expliti in the documentation section (even if it is
mentioned as a dependency of lldb itself above) probably doesn't hurt.
Before target.xml, lldb had its own method for querying the remote stub
of the registers it supports, qRegisterInfo. The gdb standard method of
using a target.xml file to describe the available registers has become
commonplace, and the lldb method for doing this is no longer needed.
Stubs should describe their registers to lldb, but it should be with the
target.xml file.
This adds a release note for all the SME support now in LLDB and a page
where I have documented the user experience (for want of a better term)
when using SVE and SME.
This includes things like which mode transitions can or cannot be
triggered from within LLDB. I hope this will serve to A: document what
I've implemented and B: be a user's guide to these extensions.
(though it is not a design document, read the commits and code for that
sort of detail)
Bridge network means that you can get to any port on the VM,
from the host, which is great. However it is quite involved to
setup in some cases, and I've certainly messed it up in the past.
An alternative is forwarding a block of ports and using some
hidden options to lldb-server to limit what it uses. This
commit documents that and the pitfall that the port list isn't shared.
The theory also works for Arm's FVP (which inspired me to write
this up) but since QEMU is the preferred option upstream, it goes
in that document.
Along the way I fixed a link to the QEMU page that used the URL
not a relative link to the document.
Running:
$ clang-format -i $(find -regex "\./lldb/.*\.c") $(find -regex
"\./lldb/.*\.cpp") $(find -regex "\./lldb/.*\.h")
Resulted in:
1602 files changed, 25090 insertions(+), 25849 deletions(-)
(note: this includes tests which we wouldn't format, just using this as
an example)
The vast majority of which were whitespace changes. So as far as
formatting we're not deviating from llvm for any reason other than not
churning old code.
Formatting aside, the major features of lldb (single line if, early
return) are all reflected in llvm's style. We differ mainly on variable
naming (proposed to change in
https://llvm.org/docs/Proposals/VariableNames.html anyway) and use of
asserts. Which was already documented.
This is a (rough) port of architecture/varformats.html page that got
lost during the migration to RST in edb874b. I'm not sure how much of
its content is still relevant today. However, the page is pretty
extensive and seems like it's worth preserving.
Neither actually linked anywhere, but I did find a good target for the
introduction.
For the architecture side I don't see a page that would fit, so I've
just removed the sentence.
The testing page already has some page about debugging failures.
I'm not linking directly to that section because:
* The earlier sections about running single tests and such
are just as useful for debugging in general.
* The new theme has a nice sidebar on the right that makes
it really easy to find what you want once on the page.
* We'll probably add more content to the testing page later.
In the LDDB documentation you have the following sentence:
"The --format (which you can shorten to -f) option accepts a format name."
The link points to the wrong place.
I pointed it to the table that precedes the Type summary section.
Reviewed By: DavidSpickett
Differential Revision: https://reviews.llvm.org/D151668
The issues link as it was was including PRs, so I've made that
issues only and only those in an open state.
Code review is now on Gtihub so same thing, PRs only, open state,
label lldb.
Adds the following:
* A note that you can use attaching to debug the right lldb-server
process, though there are drawbacks.
* A section on debugging the remote protocol.
* Reducing bugs, including reducing ptrace bugs to remove the need for
LLDB.
I've added a standlone ptrace program to the examples folder because:
* There's no better place to put it.
* Adding it to the page seems like wasting space, and would be harder to
update.
* I link to Eli Bendersky's classic blog on the subject, but we are
safer with our own example as well.
* Eli's example is for 32 bit Intel, AArch64 is more common these days.
* It's easier to show the software breakpoint steps in code than explain
it (though I still do that in the text).
* It was living on my laptop not helping anyone so I think it's good to
have it upstream for others, including future me.
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.
The main way I cross build lldb is to point CMake at an existing host
build to get the native tablegen tools. This is what we had documented
before.
There is another option where you start from scratch and the host tools
are built for you. This patch documents that and explains which one to
choose.
Added another arm64 example which uses this. So the frst one is the
"automatic" build and the second is the traditional approach.
For ease of copy paste and understanding, I've kept the full command in
each section and noted the one difference between them.
Along the way I updated some of the preamble to explain the two
approaches and updated some language e.g. removing "just ...". Eveyone's
"just" is different, doubly so when cross-compiling.
This patch re-lands f0731d5b61 with more fixes and improvements.
First, this patch removes `__eq__` implementations from classes that
didn't implemented `operator!=` on the C++ implementation.
This patch removes sphinx document generation for special members such
as `__len__`, since there is no straightforward way to skip class that
don't implement them. We also don't want to introduce a change in
behavior by implementing artifical special members for classes that are
missing them.
Finally, this patch improve the ergonomics of some classes by
implementing special members where it makes sense, i.e. `hex(SBFrame)`
is equivalent to `SBFrame.GetPC()`.
Differential Revision: https://reviews.llvm.org/D159017
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This reverts 3 commit:
- f0731d5b61.
- 8e0a087571.
- f2f5d6fb8d.
This changes were introduced to silence the warnings that are printed
when generating the lldb module documentation for the website but it
changed the python bindings and causes test failures on the macos bot:
https://green.lab.llvm.org/green/job/lldb-cmake/59438/
We will have to consider other options to silence these warnings.
This reverts commit 18f1c1ace7 and fix the
build failure issues introduced because of the `STRING_EXTENSION_OUTSIDE`
swig macros.
Differential Revision: https://reviews.llvm.org/D159017
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch does various things to silence the warnings that show up when
generating the website documentation.
First, this patch adds the missing definition for special member methods
in every SBAPI class. If the class cannot implement one of the special
member method, we just define it as a null operation (pass).
This should fix the following warnings:
```
WARNING: missing attribute __int__ in object lldb.SB*
WARNING: missing attribute __len__ in object lldb.SB*
WARNING: missing attribute __hex__ in object lldb.SB*
WARNING: missing attribute __oct__ in object lldb.SB*
WARNING: missing attribute __iter__ in object lldb.SB*
```
Then, it un-skips the various `static` methods that we didn't generate
the methods for, since it's not necessary thanks to the automod-api module.
Finally, this comments out the `_static` directory in the sphinx config,
since we don't need it anymore.
Differential Revision: https://reviews.llvm.org/D159017
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch brings a fresh coat of paint to the LLDB website.
This uses the `furo` theme from the suggested theme list, adds some
changes to the css to make it use the full browser window width and
removes the table of contents since the theme generates it automatically.
This patch also rewrites the tables for "GDB to LLDB command map" to
convert them from raw HTML to native inlined code blocks.
To generate the website, make sure you install the theme first with
`pip install furo`, enable sphinx in the cmake invocation` then run
`ninja docs-lldb-html`
Discourse: https://discourse.llvm.org/t/rfc-revamping-lldbs-website
Differential Revision: https://reviews.llvm.org/D158323
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch reverts the lldb website revamp (eea8874) since the `furo` theme
that we use is not installed on the publisher bot. The prevents other
website from getting there documentation updated.
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch brings a fresh coat of paint to the LLDB website.
This uses the `furo` theme from the suggested theme list, adds some
changes to the css to make it use the full browser window width and
removes the table of contents since the theme generates it automatically.
This patch also rewrites the tables for "GDB to LLDB command map" to
convert them from raw HTML to native inlined code blocks.
To generate the website, make sure you install the theme first with
`pip install furo`, enable sphinx in the cmake invocation` then run
`ninja docs-lldb-html`
Discourse: https://discourse.llvm.org/t/rfc-revamping-lldbs-website
Differential Revision: https://reviews.llvm.org/D158323
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
To address https://github.com/llvm/llvm-project/issues/64616, this change
does the following:
* Links back to the "Optional Dependencies" section from the cross
compilation instructions where we talk about removing libraries.
In the reported issue, the host libXML was found by CMAke somehow and
disabling libXML fixed it, so this link should encourage users
to try as many of those options as needed.
* Removes the use of CMAKE_CROSS_COMPILING. In older CMake versions
it seems you could set this manually but now the advice is to set
CMAKE_SYSTEM_NAME and CMAKE_SYSTEM_PROCESSOR then let CMake figure
it out.
There is also CMAKE_SYSTEM_VERSION which the docs say you have to
set too, but I can only find examples of Windows and Android builds
using this. It might be needed to "cross" compile from one version
of AArch64 Linux to another, but I can't confirm that.
* Removes the tablegen tools paths in favour of DLLVM_NATIVE_TOOL_DIR.
This one setting deals with all build tools in llvm that must be host
versions.
* Updates the explanations of the common options and orders them
in some rough order of relevance with the "might be needed" later.
Reviewed By: JDevlieghere, bulbazord
Differential Revision: https://reviews.llvm.org/D158085
