This PR adds a proof-of-concept for a bytecode designed to ship and
run LLDB data formatters. More motivation and context can be found in
the formatter-bytecode.rst file and on discourse.
https://discourse.llvm.org/t/a-bytecode-for-lldb-data-formatters/82696
Relanding with a fix for a case-sensitive path.
This PR adds a proof-of-concept for a bytecode designed to ship and
run LLDB data formatters. More motivation and context can be found in
the formatter-bytecode.rst file and on discourse.
https://discourse.llvm.org/t/a-bytecode-for-lldb-data-formatters/82696
Relanding with a fix for a case-sensitive path.
See
https://discourse.llvm.org/t/rfc-lets-document-and-enforce-a-minimum-python-version-for-lldb/82731
for discussions.
This matches LLVM's requirement to run tests. For LLDB 20 there will be
a CMake warning telling builders that from LLDB 21 this will be a hard
requirement. From LLDB 21, it will be an error to try to build with
anything <= 3.8.
So there are no code changes in this commit. Once the llvm 20 branch is
created we can remove some < 3.8 support code.
As always, if you disable Python support you will not get any new
warnings or errors from this change.
Lua 5.3 and Lua 5.4 are similar enough that we can easily support both
in LLDB. This patch adds support for building LLDB with both and updates
the documentation accordingly.
Currently all the headings marked as `#` show up
as a top-level entry in the `Developing LLDB`
toctree. This patch marks these as `##` so only
`Adding Programming Language Support` is displayed
in the table of contents.
I've had multiple request for documentation about the JSON symbol file
format that LLDB supports. This patch documents the structure and
fields, shows a handful of examples and explains how to use it in LLDB.
1. This commit adds LLDB_TEST_PLATFORM_URL, LLDB_TEST_SYSROOT,
LLDB_TEST_PLATFORM_WORKING_DIR, LLDB_SHELL_TESTS_DISABLE_REMOTE cmake
flags to pass arguments for cross-compilation and remote running of both Shell&API tests.
2. To run Shell tests remotely, it adds 'platform select' and 'platform connect' commands to %lldb
substitution.
3. 'remote-linux' feature added to lit to disable tests failing with
remote execution.
4. A separate working directory is assigned to each test to avoid
conflicts during parallel test execution.
5. Remote Shell testing is run only when LLDB_TEST_SYSROOT is set for
building test sources. The recommended compiler for that is Clang.
---------
Co-authored-by: Vladimir Vereschaka <vvereschaka@accesssoftek.com>
This commit extends the developer docs for `lldb-dap`. It also adds a
short "Contributing" section to the user-facing README.
Last but not least, it updates the `repository` in the package.json to
point to the actual source of truth for the source code, instead of
pointing to its mirrored repository. I hope that the VS Code Marketplace
properly supports the `directory` property. Unfortunately, I have no way
to test this before merging this Pull Request.
Listen to gdbserver-port, accept the connection and run `lldb-server gdbserver --fd` on all platforms.
Parameters --min-gdbserver-port and --max-gdbserver-port are deprecated now.
This is the part 2 of #101283.
Fixes#97537.
This got deleted in e078c9507c3abb4d9bb2265c366b26557880a3e3, I presume
accidentally, because it didn't have a corresponding rst file for it.
So I've brought it back and converted it into Markdown. The content
remains accurate, from what I know at least.
It's a bit "now draw the rest of the owl" but if nothing else, it gives
you a bunch of important classes to go and research as a starting point.
You can see the original content here:
5d71fc5d7b/lldb/www/adding-language-support.html
When an inferior stub cannot allocate memory for lldb, and lldb needs to
store the result of expressions, it will do it in lldb's own memory
range ("host memory"). But it needs to find a virtual address range that
is not used in the inferior process. It tries to use the
qMemoryRegionInfo gdb remote serial protocol packet to find a range that
is inaccessible, starting at address 0 and moving up the size of each
region.
If the first region found at address 0 is inaccessible, lldb will use
the address range starting at 0 to mean "read lldb's host memory, not
the process memory", and programs that crash with a null dereference
will have poor behavior.
This patch skips consideration of a memory region that starts at address
0.
I also clarified the documentation of qMemoryRegionInfo to make it clear
that the stub is required to provide permissions for a memory range that
is accessable, it is not an optional key in this response. This issue
was originally found by a stub that did not list permissions in its
response, and lldb treated the first region returned as the one it would
use. (the stub also didn't support the memory-allocate packet)
This reverts commit fe82a3da36196157c0caa1ef2505186782f750d1.
This broke LLDB on MacOS due to a missing symbol during linking.
The fix has been applied in c6c08eee37bada190bd1aa4593c88a5e2c8cdaac.
Original commit message:
The terminfo dependency introduces a significant nonhermeticity into the
build. It doesn't respect `--no-undefined-version` meaning that it's not
a dependency that can be built with Clang 17+. This forces maintainers
of source-based distributions to implement patches or ignore linker
errors.
Remove it to reduce the closure size and improve portability of
LLVM-based tools. Users can still use command line arguments to toggle
color support expliticly.
Fixes#75490Closes#53294#23355
The terminfo dependency introduces a significant nonhermeticity into the
build. It doesn't respect `--no-undefined-version` meaning that it's not
a dependency that can be built with Clang 17+. This forces maintainers
of source-based distributions to implement patches or ignore linker
errors.
Remove it to reduce the closure size and improve portability of
LLVM-based tools. Users can still use command line arguments to toggle
color support expliticly.
Fixes#75490Closes#53294#23355
The README.md is what users see when they look for the extension in the
Marketplace [1]. Right now, it's a mix of developer documentation (for
us) and user documentation. This commit moves the developer docs into
`docs` and the lldb website and refocuses the README on using the
extension.
[1] https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap
Comparing a bit of the mock GDB server code to what was in the document
I found these:
* QLaunchArch
* qSpeedTest
* qSymbol
qSymbol is the most mysterious but it did have some examples in a
comment so I've adapted that.
This removes various subtitles or converts them to bold text so that the
table of contents is less cluttered.
This includes "Example", "Notes", "Priority To Implement" and
"Response".
So we aren't describing the same packets twice. Basically turning the
platform doc into a list of cross links.
qLaunchSuccess was missing a description so I added one.
As before, script did most of the work, hand edits after that.
There's a lot more we can do dedupe this and the packets doc, this will
come in a follow up PR.
This document has never been on the website, unlike GDB's protocol docs.
It will be useful to have both available online to compare.
Markdown is easier to edit and preview in many editors (including Github
itself), so I've chosen that over RST. Plus, building the website takes
minutes and I lose the will to make nice edits when I have to deal with
that.
The standard dialiect lacks some things notably multi-line table cells,
so I've converted large tables into bullet point lists
so that we still get text wrapping. This is a downside but I think the
simplicity of Markdown outweighs this.
I have applied the plain text markers where I've noticed it and escaped
some HTML characters. There may be more changes needed but, it's
Markdown, so it's in theory a lot easier for someone to fix it!
https://discourse.llvm.org/t/running-lldb-in-a-container/76801/4 found
that the obvious way to use this variable doesn't work, despite what our
docs and examples say.
Perhaps in the past it did but now you need to use ";" as a separator to
make sure the final command line works properly.
For example "-A foo" becomes "-A foo" when python goes to run the runner
script. The script sees this as one command line element, not two. What
you actually want is "-A;foo" which we convert to "-A" "foo" which the
script sees as one option and one value for that option.
The "Script:" printout from dotest is misleading here because it does `"
".join(cmd)` so it looks like it's ok but in fact it's not.
I'm not changing that format though because printing the command as a
Python list is not useful outside of this specific situation.
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.
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.
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.
