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.
If your arguments or option values are of a type that naturally uses one
of our common completion mechanisms, you will get completion for free.
But if you have your own custom values or if you want to do fancy things
like have `break set -s foo.dylib -n ba<TAB>` only complete on symbols
in foo.dylib, you can use this new mechanism to achieve that.
This got deleted in e078c9507c, 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
The API is present, and we even have a test for it, but it isn't
documented so no one probably knows you can set requirements for your
scripted commands. This just adds docs and uses it appropriately in the
`framestats` example command.
Avoid creating an uncacheable conf variable by using a string instead of
a function reference. Also has the effect of avoiding triggering the
"config.cache" sphinx warning.
Requires myst_parser 0.19.0 (specifically
https://github.com/executablebooks/MyST-Parser/pull/696) which is over a
year old by now. Do we mandate any minimum version for these
dependencies?
This patch is a follow-up to #97263 that fix ambigous abbreviated
command resolution.
When multiple commands are resolved, instead of failing to pick a
command to
run, this patch changes to resolution logic to check if there is a
single
alias match and if so, it will run the alias instead of the other
matches.
This has as a side-effect that we don't need to make aliases for every
substring of aliases to support abbrivated alias resolution.
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
That aren't the generated `python_api/` pages.
This button is a pencil icon at the top right of the page and takes you
to a GitHub page where you can edit the content, assuming you have a
fork already. If not it tells you how to make one.
This is hardcoded to the llvm-project URL and main branch. So folks will
need a downstream patch if they want to change that.
For the upstream repo, main is right because even if a release branch
was open for PRs, it would only be for cherry picks from main.
The icon isn't as obvious as the "edit on GitHub" icons seen elsewhere
but it's built in, and we could change it later if we wanted to.
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)
Among other things, returning an empty string as the repeat command
disables auto-repeat, which can be useful for state-changing commands.
There's one remaining refinement to this setup, which is that for parsed
script commands, it should be possible to change an option value, or add
a new option value that wasn't originally specified, then ask lldb "make
this back into a command string". That would make doing fancy things
with repeat commands easier.
That capability isn't present in the lldb_private side either, however.
So that's for a next iteration.
I haven't added this to the docs on adding commands yet. I wanted to
make sure this was an acceptable approach before I spend the time to do
that.
Following a feedback request in #97262, I took out the scripted thread
plan python base class from it and make a separate PR for it.
This patch adds the scripted thread plan base python class to the lldb
python module as well as the lldb documentation website.
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch adds the documentation for a subset of scripting extensions
such as scripted process, scripted thread, operating system threads &
scritped thread plans to the lldb website.
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This reverts commit fe82a3da36.
This broke LLDB on MacOS due to a missing symbol during linking.
The fix has been applied in c6c08eee37.
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
Update the folder titles for targets in the monorepository that have not
seen taken care of for some time. These are the folders that targets are
organized in Visual Studio and XCode
(`set_property(TARGET <target> PROPERTY FOLDER "<title>")`)
when using the respective CMake's IDE generator.
* Ensure that every target is in a folder
* Use a folder hierarchy with each LLVM subproject as a top-level folder
* Use consistent folder names between subprojects
* When using target-creating functions from AddLLVM.cmake, automatically
deduce the folder. This reduces the number of
`set_property`/`set_target_property`, but are still necessary when
`add_custom_target`, `add_executable`, `add_library`, etc. are used. A
LLVM_SUBPROJECT_TITLE definition is used for that in each subproject's
root CMakeLists.txt.
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.
Fixes#47549
`lldb-server`'s platform mode seems to have an issue with its
`--min-gdbserver-port` `--max-gdbserver-port` flags (and probably the
`--gdbserver-port` flag, but I didn't test it).
How the platform code seems to work is that it listens on a port, and
whenever there's an incoming connection, it forks the process to handle
the connection. To handle the port flags, the main process uses an
instance of the helper class
`GDBRemoteCommunicationServerPlatform::PortMap`, that can be configured
and track usages of ports. The child process handling the platform
connection, can then use the port map to allocate a port for the
gdb-server connection it will make (this is another process it spawns).
However, in the current code, this works only once. After the first
connection is handled by forking a child process, the main platform
listener code loops around, and then 'forgets' about the port map. This
is because this code:
```cpp
GDBRemoteCommunicationServerPlatform platform(
acceptor_up->GetSocketProtocol(), acceptor_up->GetSocketScheme());
if (!gdbserver_portmap.empty()) {
platform.SetPortMap(std::move(gdbserver_portmap));
}
```
is within the connection listening loop. This results in the
`gdbserver_portmap` being moved into the platform object at the
beginning of the first iteration of the loop, but on the second
iteration, after the first fork, the next instance of the platform
object will not have its platform port mapped.
The result of this bug is that subsequent connections to the platform,
when spawning the gdb-remote connection, will be supplied a random port
- which isn't bounded by the `--min-gdbserver-port` and
`--max-gdbserver--port` parameters passed in by the user.
This PR fixes this issue by having the port map be maintained by the
parent platform listener process. On connection, the listener allocates
a single available port from the port map, associates the child process
pid with the port, and lets the connection handling child use that
single port number.
Additionally, when cleaning up child processes, the main listener
process tracks the child that exited to deallocate the previously
associated port, so it can be reused for a new connection.
This was last modified in 4fd3347d6e in
2021 and was made obsolete by the RST version that
edb874b231 added in 2019.
There are some differences but at this point, I'd bet the RST is the
correct one.
* Replace "we" with either "you" (when talking to the reader) or "lldb"
(when talking about the project).
* Refer to lldb as lldb not LLDB, to match what the user sees on
the command line (I am going to come back later and put the proper name in places where it's talking about the projects themselves)
* Remove a bunch of contractions for example "won't". Which don't (pun
intended) seem like a big deal at first but even I as a native English
speaker find the text clearer with them expanded.
* Use RST's plain text highlighting for keywords and command names.
* Split some very long lines for easier editing in future.
Adds support for applying LLVM formatting to variables.
The reason for this is to support cases such as the following.
Let's say you have two separate bytes that you want to print as a
combined hex value. Consider the following summary string:
```
${var.byte1%x}${var.byte2%x}
```
The output of this will be: `0x120x34`. That is, a `0x` prefix is
unconditionally applied to each byte. This is unlike printf formatting
where you must include the `0x` yourself.
Currently, there's no way to do this with summary strings, instead
you'll need a summary provider in python or c++.
This change introduces formatting support using LLVM's formatter system.
This allows users to achieve the desired custom formatting using:
```
${var.byte1:x-}${var.byte2:x-}
```
Here, each variable is suffixed with `:x-`. This is passed to the LLVM
formatter as `{0:x-}`. For integer values, `x` declares the output as
hex, and `-` declares that no `0x` prefix is to be used. Further, one
could write:
```
${var.byte1:x-2}${var.byte2:x-2}
```
Where the added `2` results in these bytes being written with a minimum
of 2 digits.
An alternative considered was to add a new format specifier that would
print hex values without the `0x` prefix. The reason that approach was
not taken is because in addition to forcing a `0x` prefix, hex values
are also forced to use leading zeros. This approach lets the user have
full control over formatting.
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!
