feat: add build-ID based debug file lookup

On Ubuntu/Debian, debug packages (e.g. libc6-dbg) install debug files
at /usr/lib/debug/.build-id/XX/YYYYYY.debug — not at the paths checked
by .gnu_debuglink. The binary has a .note.gnu.build-id section but the
debuglink search paths are empty, so the previous implementation could
never find the debug file.

Now tries build-ID lookup first, then falls back to .gnu_debuglink.
The search root is parameterized internally so both mechanisms are
independently testable with a tempdir.

Author: not-matthias

crates/instrument-hooks-bindings/instrument-hooks

@@ -191,23 +191,63 @@ pub fn compute_base_avma(base_svma: u64, load_bias: u64) -> u64 {
     base_svma.wrapping_add(load_bias)
 }
 
-/// Search for a separate debug info file using `.gnu_debuglink`.
-///
-/// Follows the standard GDB search order:
-/// 1. `<binary_dir>/<debuglink>`
-/// 2. `<binary_dir>/.debug/<debuglink>`
-/// 3. `/usr/lib/debug/<binary_dir>/<debuglink>`
+const DEFAULT_DEBUG_DIR: &str = "/usr/lib/debug";
+
+/// Search for a separate debug info file.
 ///
-/// Validates the CRC32 checksum to avoid using stale debug files.
+/// Tries two mechanisms in order:
+/// 1. **Build-ID path**: `<debug_dir>/.build-id/<XX>/<YYYYYY...>.debug`
+/// 2. **`.gnu_debuglink`** with GDB search order and CRC32 validation
 pub fn find_debug_file(object: &object::File, binary_path: &Path) -> Option<PathBuf> {
+    find_debug_file_in(object, binary_path, Path::new(DEFAULT_DEBUG_DIR))
+}
+
+fn find_debug_file_in(
+    object: &object::File,
+    binary_path: &Path,
+    debug_dir: &Path,
+) -> Option<PathBuf> {
+    if let Some(path) = find_debug_file_by_build_id(object, debug_dir) {
+        return Some(path);
+    }
+    find_debug_file_by_debuglink(object, binary_path, debug_dir)
+}
+
+fn find_debug_file_by_build_id(object: &object::File, debug_dir: &Path) -> Option<PathBuf> {
+    let build_id = object.build_id().ok()??;
+    if build_id.len() < 2 {
+        return None;
+    }
+
+    let hex = build_id
+        .iter()
+        .map(|b| format!("{b:02x}"))
+        .collect::<String>();
+    let path = debug_dir
+        .join(".build-id")
+        .join(&hex[..2])
+        .join(format!("{}.debug", &hex[2..]));
+
+    if path.exists() {
+        return Some(path);
+    }
+
+    None
+}
+
+fn find_debug_file_by_debuglink(
+    object: &object::File,
+    binary_path: &Path,
+    debug_dir: &Path,
+) -> Option<PathBuf> {
     let (debuglink, expected_crc) = object.gnu_debuglink().ok()??;
     let debuglink = std::str::from_utf8(debuglink).ok()?;
     let dir = binary_path.parent()?;
 
     let candidates = [
         dir.join(debuglink),
         dir.join(".debug").join(debuglink),
-        Path::new("/usr/lib/debug")
+        debug_dir
             .join(dir.strip_prefix("/").unwrap_or(dir))
             .join(debuglink),
     ];
@@ -227,3 +267,46 @@ pub fn find_debug_file(object: &object::File, binary_path: &Path) -> Option<Path
         true
     })
 }
+
+#[cfg(all(test, target_os = "linux"))]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_find_debug_file_by_build_id() {
+        // go_fib.bin has a build-id. Set up the build-id directory structure
+        // in a tempdir and verify find_debug_file_in resolves it.
+        let binary_path = Path::new("testdata/perf_map/go_fib.bin");
+        let content = std::fs::read(binary_path).unwrap();
+        let object = object::File::parse(&*content).unwrap();
+
+        let build_id = object.build_id().unwrap().unwrap();
+        let hex: String = build_id.iter().map(|b| format!("{b:02x}")).collect();
+
+        let tmp = tempfile::tempdir().unwrap();
+        let debug_file_dir = tmp.path().join(".build-id").join(&hex[..2]);
+        std::fs::create_dir_all(&debug_file_dir).unwrap();
+
+        let debug_file_path = debug_file_dir.join(format!("{}.debug", &hex[2..]));
+        // Copy the original binary as the "debug file" (it has DWARF)
+        std::fs::copy(binary_path, &debug_file_path).unwrap();
+
+        let result = find_debug_file_in(&object, binary_path, tmp.path());
+        assert_eq!(result, Some(debug_file_path));
+    }
+
+    #[test]
+    fn test_find_debug_file_by_debuglink() {
+        // cpp_my_benchmark_stripped.bin has a .gnu_debuglink pointing to
+        // cpp_my_benchmark.debug in the same directory.
+        let binary_path = Path::new("testdata/perf_map/cpp_my_benchmark_stripped.bin");
+        let content = std::fs::read(binary_path).unwrap();
+        let object = object::File::parse(&*content).unwrap();
+
+        let result = find_debug_file_in(&object, binary_path, Path::new("/nonexistent"));
+        assert_eq!(
+            result,
+            Some(PathBuf::from("testdata/perf_map/cpp_my_benchmark.debug"))
+        );
+    }
+}