使用适用于 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 设备 当前配置为默认目标如果您有额外的紫红色 设备，请点击 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 扩展程序，您可以查看符号化的日志 （人类可读的堆栈轨迹）。等效 运行 ffx log。如需详细了解 ffx log，请参阅 监控设备日志。

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

此图显示了 Fuchsia 扩展程序的 Fuchsia 日志。 有一个过滤器，用于查看所有不包含以下内容的 INFO 严重性日志 网络组件的名称。

  • 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：取决于类别。适用于： <ph type="x-smartling-placeholder">
      </ph>
    • 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"。如需了解详情，请参阅 日志。

运算符

过滤支持以下运算符：

  • :：此运算符可用于查询，具有不同的用途，具体取决于 指定的值： <ph type="x-smartling-placeholder">
      </ph>
    • 如果值为 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（此选项位于左侧的边栏中）， 具有播放和错误图标）。

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

  2. 在 Run and Debug: Run 面板中，点击 Show all automated debug 配置。然后，从命令面板选择 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（此选项位于左侧的边栏中）， 具有播放和错误图标）。

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

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

启动调试程序后：

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