This revert #181334 and its follow-up PRs (including #181488, #181492,
#181493, #181494 and #181498) as well as Ismail's documentation changes
(#181594, #181717). The original commit causes a test failure in CI
(https://github.com/llvm/llvm-project/issues/181938) but the more I look
at the patch, the more I'm convinced it was not ready to land. It will
be easier to iterate on the feedback by re-landing this than by using
post-commit review.
This patch addresses some post-merge comments from llvm-project#181594,
where the tutorial name for Scripted Symbol Locator was missing a word
and wasn't capitalized properly.
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch adds documentation for the Scripted Symbol Locator plugin
system, including tutorial (renamed to hunting-down-symbols.md to match
other tutorial naming conventions) and cleans up API reference for the
website.
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
## Summary
Based on discussion from
[RFC](https://discourse.llvm.org/t/rfc-python-callback-for-source-file-resolution/83545),
this PR adds a new `SymbolLocatorScripted` plugin that allows Python
scripts to implement custom symbol and source file resolution logic.
This enables downstream users to build custom symbol servers, source
file remapping, and build artifact resolution entirely in Python.
### Changes
- Adds `LocateSourceFile()` to the SymbolLocator plugin interface,
called during source path resolution with a fully loaded `ModuleSP`, so
the plugin has access to the module's UUID, file paths, and symbols.
- Adds `SymbolLocatorScripted` plugin that delegates all four
SymbolLocator methods (`LocateExecutableObjectFile`,
`LocateExecutableSymbolFile`, `DownloadObjectAndSymbolFile`,
`LocateSourceFile`) to a user-provided Python class.
- Adds `ScriptedSymbolLocatorPythonInterface` to bridge C++ calls to
Python, with proper GIL management and error handling.
- Results for `LocateSourceFile` are cached per (module UUID, source
file) pair.
- The Python class is configured via: `settings set
plugin.symbol-locator.scripted.script-class module.ClassName`
### Python class interface
```python
class MyLocator:
def __init__(self, exe_ctx, args): ...
def locate_source_file(self, module, original_source_file):
...
def locate_executable_object_file(self, module_spec): ...
def locate_executable_symbol_file(self, module_spec,
default_search_paths): ...
def download_object_and_symbol_file(self, module_spec,
force_lookup, copy_executable): ...
```
### Test plan
```
Added TestScriptedSymbolLocator.py with 3 test cases:
- test_locate_source_file — verifies the locator resolves source
files, receives a valid SBModule with UUID, and remaps paths correctly
- test_locate_source_file_none_fallthrough — verifies returning
None falls through to default LLDB resolution, and that having no script
class set works normally
- test_invalid_script_class — verifies graceful handling of
invalid class names without crashing
```
Co-authored-by: Rahul Reddy Chamala <rachamal@fb.com>
All these are using H1 for the main heading but H3 for the
rest, Sphinx warns about this:
WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]
This tries to parse the block as that language but in these
cases fails because they aren't purely that language. This
falls back to a permissive mode which is fine, but highlights
the invalid tokens like errors which isn't great.
Instead don't try to highlight these blocks. This fixes 4
warnings seen in the docs build:
lldb/docs/use/tutorials/custom-frame-recognizers.md:43: WARNING: Lexing literal_block <...> as "c++" resulted in an error at token: '#'. Retrying in relaxed mode.
lldb/docs/use/tutorials/script-driven-debugging.md:175: WARNING: Lexing literal_block <...> as "c++" resulted in an error at token: '#'. Retrying in relaxed mode.
lldb/docs/use/tutorials/script-driven-debugging.md:426: WARNING: Lexing literal_block <...> as "c++" resulted in an error at token: '#'. Retrying in relaxed mode.
lldb/docs/use/tutorials/writing-custom-commands.md:416: WARNING: Lexing literal_block <...> as "python3" resulted in an error at token: '$'. Retrying in relaxed mode.
Logs just helped someone on Discord debug an issue in a way that would
not have been possible just by stepping the Python script. It was that
LLDB could not find the lldb-server binary.
We do talk about logs elsewhere but I think it's fine to repeat
here since it's a lot of people's first experience with scripting.
This patch adds the notion of "Facade" locations which can be reported
from a ScriptedResolver instead of the actual underlying breakpoint
location for the breakpoint. Also add a "was_hit" method to the scripted
resolver that allows the breakpoint to say which of these "Facade"
locations was hit, and "get_location_description" to provide a
description for the facade locations.
I apologize in advance for the size of the patch. Almost all of what's
here was necessary to (a) make the feature testable and (b) not break
any of the current behavior.
The motivation for this feature is given in the "Providing Facade
Locations" section that I added to the python-reference.rst so I won't
repeat it here.
rdar://152112327
This pages improve the LLDB website documentation readability and
discoverability by breaking down the very long python-reference page
into multiple subpages each explaining a specific topic.
The long term goal is to have tutorials for every scripting extension.
This also converts the pages to markdown, since it's easier to write.
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
