[Lldb-commits] [lldb] [lldb] Add ScriptedSymbolLocator plugin for source file resolution (PR #181334)

[via lldb-commits]

================
@@ -0,0 +1,163 @@
+# Scripted Symbol Locator Tutorial
+
+The **Scripted Symbol Locator** lets you write a Python class that tells LLDB
+where to find executables, symbol files, and source files for your debug
+targets. This is useful when your build artifacts live in a custom location,
+such as a symbol server or a local build-ID-indexed cache.
+
+## Quick Start
+
+1. **Write a locator class.** Create a Python file (e.g., `my_locator.py`)
+   with a class that implements the methods you need:
+
+   ```python
+   import os
+   import lldb
+
+   class MyLocator:
+       def __init__(self, exe_ctx, args):
+           self.cache_dir = None
+           if args.IsValid():
+               d = args.GetValueForKey("cache_dir")
+               if d and d.IsValid():
+                   self.cache_dir = d.GetStringValue(4096)
+
+       def locate_source_file(self, module, original_source_file):
+           """Return the resolved path, or None to fall through."""
+           if not self.cache_dir:
+               return None
+           uuid = module.GetUUIDString()
+           basename = os.path.basename(original_source_file)
+           candidate = os.path.join(self.cache_dir, uuid, "src", basename)
+           if os.path.exists(candidate):
+               return candidate
+           return None
+   ```
+
+2. **Import the script and register the locator on a target:**
+
+   ```
+   (lldb) command script import /path/to/my_locator.py
+   (lldb) target symbols scripted register \
+              -C my_locator.MyLocator \
+              -k cache_dir -v /path/to/cache
+   ```
+
+3. **Debug normally.** When LLDB resolves source files for that target,
+   your `locate_source_file` method will be called automatically.
+
+## Available Methods
+
+Your locator class can implement any combination of these methods. All are
+optional except `__init__` and `locate_source_file` (which is the abstract
+method that must be present).
+
+| Method | Called When |
+|--------|------------|
+| `locate_source_file(module, path)` | LLDB resolves a source file path in debug info |
+| `locate_executable_object_file(module_spec)` | LLDB needs the binary for a module |
+| `locate_executable_symbol_file(module_spec, search_paths)` | LLDB needs separate debug symbols |
+| `download_object_and_symbol_file(module_spec, force, copy)` | Last-resort download from a remote source |
+
+### Method Signatures
+
+```python
+def __init__(self, exe_ctx: lldb.SBExecutionContext,
+             args: lldb.SBStructuredData) -> None:
+    ...
+
+def locate_source_file(self, module: lldb.SBModule,
+                       original_source_file: str) -> Optional[str]:
----------------
rchamala wrote:

Oops, forgot to update the documentation. Thanks for pointing

https://github.com/llvm/llvm-project/pull/181334