注册调试符号

ffx debug symbol-index 命令可帮助您在开发环境中管理 Fuchsia 组件的调试符号。

概念

在开发期间,Fuchsia 组件的调试符号会作为 build 工件的一部分生成。包含调试符号的文件将 .symbol-index.json 作为后缀(例如 my-component.symbol-index.json)。

在开发环境中注册 Fuchsia 组件的调试符号可启用以下工作流:

除了注册本地生成的调试符号之外,您还可以配置环境以从在线存储空间(例如 Google Cloud Storage)检索调试符号。在全局 symbol-index 配置中添加在线存储空间后,各种 Fuchsia 调试工具(如 ffx logffx debug connect)都可以自动下载和使用在线存储空间中提供的调试符号。

在 Fuchsia 开发环境中,调试符号的注册通常在后台进行。一些 Fuchsia 工具会配置为在检测到调试符号时调用调试符号注册(使用 ffx debug symbol-index add),因此您可能永远不需要在开发过程中手动注册 Fuchsia 组件的调试符号。例如,如果您使用的是 Fuchsia 的 Bazel 规则,则调试符号会在构建过程中自动注册。不过,在必要时,您可以使用 ffx debug symbol-index 命令直接管理调试符号。

列出已注册的调试符号

如需查看全局 symbol-index 配置,请运行以下命令:

ffx debug symbol-index list

此命令会输出类似于以下内容的输出:

$ ffx debug symbol-index list
SymbolIndex {
    includes: [
        "/usr/alice/home/my-fuchsia-project/my-component.symbol-index.json",
    ],
    build_id_dirs: [],
    ids_txts: [],
    gcs_flat: [
        GcsFlat {
           url: "gs://our-fuchsia-project/debug",
           require_authentication: false,
        },
    ],
    debuginfod: []
}

添加了 debuginfod 符号服务器

使用并非在 Fuchsia 树中构建的第三方二进制文件时,您可以添加 debuginfod 服务器以提取符号。上游分发提供 debuginfod 服务器(例如 debuginfod.debian.net)或“联合”服务器(例如 debuginfod.elfutils.org),此类服务器将传送来自许多不同上游来源的符号。请与上游源代码联系,找到其 debuginfod 服务器(如果有)。通常,这些信息会以环境变量的形式呈现,例如:

export DEBUGINFOD_URLS="https://debuginfod.debian.net

如需向符号索引添加上述 debuginfod 服务器,请使用以下命令:

ffx debug symbol-index add <URL>

URL 替换为您要添加的 debuginfod 服务器的网址。例如,如需添加 Debian 的 debuginfod 服务器,请运行以下命令:

ffx debug symbol-index add https://debuginfod.debian.net

注册成功后,该命令会静默退出,不会输出任何内容。调试工具会自动向服务器查询无法在本地找到的符号。

如果要验证注册,请参阅列出已注册的调试符号

移除 debuginfod 符号服务器

如需从全局 symbol-index 配置中移除 debuginfod 服务器,请运行以下命令:

ffx debug symbol-index remove <URL>

URL 替换为您要移除的 debuginfod 服务器的网址。以下示例移除了 debian debuginfod 服务器:

ffx debug symbol-index remove https://debuginfod.debian.net

手动注册本地调试符号

如需在环境中注册调试符号,请运行以下命令:

ffx debug symbol-index add <PATH_TO_DEBUG_SYMBOLS>

PATH_TO_DEBUG_SYMBOLS 替换为调试符号文件的绝对路径。

以下示例注册了 my-component 组件的调试符号:

$ ffx debug symbol-index add /usr/alice/home/my-fuchsia-project/my-component.symbol-index.json

注册成功后,该命令会静默退出且不输出任何输出。

如果要验证注册,请参阅列出已注册的调试符号

移除已注册的本地调试符号

如需从全局 symbol-index 配置中移除调试符号,请运行以下命令:

ffx debug symbol-index remove <PATH_TO_DEBUG_SYMBOLS>

PATH_TO_DEBUG_SYMBOLS 替换为要移除的已注册调试符号文件的确切路径。

以下示例移除了 my-component 组件的调试符号:

$ ffx debug symbol-index remove /usr/alice/home/my-fuchsia-project/my-component.symbol-index.json

移除成功后,该命令会静默退出,不会输出任何内容。

清理放错位置的调试符号

在宿主机上删除已注册的调试符号文件并不意味着全局 symbol-index 配置也会自动更新。

如需从全局 symbol-index 配置中移除所有过时路径(指向已删除的调试符号文件),请运行以下命令:

ffx debug symbol-index clean

例如,如果主机上不再存在 /usr/alice/home/my-fuchsia-project 目录,此命令会从全局 symbol-index 配置中移除 /usr/alice/home/my-fuchsia-project/my-component.symbol-index.json 条目。