使用 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 裝置選項

您可以按一下 和 請在 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 擴充功能可讓您查看經過符號化的記錄 (人類可讀的堆疊追蹤)。相當於 執行 ffx log。如要進一步瞭解 ffx log，請參閱 監控裝置記錄。

「Fuchsia logs」分頁中會顯示下列資料：

這張圖片顯示 Fuchsia 擴充功能的 Fuchsia 記錄。 使用這個篩選器可查看不含任何項目的 INFO 嚴重性記錄 網路或 vulkan 元件 Monikers

  • Timestamp：顯示時間戳記 (讀取 系統單調時鐘)。時間是 。格式為 5 位數字 (前方加 0) 代表秒數，三位數代表毫秒 (結尾為零)。
  • PID：顯示產生記錄的程序 ID 撰寫新的電子郵件訊息
  • TID：顯示啟動程序的執行緒執行緒 ID 產生記錄訊息
  • Moniker：顯示產生的元件的元件路徑名稱 。如要進一步瞭解元件單元件，請參閱 元件元件。
  • 代碼：顯示與記錄事件相關聯的代碼。 如要進一步瞭解如何在記錄檔中加入標記， 在 Rust 中記錄。

  • 嚴重性：這可讓您篩選含有特定嚴重性的所有記錄訊息 包括嚴重性至少達特定等級的 舉例來說，severity:WARN 或 severity>=WARN 會包含含有以下內容的所有記錄： 嚴重性等級 WARN、ERROR 和 FATAL。「severity=WARN」只會 包含擁有 WARN 層級的記錄。您可以使用嚴重性來篩選 嚴重性下限、確切或最高嚴重性，請參閱 [範例][#filter-examples]。 有效的值 (按嚴重性遞減排序) 為：

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

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

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

篩選 Fuchsia 記錄

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

在「Fuchsia logs」(Fuchsia 記錄) 分頁頂端的「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 可讓你在專案 Cloud Build 觸發條件 會在您變更原始碼時自動啟動建構作業

設定個人資料

開始使用偵錯控制台前，您必須先建立偵錯設定檔。 您可以建立多個偵錯設定檔，然後在每個設定檔間輕鬆切換

如要建立偵錯設定檔，請按照下列步驟操作：

  1. 在 VS Code 中，開啟「Run and Debug」 (位於左側列， 會顯示播放和錯誤圖示)。

    這張圖片顯示如何在 VS Code 中開始執行及偵錯。

  2. 在「Run and Debug: Run」面板中，按一下「Show all auto debug」 設定接著，從指令區塊面板選取「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」主控台分頁執行 zxdb 指令。如要 有關 zxdb 控制台指令的資訊，請參閱 Zxdb 主控台指令和互動模型。
  • 您可以使用 VS Code 偵錯工具功能執行偵錯動作。 中斷點、記錄點等...若需更多資訊，請參閲 偵錯動作。