使用适用于 VS Code 的 Fuchsia 扩展程序

此扩展程序增加了对使用 Fuchsia 目标和源代码的支持，包括：

  • 连接到设备。
  • 调试 C++ 和 Rust 代码（受 zxdb 支持）。
  • 正在分析来自 Fuchsia 设备的日志。

兼容性

Fuchsia 扩展程序与 ffx 9.20220803.3.1 及向前兼容。

修改代码

默认情况下，VS Code 提供语法突出显示、错误和警告、跳转到定义以及列出对 C++ 的引用。

VS Code 会在后台主动分析您的代码，并为您显示各种警告或错误。如需了解详情，请参阅错误和警告。

Fuchsia 扩展程序还为 FIDL 和 CML 提供了语法突出显示功能。

连接到 Fuchsia 设备

借助 Fuchsia 扩展程序，您可以连接到 Fuchsia 目标，可以是实体设备或模拟器。该扩展程序支持多个目标设备，可让您在各种 Fuchsia 设备之间轻松切换。在任何给定时间，您都只能连接到一台设备。

如果您的模拟器已正确配置并启动，您应该会在 VS Code 的状态栏中看到 和 Fuchsia 设备的名称。如果您使用的是模拟器但没有看到 Fuchsia 设备，请参阅启动 Fuchsia 模拟器。

此图显示了如何将 Fuchsia VS Code 扩展程序连接到 Fuchsia 设备。

Fuchsia 设备的方案

您可以在 VS Code 状态栏中点击 和 Fuchsia 设备的名称，查看 Fuchsia 设备的各种选项。这些选项显示在 VS Code 命令面板中。在大多数情况下，您有以下选项：

此图显示了通过 Fuchsia VS Code 扩展程序控制已连接的 Fuchsia 设备的各种选项。

  • 默认目标：<device-name>：此选项显示当前配置为默认目标的 Fuchsia 设备。如果您有其他 Fuchsia 设备，请点击 Set <device-name> as default 以连接到该特定设备。这相当于运行 ffx target default get。
  • 将 <device-name> 设为默认：通过此选项，您可以连接到所选的 Fuchsia 设备。这相当于运行 ffx target default set <device-name>。
  • 显示 <device-name> 的日志：此选项会打开 Fuchsia 扩展程序的 Fuchsia 日志选项卡。如需了解详情，请参阅查看 Fuchsia 日志。这相当于运行 ffx log。
  • 重新启动 <device-name>：此选项会重启您的 Fuchsia 设备。这相当于运行 ffx target reboot。
  • 关机 <device-name>：此选项会将 Fuchsia 设备关机。这相当于运行 ffx target off。如果关闭 Fuchsia 模拟器，则需要使用 ffx emu start <product-bundle> 重新启动模拟器。如需了解详情，请参阅启动 Fuchsia 模拟器。

查看 Fuchsia 日志

借助 Fuchsia 扩展程序，您可以查看已连接的 Fuchsia 设备的符号化日志（简单易懂的堆栈轨迹）。这相当于运行 ffx log。如需详细了解 ffx log，请参阅监控设备日志。

在 Fuchsia 日志标签页中，您可以看到以下内容：

