使用 VS Code 的 Fuchsia 擴充功能

這項擴充功能新增了與 Fuchsia 目標和原始碼搭配使用的支援，包括：

  • 正在連線到裝置。
  • 對 C++ 和 Rust 程式碼進行偵錯 (由 zxdb 支援)。
  • 正在分析 Fuchsia 裝置的記錄。

相容性

Fuchsia 擴充功能與 ffx 9.20220803.3.1 和向前版本相容。

編輯程式碼

根據預設，VS 程式碼會提供語法醒目顯示、錯誤和警告，跳至定義，並列出 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> 設為預設裝置：這個選項可讓您連線至所選 Fuuchsia 裝置。這相當於執行 ffx target default set <device-name>。
  • 顯示 <device-name> 的記錄：此選項會開啟 Fuchsia 擴充功能的「Fuchsia logs」分頁。詳情請參閱「查看 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 記錄。設有篩選器，即可查看所有不包含任何網路或 vulkan 元件視窗的所有 INFO 嚴重性記錄檔。

  • 時間戳記：顯示事件的時間戳記 (從系統單一時鐘讀取)。而是裝置啟動後的時間。其格式為 5 位數 (前方加零)，秒為三位數，以毫秒表示 (結尾為零)。
  • PID：顯示產生記錄訊息的程序 ID。
  • TID：顯示啟動記錄訊息的程序執行緒 ID。
  • Moniker：顯示產生記錄訊息的元件路徑名稱。如要進一步瞭解元件 Monikers，請參閱「元件自動化工具」。
  • 標記：顯示與記錄事件相關聯的標記。如要進一步瞭解如何新增標記至記錄檔，請參閱 Rust 中的記錄。

  • 「Severity」(嚴重性)：可讓您篩選具有特定嚴重性的所有記錄訊息，包括以至少指定等級的嚴重性做為依據。例如，severity:WARN 或 severity>=WARN 會包含嚴重性等級為 WARN、ERROR 和 FATAL 的所有記錄。severity=WARN 只會包含 WARN 層級的記錄。您可以使用嚴重性，根據最小、完全或最大嚴重性進行篩選，請參閱 [範例][#filter-examples]。有效的值 (按照嚴重性排序) 如下：

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

    如要進一步瞭解記錄記錄的嚴重性，請參閱選擇記錄的嚴重性。

  • 訊息：顯示實際的記錄訊息。

篩選 Fuchsia 記錄檔

您可以篩選 Fuchsia 記錄，找出特定的記錄事件。篩選 Fuchsia 記錄的方法如下：

在「Fuchsia logs」分頁頂端的「Filter logs...」文字方塊中，使用下列語法：

篩選器是由一或多個子篩選器組成，格式如下：

<category> <operator> <value>

在此情況下：

  • category：如需有效類別，請參閱「類別」。
  • operator：如要瞭解有效的類別，請參閱運算子。
  • value：視類別而定。：
    • 嚴重性：嚴重程度名稱。如要瞭解有效的嚴重性，請參閱類別。
    • 其他類別 (視類型而定)：
    • 不含空格的字串 (或含逸出空格 \)
    • 雙引號的字串：可包含任何字元，但必須逸出 " 和 \` 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」(執行和偵錯) (此選項在左側導覽列中，並包含播放和錯誤圖示)。

    這張圖片顯示如何在 VS Code 中啟動執行和偵錯。

  2. 在「Run and Debug: Run」面板中，按一下「Show all auto debug configurations」。接著從指令區塊面板選取「Add Config (fuchsia)」。編輯器會開啟 launch.json 檔案。

  3. 編輯器應會顯示預先填入的偵錯設定檔清單，選取任何以 zxdb 開頭的設定檔。

    視需要修改偵錯設定檔的鍵/值。編輯設定檔之前，請考慮以下事項：

    • name：為設定檔指定有意義的 ID。
    • 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 中的偵錯設定檔。

啟動偵錯工具後：

  • 您可以使用「Debug Console」分頁執行 zxdb 指令。如要進一步瞭解 zxdb 主控台指令，請參閱 Zxdb 主控台指令和互動模型。
  • 您可以使用 VS Code 偵錯工具功能執行偵錯動作、新增中斷點、記錄點等... 詳情請參閱「偵錯動作」。