llvm-project/lldb/bindings/python/python-swigsafecast.swig
rchamala 1ee03d1e09
[lldb] Add ScriptedSymbolLocator plugin for source file resolution (#181334)
## 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>
2026-02-14 07:39:00 -08:00

162 lines
6.0 KiB
Plaintext

namespace lldb_private {
namespace python {
PythonObject ToSWIGHelper(void *obj, swig_type_info *info) {
return {PyRefType::Owned, SWIG_NewPointerObj(obj, info, SWIG_POINTER_OWN)};
}
PythonObject SWIGBridge::ToSWIGWrapper(std::unique_ptr<lldb::SBValue> value_sb) {
return ToSWIGHelper(value_sb.release(), SWIGTYPE_p_lldb__SBValue);
}
PythonObject SWIGBridge::ToSWIGWrapper(std::unique_ptr<lldb::SBCommandReturnObject> result_up) {
return ToSWIGHelper(result_up.release(), SWIGTYPE_p_lldb__SBCommandReturnObject);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::ValueObjectSP value_sp) {
return ToSWIGWrapper(std::unique_ptr<lldb::SBValue>(new lldb::SBValue(value_sp)));
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::TargetSP target_sp) {
return ToSWIGHelper(new lldb::SBTarget(std::move(target_sp)),
SWIGTYPE_p_lldb__SBTarget);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::ProcessSP process_sp) {
return ToSWIGHelper(new lldb::SBProcess(std::move(process_sp)),
SWIGTYPE_p_lldb__SBProcess);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::ModuleSP module_sp) {
return ToSWIGHelper(new lldb::SBModule(std::move(module_sp)),
SWIGTYPE_p_lldb__SBModule);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::ThreadPlanSP thread_plan_sp) {
return ToSWIGHelper(new lldb::SBThreadPlan(std::move(thread_plan_sp)),
SWIGTYPE_p_lldb__SBThreadPlan);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::StackFrameListSP frames_sp) {
return ToSWIGHelper(new lldb::SBFrameList(std::move(frames_sp)),
SWIGTYPE_p_lldb__SBFrameList);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::BreakpointSP breakpoint_sp) {
return ToSWIGHelper(new lldb::SBBreakpoint(std::move(breakpoint_sp)),
SWIGTYPE_p_lldb__SBBreakpoint);
}
PythonObject SWIGBridge::ToSWIGWrapper(Status&& status) {
return ToSWIGHelper(new lldb::SBError(std::move(status)), SWIGTYPE_p_lldb__SBError);
}
PythonObject SWIGBridge::ToSWIGWrapper(std::unique_ptr<lldb::SBStructuredData> data_sb) {
return ToSWIGHelper(data_sb.release(), SWIGTYPE_p_lldb__SBStructuredData);
}
PythonObject SWIGBridge::ToSWIGWrapper(const StructuredDataImpl &data_impl) {
return ToSWIGWrapper(std::unique_ptr<lldb::SBStructuredData>(new lldb::SBStructuredData(data_impl)));
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::ThreadSP thread_sp) {
return ToSWIGHelper(new lldb::SBThread(std::move(thread_sp)),
SWIGTYPE_p_lldb__SBThread);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::StackFrameSP frame_sp) {
return ToSWIGHelper(new lldb::SBFrame(std::move(frame_sp)),
SWIGTYPE_p_lldb__SBFrame);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::DebuggerSP debugger_sp) {
return ToSWIGHelper(new lldb::SBDebugger(std::move(debugger_sp)),
SWIGTYPE_p_lldb__SBDebugger);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::WatchpointSP watchpoint_sp) {
return ToSWIGHelper(new lldb::SBWatchpoint(std::move(watchpoint_sp)),
SWIGTYPE_p_lldb__SBWatchpoint);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::BreakpointLocationSP bp_loc_sp) {
return ToSWIGHelper(new lldb::SBBreakpointLocation(std::move(bp_loc_sp)),
SWIGTYPE_p_lldb__SBBreakpointLocation);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::ExecutionContextRefSP ctx_sp) {
return ToSWIGHelper(new lldb::SBExecutionContext(std::move(ctx_sp)),
SWIGTYPE_p_lldb__SBExecutionContext);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::TypeImplSP type_impl_sp) {
return ToSWIGHelper(new lldb::SBType(type_impl_sp), SWIGTYPE_p_lldb__SBType);
}
PythonObject SWIGBridge::ToSWIGWrapper(const TypeSummaryOptions &summary_options) {
return ToSWIGHelper(new lldb::SBTypeSummaryOptions(summary_options),
SWIGTYPE_p_lldb__SBTypeSummaryOptions);
}
PythonObject SWIGBridge::ToSWIGWrapper(const SymbolContext &sym_ctx) {
return ToSWIGHelper(new lldb::SBSymbolContext(sym_ctx),
SWIGTYPE_p_lldb__SBSymbolContext);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::ProcessLaunchInfoSP launch_info_sp) {
return ToSWIGHelper(new lldb::ProcessLaunchInfoSP(std::move(launch_info_sp)),
SWIGTYPE_p_lldb__SBLaunchInfo);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::ProcessAttachInfoSP attach_info_sp) {
return ToSWIGHelper(new lldb::ProcessAttachInfoSP(std::move(attach_info_sp)),
SWIGTYPE_p_lldb__SBAttachInfo);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::DataExtractorSP data_sp) {
return ToSWIGHelper(new lldb::DataExtractorSP(std::move(data_sp)),
SWIGTYPE_p_lldb__SBData);
}
ScopedPythonObject<lldb::SBCommandReturnObject>
SWIGBridge::ToSWIGWrapper(CommandReturnObject &cmd_retobj) {
return ScopedPythonObject<lldb::SBCommandReturnObject>(
new lldb::SBCommandReturnObject(cmd_retobj),
SWIGTYPE_p_lldb__SBCommandReturnObject);
}
PythonObject SWIGBridge::ToSWIGWrapper(const Stream *s) {
return ToSWIGHelper(new lldb::SBStream(), SWIGTYPE_p_lldb__SBStream);
}
PythonObject SWIGBridge::ToSWIGWrapper(std::shared_ptr<lldb::SBStream> stream_sb) {
return ToSWIGHelper(stream_sb.get(), SWIGTYPE_p_lldb__SBStream);
}
PythonObject SWIGBridge::ToSWIGWrapper(Event *event) {
return ToSWIGHelper(new lldb::SBEvent(event), SWIGTYPE_p_lldb__SBEvent);
}
PythonObject SWIGBridge::ToSWIGWrapper(
std::unique_ptr<lldb::SBFileSpec> file_spec_sb) {
return ToSWIGHelper(file_spec_sb.release(), SWIGTYPE_p_lldb__SBFileSpec);
}
PythonObject SWIGBridge::ToSWIGWrapper(
std::unique_ptr<lldb::SBModuleSpec> module_spec_sb) {
return ToSWIGHelper(module_spec_sb.release(), SWIGTYPE_p_lldb__SBModuleSpec);
}
PythonObject SWIGBridge::ToSWIGWrapper(
std::unique_ptr<lldb::SBFileSpecList> file_spec_list_sb) {
return ToSWIGHelper(file_spec_list_sb.release(),
SWIGTYPE_p_lldb__SBFileSpecList);
}
PythonObject SWIGBridge::ToSWIGWrapper(lldb::DescriptionLevel level) {
return PythonInteger((int64_t) level);
}
} // namespace python
} // namespace lldb_private