下图显示了来自 Fuchsia 扩展程序的 Fuchsia 日志。有一个过滤器可查看所有 INFO 严重级别日志，这些日志不包含任何网络或 Vulkan 组件名称。

  • Timestamp：这显示事件的时间戳（从系统单调时钟读取）。自设备启动以来的时间。其格式为：5 位数（前导零）表示秒，三位数表示毫秒（尾随零）。
  • PID：此字段会显示生成日志消息的进程的进程标识符。
  • TID：此字段显示启动了生成日志消息的进程的线程的线程标识符。
  • Moniker：显示生成日志消息的组件的名称。如需详细了解组件名称，请参阅组件名称。
  • 标记：显示与日志记录事件相关联的标记。如需详细了解如何向日志添加标记，请参阅在 Rust 中进行日志记录。

  • 严重级别：可让您过滤具有特定严重级别（包括根据至少指定级别的严重级别）的所有日志消息。例如，severity:WARN 或 severity>=WARN 将包含严重级别为 WARN、ERROR 和 FATAL 的所有日志。severity=WARN 将仅包含 WARN 级别的日志。您可以使用严重级别，根据最低、确切或最高严重级别进行过滤，请参阅 [示例][#filter-examples]。有效值（按严重程度从低到高的顺序）为：

    • FATAL
    • ERROR
    • WARN
    • INFO
    • DEBUG
    • TRACE

    如需详细了解日志记录的严重性，请参阅为日志记录选择严重性。

  • 消息：这会显示实际的日志记录消息。

过滤 Fuchsia 日志

您可以过滤 Fuchsia 日志以查找特定的日志记录事件。如需过滤 Fuchsia 日志，请执行以下操作：

在 Fuchsia 日志标签页顶部的过滤日志... 文本框中，使用以下语法：

一个过滤器由一个或多个采用以下格式的子过滤器组成：

<category> <operator> <value>

其中：

  • category：如需了解有效类别，请参阅类别。
  • operator：如需了解有效类别，请参阅运算符。
  • value：取决于类别。例如：
    • severities：严重级别名称。如需了解有效的严重程度，请参阅类别。
    • 其他类别，具体视类型而定：
    • 不含空格（或含有转义空格 \）的字符串
    • 英文双引号字符串：可以包含任何字符，但必须转义 " 和 \` with a。
    • 正则表达式，请参阅正则表达式
    • 数字
    • 一个布尔值（true、false）

此外，子过滤条件可以使用 OR 连接。可以表示任何逻辑表达式。 例如：

this-filter-is-always-here (first-alternative-filter OR second-alternative-filter)

例如，message:"Hello world" 会查询包含 Hello world 的日志消息。

最后，日志记录查看器还支持将原始字符串和正则表达式作为过滤器传递。这会使查看器过滤包含给定值的任何字段。例如：

  • 写入 foo 将显示任何字段包含 foo 一词的日志。
  • 在任意位置写入 foo barwill show logs where any field containsfooandbar`。
  • 写入 "foo bar" 将显示任何位置包含字符串 "foo bar" 的日志。
  • 写入 not foo 或 !foo 将显示任何位置不包含 foo 的日志。

类别

过滤功能支持以下类别：

  • any：可让您按任何受支持的字段进行过滤。这相当于只写入原始字符串，例如，any:foo 与 foo 相同。
  • manifest：这样，您就可以按清单名称（位于启动组件的网址的相应部分）进行过滤。
  • moniker：这可让您按发出日志的组件进行过滤。
  • package-name：用于允许您按软件包的名称（位于启动组件的网址的相应部分）进行过滤。
  • tags：这可让您按日志中可能存在的标记进行过滤。

  • severity：这可让您过滤具有指定严重级别的所有日志消息。有效值（按严重程度降序排列）为：

    • FATAL
    • ERROR
    • WARN
    • INFO
    • DEBUG
    • TRACE

  • message：这可让您按日志消息的内容进行过滤。

此外，您还可以根据 Fuchsia 日志 JSON 载荷中定义的其他键进行过滤。例如 myCustomKey:"Hello world"。如需了解详情，请参阅日志。

运算符

过滤支持以下运算符：

  • :：此运算符可让您进行查询，并根据指定的值有不同的用途：
    • 如果值为 severity，则相应运算符被视为 >=。例如，severity:info 表示 severity>=info。
    • 如果值是一个字符串，则运算符过滤包含该字符串的日志。
    • 如果值不是字符串或严重程度，则相应运算符被视为 =。例如，比较整数或布尔值。
  • =：此运算符可让您查询过滤条件是否包含完全匹配。
  • >、<、>=、<=：这些运算符可用于比较值。只有 custom 类别和 severity 支持此属性。

逻辑运算符

  • or 或 |：这可让您在查询中使用 or 限定符，或者将多个查询串联起来。
  • not 或 !：这可让您在查询中使用 not 逻辑运算符，或者将多个查询链接起来。
  • and 或 &：这可让您在查询中使用 and 逻辑运算符，或者将多个查询链接起来。

运算符 and 优先于 or。因此，以下两个语句是等效的：

moniker:foo severity:info or moniker:bar
(moniker:foo and severity:info) or moniker:bar

not 始终会应用于它旁边的过滤条件/表达式。因此，以下语句是等效的：

not severity:info moniker:bar not (tag:baz id=3)
(not severity:info) moniker:bar !(tag:baz and id=3)

正则表达式

正则表达式可以传递给运算符 : 和 =。将正则表达式与 : 搭配使用时，系统将在它所应用到的类别中搜索该正则表达式。与 = 搭配使用时，整个字段必须与正则表达式匹配。

正则表达式必须在 / 内编写。例如：moniker:/core.+net.+/。

您也可以在不定位类别的情况下使用正则表达式，只需编写 /regex-here/，就像使用原始字符串进行过滤一样。以这种方式使用时，显示包含正则表达式匹配的字段的日志。

示例

  • 显示来自 core/test 和 core/network 名称的日志：

    moniker:core/test|core/network

    这相当于：

    (moniker:core/test | moniker:core/network)

  • 显示严重级别为 error 或更高的日志（其中组件网址包含名为 hello 的软件包，其中清单名为 hello），或者消息包含“hello world”但消息不包含“bye”：

    (package_name:hello | manifest:hello | message:"hello world") severity:error !message:"bye"

  • 显示消息、组件网址、名称等中任何字段包含 hello、world 或 test 的日志：

    any:hello|world|test

  • 显示包含严重级别 INFO、WARN、ERROR 和 FATAL 的日志：

    severity:info

  • 显示仅包含 INFO 严重级别的日志：

    severity=info

  • 显示严重级别为 INFO 但实际上并不包含 INFO 的日志。下面是严重级别为 TRACE 和 DEBUG 的日志：

    severity<info

清除 Fuchsia 日志

Fuchsia 扩展程序流式传输 Fuchsia 日志后，您可以清除列出的 Fuchsia 日志，以查看 Fuchsia 设备的传入日志记录事件。

如需清除 Fuchsia 日志，请点击 Fuchsia 日志标签页右上角的 。

调试代码

借助 Fuchsia 扩展程序，您可以运行 Fuchsia 调试程序 zxdb。这会将 zxdb 调试程序集成到 VS Code IDE 中，以便您在使用源代码时设置断点和其他调试程序设置。

配置配置文件

在开始使用调试控制台之前，您需要创建调试配置文件。您可以创建多个调试配置文件，然后在每个配置文件之间轻松切换。

如需创建调试配置文件，请执行以下操作：

  1. 在 VS Code 中，打开 Run and Debug（此选项位于左侧边栏中，并带有播放和 bug 图标）。

    下图显示了如何在 VS Code 中启动“Run and Debug”。

  2. 在 Run and Debug: Run 面板中，点击 Show all automated debug configurations。然后，从命令面板选择 Add Config (fuchsia)。 编辑器将打开一个 launch.json 文件。

  3. 编辑器应显示预填充的调试配置文件列表，选择以 zxdb 开头的任何配置文件。

    根据需要为您的调试配置文件修改键/值。在修改配置文件之前，请考虑以下事项：

    • name：为配置文件指定一个有意义的标识符。
    • type：指定 zxdb。这是唯一的 Fuchsia 调试程序。
    • request：指定 launch。这是唯一有效的选项。
    • launchcommand：指定 ffx 二进制文件的别名或路径，并附加所有选项和参数。在大多数情况下，这将是一个 ffx component run ....。如需了解详情，请参阅运行组件。
    • process：指定要调试的组件的名称。

  4. 为配置文件添加值后，launch.json 应如下所示：

       {
     "configurations": [
     {
      # Specify a meaningful identifier.
      "name": "Debug examples",
      # This is a fixed required value.
      "type": "zxdb",
      # This is a fixed required value.
      "request": "launch",
      # Specify the desired launchcommand.
      "launchCommand": "tools/ffx component run /core/ffx-laboratory:hello_world fuchsia-pkg://fuchsiasamples.com/hello_world#meta/hello_world.cm --recreate",
      # Specify the process that you want to debug.
      "process": "hello_world"
    }
    ]
  }
  ```

  5. 保存您对 launch.json 文件所做的更改。

您已成功创建调试配置文件。您可以重复相关说明以添加其他配置文件。

运行和调试

创建调试配置文件后，您可以使用该配置文件运行和调试正在使用的组件。

如需启动调试程序，请执行以下操作：

  1. 在 VS Code 中，打开 Run and Debug（此选项位于左侧边栏中，并带有播放和 bug 图标）。

  2. 在 Run and Debug: Run 面板中，使用下拉列表选择您的调试配置文件。然后，点击下拉列表左侧的绿色 以启动调试会话。

    此图显示了如何在 VS Code 中更改调试配置文件。

启动调试程序后：

  • 您可以使用调试控制台标签页运行 zxdb 命令。如需详细了解 zxdb 控制台命令，请参阅 Zxdb 控制台命令和交互模型。
  • 您可以使用 VS Code 调试程序功能执行调试操作，添加断点、日志点等... 如需了解详情，请参阅调试操作。