Skip to content

fix: support GDB separate debug file layouts #268

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
swananan merged 1 commit into from
Aug 2, 2026
Merged

fix: support GDB separate debug file layouts #268

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

24 changes: 8 additions & 16 deletions config-zh.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,23 +57,18 @@ timestamp = "local"
color = "auto"

[dwarf]
# DWARF 调试信息搜索路径（用于 .gnu_debuglink 文件）
# 本地独立 DWARF 调试信息的全局搜索目录
#
# 当二进制文件使用 .gnu_debuglink 引用独立的调试文件时，
# GhostScope 会在这些路径中搜索调试文件。
# GhostScope 使用这些目录搜索 Build-ID 和 .gnu_debuglink 调试文件。
# 命令行 --debug-file/-d 会直接指定一个调试文件，并绕过该搜索列表用于
# 选中的目标模块。
#
# 这些路径只影响自动 .gnu_debuglink 发现。命令行 --debug-file/-d
# 会直接指定一个调试文件，并绕过该搜索列表用于选中的目标模块。
#
# 搜索顺序（优先级从高到低）：
# 1. 绝对路径（如果 .gnu_debuglink 包含绝对路径 - 罕见）
# 2. 用户配置的 search_paths + basename（此处配置）
# 3. 二进制文件所在目录 + basename
# 4. 二进制文件所在目录的 .debug 子目录 + basename
#
# 对于每个用户配置的路径，会检查两种位置：
# 支持的位置包括：
# - <路径>/.build-id/xx/yyyy.debug
# - <路径>/<二进制绝对目录>/<debug_文件名>
# - <路径>/debug_文件名
# - <路径>/.debug/debug_文件名
# - 二进制文件所在目录及其 .debug 子目录
#
# 特性：
# - 主目录展开："~/" 会被替换为你的主目录
Expand All @@ -86,9 +81,6 @@ color = "auto"
# - 用户特定： "~/.local/lib/debug"
# - 自定义构建输出："/path/to/build/debug"
#
# 注意：.gnu_debuglink 通常使用 basename（相对路径），但也支持绝对路径。
# 如需使用系统范围的调试目录（如 /usr/lib/debug），请添加到 search_paths。
#
# 默认值：["/usr/lib/debug", "/usr/local/lib/debug"]
search_paths = [
"/usr/lib/debug",
Expand Down
26 changes: 8 additions & 18 deletions config.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,24 +61,18 @@ timestamp = "local"
color = "auto"

[dwarf]
# DWARF debug information search paths for .gnu_debuglink files
# Global directories for local separate DWARF debug information
#
# When a binary uses .gnu_debuglink to reference separate debug files,
# GhostScope searches these paths to locate the debug file.
# GhostScope uses these roots for Build-ID and .gnu_debuglink discovery.
# The --debug-file/-d CLI option points directly at one debug file and
# bypasses this search list for the selected target module.
#
# These paths only affect automatic .gnu_debuglink discovery. The
# --debug-file/-d CLI option points directly at one debug file and bypasses
# this search list for the selected target module.
#
# Search order (highest priority first):
# 1. Absolute path (if .gnu_debuglink contains an absolute path - rare)
# 2. User-configured search_paths + basename (configured here)
# 3. Same directory as the binary + basename
# 4. .debug subdirectory next to the binary + basename
#
# For each user-configured path, both direct and .debug subdirectory are checked:
# Supported locations include:
# - <path>/.build-id/xx/yyyy.debug
# - <path>/<absolute-binary-directory>/<debug_filename>
# - <path>/debug_filename
# - <path>/.debug/debug_filename
# - the binary directory and its .debug subdirectory
#
# Features:
# - Home directory expansion: "~/" is replaced with your home directory
Expand All @@ -91,10 +85,6 @@ color = "auto"
# - User-specific: "~/.local/lib/debug"
# - Custom build output: "/path/to/build/debug"
#
# Note: .gnu_debuglink typically uses basename (relative path), but absolute paths
# are also supported. If you need system-wide debug directories like /usr/lib/debug,
# add them to search_paths.
#
# Default: ["/usr/lib/debug", "/usr/local/lib/debug"]
search_paths = [
"/usr/lib/debug",
Expand Down
39 changes: 21 additions & 18 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,19 +109,19 @@ ghostscope -p 1234 --debug-file /path/to/binary.debug

# Auto-detection searches in order:
# 1. Binary itself (.debug_info sections)
# 2. .gnu_debuglink section (see search paths below)
# 2. Local separate debug files by Build-ID or .gnu_debuglink
# 3. debuginfod by Build-ID, when [dwarf.debuginfod] is enabled
#
# Local Build-ID directory layouts are not searched directly. .gnu_debugdata
# is not loaded currently. Use .gnu_debuglink search_paths or debuginfod for
# separate debug information. The default search_paths include /usr/lib/debug
# and /usr/local/lib/debug.
# .gnu_debugdata is not loaded currently. The default search_paths include
# /usr/lib/debug and /usr/local/lib/debug.

# .gnu_debuglink search paths (configurable in config.toml):
# Local separate-debug search paths (configurable in config.toml):
# 1. Absolute path (if .gnu_debuglink contains absolute path - rare)
# 2. User-configured search_paths + basename (highest priority)
# 3. Same directory as the binary + basename
# 4. .debug subdirectory next to the binary + basename
# 2. <search_path>/.build-id/xx/yyyy.debug, when a Build-ID is available
# 3. User-configured search_paths + basename (GhostScope compatibility path)
# 4. Same directory as the binary + basename
# 5. .debug subdirectory next to the binary + basename
# 6. <search_path>/<absolute_binary_directory>/<basename>
#
# Note: If you override search_paths in config.toml, keep any system-wide debug
# directories that you still rely on.
Expand Down Expand Up @@ -334,23 +334,26 @@ timestamp = "local"
color = "auto"

[dwarf]
# Debug information search paths for .gnu_debuglink files
# When a binary uses .gnu_debuglink to reference separate debug files,
# GhostScope searches these paths to locate the debug file.
# Global directories for local separate debug information.
# GhostScope uses these roots for Build-ID and .gnu_debuglink discovery.
#
# These paths only affect automatic .gnu_debuglink discovery. The
# --debug-file/-d CLI option points directly at one debug file and bypasses
# The --debug-file/-d CLI option points directly at one debug file and bypasses
# this search list for the selected target module.
#
# Search order (highest priority first):
# 1. Absolute path (if .gnu_debuglink contains an absolute path - rare)
# 2. User-configured search_paths + basename (configured here)
# 3. Same directory as the binary + basename
# 4. .debug subdirectory next to the binary + basename
# 2. <search_path>/.build-id/xx/yyyy.debug, when a Build-ID is available
# 3. User-configured search_paths + basename (GhostScope compatibility path)
# 4. Same directory as the binary + basename
# 5. .debug subdirectory next to the binary + basename
# 6. <search_path>/<absolute_binary_directory>/<basename>
#
# For each user-configured path, both direct and .debug subdirectory are checked:
# For each user-configured path, GhostScope also checks the existing flat paths:
# - <path>/debug_filename
# - <path>/.debug/debug_filename
# Standard GDB directory layouts are checked as well:
# - <path>/.build-id/xx/yyyy.debug
# - <path>/<absolute_binary_directory>/debug_filename
#
# Features:
# - Home directory expansion: "~/" is replaced with your home directory
Expand Down
39 changes: 22 additions & 17 deletions docs/zh/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,18 +110,19 @@ ghostscope -p 1234 --debug-file /path/to/binary.debug

# 自动检测按以下顺序搜索：
# 1. 二进制文件本身（.debug_info 节）
# 2. .gnu_debuglink 节（参见下方搜索路径）
# 2. 通过 Build-ID 或 .gnu_debuglink 搜索本地独立调试文件
# 3. 启用 [dwarf.debuginfod] 时，通过 Build-ID 使用 debuginfod
#
# GhostScope 不会直接搜索本地 Build-ID 目录布局；当前也不会加载
# .gnu_debugdata。如需使用独立调试信息，请使用 .gnu_debuglink search_paths
# 或 debuginfod。默认 search_paths 包含 /usr/lib/debug 和 /usr/local/lib/debug。
# GhostScope 当前不会加载 .gnu_debugdata。默认 search_paths 包含
# /usr/lib/debug 和 /usr/local/lib/debug。

# .gnu_debuglink 搜索路径（可在 config.toml 中配置）：
# 本地独立调试文件搜索路径（可在 config.toml 中配置）：
# 1. 绝对路径（如果 .gnu_debuglink 包含绝对路径 - 罕见）
# 2. 用户配置的 search_paths + basename（最高优先级）
# 3. 二进制文件同目录 + basename
# 4. 二进制文件同目录的 .debug 子目录 + basename
# 2. 有 Build-ID 时，<search_path>/.build-id/xx/yyyy.debug
# 3. 用户配置的 search_paths + basename（GhostScope 兼容路径）
# 4. 二进制文件同目录 + basename
# 5. 二进制文件同目录的 .debug 子目录 + basename
# 6. <search_path>/<二进制绝对目录>/<basename>
#
# 注意：如果在 config.toml 中覆盖 search_paths，请保留仍然依赖的系统调试目录。
```
Expand Down Expand Up @@ -332,22 +333,26 @@ timestamp = "local"
color = "auto"

[dwarf]
# DWARF 调试信息搜索路径（用于 .gnu_debuglink 文件）
# 当二进制文件使用 .gnu_debuglink 引用独立的调试文件时，
# GhostScope 会在这些路径中搜索调试文件。
# 本地独立 DWARF 调试信息的全局搜索目录。
# GhostScope 使用这些目录进行 Build-ID 和 .gnu_debuglink 查找。
#
# 这些路径只影响自动 .gnu_debuglink 发现。命令行 --debug-file/-d
# 会直接指定一个调试文件，并绕过该搜索列表用于选中的目标模块。
# 命令行 --debug-file/-d 会直接指定一个调试文件，并绕过该搜索列表用于
# 选中的目标模块。
#
# 搜索顺序（优先级从高到低）：
# 1. 绝对路径（如果 .gnu_debuglink 包含绝对路径 - 罕见）
# 2. 用户配置的 search_paths + basename（此处配置）
# 3. 二进制文件所在目录 + basename
# 4. 二进制文件所在目录的 .debug 子目录 + basename
# 2. 有 Build-ID 时，<search_path>/.build-id/xx/yyyy.debug
# 3. 用户配置的 search_paths + basename（GhostScope 兼容路径）
# 4. 二进制文件所在目录 + basename
# 5. 二进制文件所在目录的 .debug 子目录 + basename
# 6. <search_path>/<二进制绝对目录>/<basename>
#
# 对于每个用户配置的路径，会检查两种位置：
# 对于每个用户配置的路径，仍会检查原有的两种平铺位置：
# - <路径>/debug_文件名
# - <路径>/.debug/debug_文件名
# 同时也会检查标准 GDB 目录布局：
# - <路径>/.build-id/xx/yyyy.debug
# - <路径>/<二进制绝对目录>/debug_文件名
#
# 特性：
# - 主目录展开："~/" 会被替换为你的主目录
Expand Down
Loading
Loading