本文件說明如何在開發期間直接將元件新增至元件執行個體樹狀結構,並在執行階段與元件互動。
- 工作階段元件: 建立及執行工作階段
- 測試元件: 執行 Fuchsia 測試
概念
在執行元件之前,請先瞭解以下概念:
如要進一步瞭解元件執行作業,請參閱「元件生命週期」。
元件執行個體
執行元件的第一步,是在樹狀結構中新增元件執行個體。 capabilities
探索靜態元件
靜態元件宣告為樹狀結構中另一個元件執行個體的子項。您可以使用 ffx component show
來判斷靜態元件執行個體的路徑名稱和元件網址:
ffx component show COMPONENT_NAME
將 COMPONENT_NAME
替換為元件名稱。以下範例顯示 pkg-resolver
元件的指令輸出:
$ ffx component show pkg-resolver
Moniker: /core/pkg-resolver
URL: fuchsia-pkg://fuchsia.com/pkg-resolver#meta/pkg-resolver.cm
Type: CML static component
Component State: Resolved
Execution State: Running
...
無法在執行階段建立或刪除靜態元件執行個體。
管理動態元件
動態元件是在集合的執行階段內建立。您可以使用 ffx component create
建立新的元件執行個體,並在現有集合中提供目標路徑名稱,以及用於解析元件的元件網址:
ffx component create TARGET_MONIKER COMPONENT_URL
將 TARGET_MONIKER
替換為現有集合中新元件的目的地路徑名稱,並將 COMPONENT_URL
替換為元件的提供位置。舉例來說,下列指令會在 ffx-laboratory
集合中建立名為 hello-world
的新元件執行個體:
$ ffx component create /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
URL: fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
Moniker: /core/ffx-laboratory:hello-world
Creating component instance...
同樣地,您可以使用 ffx component destroy
提供動態元件路徑名稱,藉此刪除動態元件執行個體:
ffx component destroy TARGET_MONIKER
將 TARGET_MONIKER
替換為要刪除的元件的路徑名稱。以下範例會刪除您在上述步驟中建立的 hello-world
元件:
$ ffx component destroy /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Destroying component instance...
元件執行
一旦樹狀結構中有元件執行個體,您可以使用 ffx component
啟動及停止目標執行個體。
啟動執行個體
使用 ffx component start
明確啟動元件執行個體:
ffx component start TARGET_MONIKER
將 TARGET_MONIKER
替換為元件的路徑名稱以開始。以下範例會啟動先前建立的 hello-world
元件:
$ ffx component start /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Starting component instance...
停止執行個體
使用 ffx component stop
以透過模擬器終止執行中的元件執行個體:
ffx component stop TARGET_MONIKER
將 TARGET_MONIKER
替換為元件的路徑名稱,以便停止。以下範例會停止前往上述啟動的 hello-world
元件:
$ ffx component stop /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Stopping component instance...
執行元件
ffx component run
指令提供快速入門導覽課程,讓您在開發期間執行基本元件。這是 ffx component create
的捷徑,後面接著 ffx component start
:
ffx component run TARGET_MONIKER COMPONENT_URL
將 TARGET_MONIKER
替換為現有集合中新元件的目的地路徑名稱,並將 COMPONENT_URL
替換為元件的提供位置。舉例來說,下列指令會在 ffx-laboratory
集合中建立名為 hello-world-rust
的新元件執行個體:
$ ffx component run /core/ffx-laboratory:hello-world-rust fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
URL: fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
Moniker: /core/ffx-laboratory:hello-world-rust
Creating component instance...
Starting component instance...
上述範例相當於執行下列個別 ffx
指令:
$ ffx component create /core/ffx-laboratory:hello-world-rust fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
$ ffx component start /core/ffx-laboratory:hello-world-rust
更新元件的方式
當您變更元件時,您通常會希望更新在裝置上執行的其中一個執行個體。例如,您可以變更元件的二進位檔,然後重新啟動元件,以使用新的二進位檔執行。或者,您可以變更資訊清單,藉此新增能力路徑,以便在裝置上提供這些能力路徑。
ffx component reload
指令是重新載入元件最快速且最完整的方式。但除了瞭解其他方法,還能針對特殊用途進行更精準的作業。
以下摘要說明各項方法,並參閱下文。
摘要
指令 | 說明 | 更新套件 | 更新資訊清單 | 保留資源 |
---|---|---|---|---|
ffx 元件重新載入 | 包括停止、更新及啟動 | 是 | 是 | 是 |
ffx 元件 刪除/建立/開始 | 然後開始下載 | 是 | 是 | 否 |
ffx 元件執行 --recreate | 然後開始下載 | 是 | 是 | 否 |
ffx 元件 停止/開始 | 就在不刪除任何機制的情況下 | 否 | 否 | 是 |
- 「更新套件」表示在重新載入套件時,程式碼會更新。
- 「更新資訊清單」表示系統會重新載入資訊清單快取,並更新 FIDL 檔案中包含的其他資訊。
- 「保留資源」代表系統會改為保留刪除指令會釋出的資源 (例如儲存空間)。
重新載入
更新元件的程式碼和資訊清單,同時保留下列資源:
ffx component reload TARGET_MONIKER
這個指令會先關閉元件,然後重新載入並重新啟動元件。這個指令會更新套件和資訊清單,而不會刪除元件或釋出資源。
reload
指令會保留元件的資源,例如儲存空間。如果初始化、取得或重新建立特定狀態下的資源用於偵錯,這項預留作業會很有幫助。
刪除元件的成本也很高 (例如需要關閉並重新啟動工作階段,或目標裝置/模擬器) 也會加快重新載入速度。
刪除/建立/開始
如要完全重新載入元件並捨棄取得的資源,請先刪除現有的元件執行個體,然後再重新啟動。您可以使用下列功能:
$ ffx component destroy TARGET_MONIKER
$ ffx component create TARGET_MONIKER COMPONENT_URL
$ ffx component start TARGET_MONIKER
這個序列會重新載入套件和資訊清單,因此程式碼和能力變更會更新。不過刪除元件也會釋出其使用的所有資源。如果您的目標是從完全重新初始化的元件著手,您可能會需要這種完整重設。
執行 --recreate
與刪除/建立/開始序列類似,是一種方便的指令,就是附帶 --recreate
的 run
指令:
ffx component run TARGET_MONIKER COMPONENT_URL --recreate
停止/開始
雖然這並非更新主要的方法,但停止更新後會產生部分更新的副作用。
$ ffx component stop TARGET_MONIKER
$ ffx component start TARGET_MONIKER
假設正在執行套件管理員 (例如 ffx serve
),系統會載入並執行最新版本的元件程式碼。不過,礙於 Fuchsia 元件架構中快取的運作方式,資訊清單不會更新。資訊清單包含元件的轉送方式和 *.cm
檔案中定義的其他資訊。因此,如果您變更元件的能力路徑,停止及啟動元件不會擷取這些變更。
ffx-laboratory
ffx-laboratory
是一個元件集合,提供一組受限制的開發功能。此集合中的元件提供下列功能:
- 通訊協定功能
fuchsia.logger.LogSink
:記錄記錄訊息fuchsia.process.Launcher
:建立新程序
- 儲存空間功能
tmp
:臨時儲存空間 (非永久儲存空間)data
:由/tmp
支援的模擬永久儲存空間cache
:由/tmp
支援的模擬快取儲存空間
- 目錄功能
/dev
:驅動程式管理員提供的裝置驅動程式庫devfs
/boot
:元件管理服務提供的唯讀bootfs
ffx-laboratory
是 transient
集合。這個集合中的元件執行個體會在停止後持續保留。如要刪除這個集合中的元件執行個體,請使用 ffx component destroy
指令。
疑難排解
本節包含在開發期間執行元件時可能會遇到的常見問題。
無法解析元件
使用 ffx component start
或 ffx component run
時,如果元件架構無法解析元件執行個體,您可能會遇到以下錯誤:
$ ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
Moniker: /core/ffx-laboratory:hello-world
Creating component instance...
Starting component instance...
Lifecycle protocol could not bind to component instance: InstanceCannotResolve
如果元件網址未解析為有效的元件資訊清單,就會發生這種情形。
如要解決這個問題,請確認下列事項:
元件執行個體已存在
使用 ffx component create
或 ffx component run
時,如果元件執行個體已存在,您可能會遇到以下錯誤:
$ ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
Moniker: /core/ffx-laboratory:hello-world
Creating component instance...
Component instance already exists. Use --recreate to destroy and recreate a new instance, or --name to create a new instance with a different name.
如果其他元件執行個體已在使用目標路徑名稱,就會發生這種情形。
如要解決這個問題,請使用 ffx component
destroy
指令手動刪除執行個體:
$ ffx component destroy /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Destroying component instance...
如果您使用的是 ffx component run
,請新增 --recreate
旗標以刪除執行個體並重新建立:
$ ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm --recreate
URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
Moniker: /core/ffx-laboratory:hello-world
Creating component instance...
Component instance already exists. Destroying...
Recreating component instance...
Starting component instance...
或者,新增 --name
旗標,建立名稱不同的新執行個體:
$ ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm --name hello-world-2
URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
Moniker: /core/ffx-laboratory:hello-world-2
Creating component instance...
Starting component instance...