1ee03d1e09
## 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>
121 lines
4.1 KiB
C++
121 lines
4.1 KiB
C++
//===----------------------------------------------------------------------===//
|
|
//
|
|
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
|
|
// See https://llvm.org/LICENSE.txt for license information.
|
|
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
#include "lldb/Core/PluginManager.h"
|
|
#include "lldb/Host/Config.h"
|
|
#include "lldb/Target/ExecutionContext.h"
|
|
#include "lldb/Utility/Log.h"
|
|
#include "lldb/lldb-enumerations.h"
|
|
|
|
#if LLDB_ENABLE_PYTHON
|
|
|
|
// clang-format off
|
|
// LLDB Python header must be included first
|
|
#include "../lldb-python.h"
|
|
// clang-format on
|
|
|
|
#include "../SWIGPythonBridge.h"
|
|
#include "../ScriptInterpreterPythonImpl.h"
|
|
#include "ScriptedSymbolLocatorPythonInterface.h"
|
|
|
|
using namespace lldb;
|
|
using namespace lldb_private;
|
|
using namespace lldb_private::python;
|
|
|
|
ScriptedSymbolLocatorPythonInterface::ScriptedSymbolLocatorPythonInterface(
|
|
ScriptInterpreterPythonImpl &interpreter)
|
|
: ScriptedSymbolLocatorInterface(), ScriptedPythonInterface(interpreter) {}
|
|
|
|
llvm::Expected<StructuredData::GenericSP>
|
|
ScriptedSymbolLocatorPythonInterface::CreatePluginObject(
|
|
const llvm::StringRef class_name, ExecutionContext &exe_ctx,
|
|
StructuredData::DictionarySP args_sp, StructuredData::Generic *script_obj) {
|
|
ExecutionContextRefSP exe_ctx_ref_sp =
|
|
std::make_shared<ExecutionContextRef>(exe_ctx);
|
|
StructuredDataImpl sd_impl(args_sp);
|
|
return ScriptedPythonInterface::CreatePluginObject(class_name, script_obj,
|
|
exe_ctx_ref_sp, sd_impl);
|
|
}
|
|
|
|
std::optional<ModuleSpec>
|
|
ScriptedSymbolLocatorPythonInterface::LocateExecutableObjectFile(
|
|
const ModuleSpec &module_spec, Status &error) {
|
|
// Make a copy so Dispatch's ReverseTransform can operate on a mutable value.
|
|
ModuleSpec ms_copy(module_spec);
|
|
FileSpec file_spec =
|
|
Dispatch<FileSpec>("locate_executable_object_file", error, ms_copy);
|
|
|
|
if (error.Fail() || !file_spec)
|
|
return {};
|
|
|
|
ModuleSpec result_spec(module_spec);
|
|
result_spec.GetFileSpec() = file_spec;
|
|
return result_spec;
|
|
}
|
|
|
|
std::optional<FileSpec>
|
|
ScriptedSymbolLocatorPythonInterface::LocateExecutableSymbolFile(
|
|
const ModuleSpec &module_spec, const FileSpecList &default_search_paths,
|
|
Status &error) {
|
|
ModuleSpec ms_copy(module_spec);
|
|
FileSpecList fsl_copy(default_search_paths);
|
|
FileSpec file_spec = Dispatch<FileSpec>("locate_executable_symbol_file",
|
|
error, ms_copy, fsl_copy);
|
|
|
|
if (error.Fail() || !file_spec)
|
|
return {};
|
|
|
|
return file_spec;
|
|
}
|
|
|
|
bool ScriptedSymbolLocatorPythonInterface::DownloadObjectAndSymbolFile(
|
|
ModuleSpec &module_spec, Status &error, bool force_lookup,
|
|
bool copy_executable) {
|
|
StructuredData::ObjectSP obj =
|
|
Dispatch("download_object_and_symbol_file", error, module_spec,
|
|
force_lookup, copy_executable);
|
|
|
|
if (!obj || error.Fail())
|
|
return false;
|
|
|
|
return obj->GetBooleanValue();
|
|
}
|
|
|
|
std::optional<FileSpec> ScriptedSymbolLocatorPythonInterface::LocateSourceFile(
|
|
const lldb::ModuleSP &module_sp, const FileSpec &original_source_file,
|
|
Status &error) {
|
|
std::string source_path = original_source_file.GetPath();
|
|
lldb::ModuleSP module_copy(module_sp);
|
|
|
|
FileSpec file_spec =
|
|
Dispatch<FileSpec>("locate_source_file", error, module_copy, source_path);
|
|
|
|
if (error.Fail() || !file_spec)
|
|
return {};
|
|
|
|
return file_spec;
|
|
}
|
|
|
|
void ScriptedSymbolLocatorPythonInterface::Initialize() {
|
|
const std::vector<llvm::StringRef> ci_usages = {
|
|
"target symbols scripted register -C "
|
|
"<script-class> [-k <key> -v <value> ...]"};
|
|
const std::vector<llvm::StringRef> api_usages = {
|
|
"SBTarget.RegisterScriptedSymbolLocator(class_name, args_dict)"};
|
|
PluginManager::RegisterPlugin(
|
|
GetPluginNameStatic(),
|
|
llvm::StringRef("Scripted symbol locator Python interface"),
|
|
CreateInstance, eScriptLanguagePython, {ci_usages, api_usages});
|
|
}
|
|
|
|
void ScriptedSymbolLocatorPythonInterface::Terminate() {
|
|
PluginManager::UnregisterPlugin(CreateInstance);
|
|
}
|
|
|
|
#endif // LLDB_ENABLE_PYTHON
|