元件資訊清單 (.cml) 參考資料

.cml 檔案包含單一 json5 物件常值,並具有下列鍵。

如果預期會輸入字串值,通常會提供有效值的清單。 下列字串值類型會重複使用,且必須遵守特定規則。

.cml 檔案會編譯成 FIDL 線路格式 (.cm) 檔案。

字串類型

名稱

功能和元件的子項都會命名。名稱字串可由一或多個下列字元組成:A-Za-z0-9_.-。長度不得超過 255 個字元,且開頭不得為 .-

路徑

路徑是由 名稱序列組成,並以 / 字元做為分隔符號。路徑長度不得超過 4095 個字元。在整份文件中,

  • 相對路徑開頭不得為 / 字元。
  • 命名空間和傳出目錄路徑必須以 / 字元開頭。

參考資料

參照字串的格式為 #<name>,其中 <name> 是指子項的名稱:

頂層鍵

include

string 陣列 (選填)

選用的 include 屬性會說明要併入這個元件資訊清單的零或多個其他元件資訊清單檔案。例如:

include: [ "syslog/client.shard.cml" ]

在上述範例中,元件資訊清單會納入 syslog 程式庫提供的資訊清單分片內容,因此如果元件嘗試寫入 syslog,就能確保元件在執行階段正常運作。依慣例,這類檔案稱為「資訊清單分片」,結尾為 .shard.cml

// 開頭的 include 路徑是 Fuchsia 結帳來源根目錄的相對路徑。不過,請勿在包含路徑前加上 //,如上例所示,這些路徑會從匯出元件資訊清單分片的 Fuchsia SDK 程式庫 (//sdk/lib) 解析。

以 Fuchsia 結帳為例,這兩個路徑包含項目是等效的:

  • syslog/client.shard.cml
  • //sdk/lib/syslog/client.shard.cml

如要查看將任何和所有 include 合併至元件資訊清單檔案的結果,請叫用下列指令:

fx cmc include cml_file --includeroot $FUCHSIA_DIR --includepath $FUCHSIA_DIR/sdk/lib

只要屬性相同,Include 就能處理參照相同能力的重複 useofferexposecapabilities 宣告。例如:

// my_component.cml
include: [ "syslog.client.shard.cml" ]
use: [
    {
        protocol: [
            "fuchsia.posix.socket.Provider",
            "fuchsia.logger.LogSink",
        ],
    },
],

// syslog.client.shard.cml
use: [
    { protocol: "fuchsia.logger.LogSink" },
],

在本例中,合併後的檔案內容會與 my_component.cml 相同,因為 fuchsia.logger.LogSink 已重複。

不過,這樣會編譯失敗:

// my_component.cml
include: [ "syslog.client.shard.cml" ]
use: [
    {
        protocol: "fuchsia.logger.LogSink",
        // properties for fuchsia.logger.LogSink don't match
        from: "#archivist",
    },
],

// syslog.client.shard.cml
use: [
    { protocol: "fuchsia.logger.LogSink" },
],

這項限制的例外狀況是 availability 屬性。如果兩個路徑宣告相同,但其中一個的供應情形比另一個更強,供應情形就會「升級」為較強的值 (如果缺少 availability,系統會預設為 required)。舉例來說:

// my_component.cml
include: [ "syslog.client.shard.cml" ]
use: [
    {
        protocol: [
            "fuchsia.posix.socket.Provider",
            "fuchsia.logger.LogSink",
        ],
        availability: "optional",
    },
],

// syslog.client.shard.cml
use: [
    {
        protocol: "fuchsia.logger.LogSink
        availability: "required",  // This is the default
    },
],

變成:

use: [
    {
        protocol: "fuchsia.posix.socket.Provider",
        availability: "optional",
    },
    {
        protocol: "fuchsia.logger.LogSink",
        availability: "required",
    },
],

包含項目是可遞移的,也就是說,分片可以有自己的包含項目。

包含路徑可以有菱形依附元件。舉例來說,以下是有效情況:A 包含 B、A 包含 C、B 包含 D、C 包含 D。在此情況下,A 會遞移包含 B、C、D。

包含路徑不得有週期。舉例來說,以下情況無效: A 包含 B,B 包含 A。 如果出現上述循環,就會導致編譯階段錯誤。

program

object (選填)

可執行的元件包含 program 區段。program 區段必須設定 runner 屬性,才能選取要執行元件的 Runner。其餘 program 區段的格式由該特定執行元件決定。

ELF 執行器

如果元件使用 ELF 執行元件,program 至少必須包含下列屬性:

  • runner:必須設為 "elf"
  • binary:可執行二進位檔的套件相對路徑
  • args (選用):引數清單

範例:

program: {
    runner: "elf",
    binary: "bin/hippo",
    args: [ "Hello", "hippos!" ],
},

如需完整的屬性清單,請參閱「ELF Runner」。

其他跑者

如果元件使用自訂執行元件,program 節中的值 (runner 除外) 會專屬於該執行元件。執行器會將引數做為鍵/值組合的字典接收。請參閱所用特定執行元件的說明,瞭解執行器預期接收哪些金鑰,以及如何解讀這些金鑰。

children

object 陣列 (選填)

children 區段會宣告子項元件執行個體,如「子項元件執行個體」一節所述。

  • name:(string) 子項元件執行個體的名稱,是包含一或多個下列字元的字串:a-z0-9_.-。在參照中使用這個元件時,系統會以這個名稱識別元件。
  • url:(string) 子項元件執行個體的元件網址
  • startup:(string) 元件執行個體的啟動模式。下列其中一個值:
    • lazy(預設):只有在另一個元件執行個體繫結至元件執行個體時,才啟動元件執行個體。
    • eager:在上層啟動後立即啟動元件執行個體。
  • on_terminate:(選用 string) 決定這個元件終止時要套用的錯誤復原政策。
    • none (預設):不採取任何行動。
    • reboot:如果元件因安全結束以外的任何原因終止,請安全地重新啟動系統。這項特殊功能僅供一小部分元件使用,詳情請參閱終止政策
  • environment:(選用 string) 如有,則為要指派給子項元件執行個體的環境名稱,為 environments 其中之一。如果省略,子項會沿用指派給這個元件的相同環境。

範例:

children: [
    {
        name: "logger",
        url: "fuchsia-pkg://fuchsia.com/logger#logger.cm",
    },
    {
        name: "pkg_cache",
        url: "fuchsia-pkg://fuchsia.com/pkg_cache#meta/pkg_cache.cm",
        startup: "eager",
    },
    {
        name: "child",
        url: "#meta/child.cm",
    }
],

collections

object 陣列 (選填)

collections 區段會宣告集合,如「元件集合」一文所述。

  • name:(string) 元件集合的名稱,為一或多個下列字元的字串:a-z0-9_.-。在參照中使用時,這個名稱會識別這個集合。
  • durability:(string) 集合中子元件例項的持續時間。
    • transient:執行個體會存在,直到父項停止或明確遭到刪除為止。
    • single_run:執行個體會在建立時啟動,停止時則會遭到終止。
  • environment:(選用 string) 如果存在,則為要指派給這個集合中例項的環境,為 environments 之一。如果省略,這個集合中的執行個體會沿用指派給這個元件的相同環境。
  • allowed_offers:(選用 string) 針對這個集合中的元件動態出價的限制。呼叫 fuchsia.component.Realm/CreateChild 時,會指定動態優惠。
    • static_only:只有這個 .cml 檔案中指定的項目。沒有動態優惠。 此為預設值。
    • static_and_dynamic:允許靜態和執行階段 (使用 CreateChild 指定) 方案。
  • allow_long_names:(選填bool) 允許子項名稱長度最多 1024 個字元,而非一般 255 個字元的限制。 預設值為 false。
  • persistent_storage:(選用 bool) 如果設為 true,動態子例項及其後代所用的隔離儲存空間資料,會在例項毀損後保留。以相同名稱建立的新子例項會與先前的例項共用相同的儲存路徑。

範例:

collections: [
    {
        name: "tests",
        durability: "transient",
    },
],

environments

object 陣列 (選填)

environments 區段會宣告環境,如「環境」所述。

  • name:(string) 環境名稱,為一或多個下列字元的字串:a-z0-9_.-。在參照中使用時,這個名稱會識別這個環境。
  • extends:(選用 string) 環境應如何擴充這個領域的環境。
    • realm:從這個元件的環境中,繼承所有屬性。
    • none:從空白環境開始,不要繼承任何項目。
  • runners:(選用 object 陣列) 環境中註冊的執行器。物件陣列,具有下列屬性:

    • runner:(string) 執行元件能力的名稱,來源在 from 中指定。
    • from:(string) 執行元件能力的來源,可以是下列其中一種:
      • parent:元件的父項。
      • self:這個元件。
      • #<child-name>:子項元件例項的參照
    • as:(選用string) 執行元件的明確名稱,會在這個環境中顯示。如果省略此屬性,系統會預設為 runner
  • resolvers:(選用 object 陣列) 環境中註冊的解析器。物件陣列,具有下列屬性:

    • resolver:(string) 解析器能力的名稱,來源指定於 from 中。
    • from:(string) 解析器能力的來源,可以是下列其中一種:
      • parent:元件的父項。
      • self:這個元件。
      • #<child-name>:子項元件例項的參照
    • scheme:(string) 解析器應處理解析作業的網址架構。
  • debug:(object 的選用陣列) 這個環境中任何元件可透過 use from debug 取得的偵錯通訊協定。

    • protocol:(選用 string or array of strings) 要提供的通訊協定名稱。
    • from:(string) 能力的來源,可以是下列其中一種:
      • parent:元件的父項。
      • self:這個元件。
      • #<child-name>:子項元件例項的參照
    • as:(選用 string) 如果指定,則為 protocol 中的能力應提供給用戶端的名稱。如果 protocol 是陣列,則不允許。
  • __stop_timeout_ms:(選用 number) 通知這個環境中的元件終止後,強制終止元件前等待的毫秒數。如果環境從 none 延伸,則這是必填欄位。

範例:

environments: [
    {
        name: "test-env",
        extends: "realm",
        runners: [
            {
                runner: "gtest-runner",
                from: "#gtest",
            },
        ],
        resolvers: [
            {
                resolver: "full-resolver",
                from: "parent",
                scheme: "fuchsia-pkg",
            },
        ],
    },
],

capabilities

object 陣列 (選填)

capabilities 區段定義這個元件提供的功能。從 self「提供」或「公開」的任何功能都必須在此處聲明。

功能欄位

這項功能支援下列能力鍵。必須設定其中一項:

  • protocol:(選用 string or array of strings)
  • service:(選用 string or array of strings)
  • directory:(選用 string)
  • storage:(選用 string)
  • runner:(選用 string)
  • resolver:(選用 string)
  • event_stream:(選用 string or array of strings)
  • dictionary:(選用 string)
  • config:(選用 string)

其他欄位

並支援下列額外欄位:

  • path:(選用 string) 元件程式的輸出目錄內的路徑,用於取得能力。

    對於 protocolservice,預設為 /svc/${protocol},否則為必要。

    對於 protocol,路徑的目標必須是管道,這類通道通常會使用與這項能力名稱相符的通訊協定。

    如果是 servicedirectory,路徑的目標必須是目錄。

    對於 runner,路徑的目標必須是管道,且必須使用 fuchsia.component.runner.ComponentRunner 通訊協定。

    對於 resolver,路徑的目標必須是管道,且必須使用 fuchsia.component.resolution.Resolver 通訊協定。

    對於 dictionary,這是選用項目。如有提供,這就是程式提供的 fuchsia.component.sandbox/DictionaryRouter 路徑,應會傳回 fuchsia.component.sandbox/DictionaryRef,程式可藉此動態提供本身的字典。如果為 dictionary 設定此值,則不允許將 offer 新增至這個字典。

  • rights:(選用 array of string) (僅限 directory) 使用這個目錄時可設定的最大目錄權限

  • from:(選用 string) (僅限 storage) 支援這項儲存空間能力的現有目錄能力的來源元件,可以是下列其中一項:

    • parent:元件的父項。
    • self:這個元件。
    • #<child-name>:子項元件例項的參照
  • backing_dir:(選用 string) (僅限 storage) 支援儲存空間的目錄能力名稱。功能必須可從 from 中參照的元件取得。

  • subdir:(選用 string) (僅限 storage) backing_dir 內的子目錄,用於建立每個元件的獨立儲存空間目錄

  • storage_id:(選用 string) (僅限 storage) 用於隔離元件儲存空間的 ID,可以是下列其中一種:

    • static_instance_id:元件 ID 索引中的執行個體 ID 會做為元件儲存空間的金鑰。如果元件未列於元件 ID 索引中,就無法使用這項儲存空間能力。
    • static_instance_id_or_moniker:如果元件列在元件 ID 索引中,執行個體 ID 會做為元件儲存空間的金鑰。否則,系統會使用儲存空間能力中的元件路徑名稱。
  • type:(選用 string) (僅限 configuration) 設定類型,可以是下列其中一種:

    • bool:布林類型。
    • uint8:未簽署的 8 位元型別。
    • uint16:無符號 16 位元型別。
    • uint32:未簽署的 32 位元型別。
    • uint64:不帶正負號的 64 位元型別。
    • int8:已簽署的 8 位元型別。
    • int16:已簽署的 16 位元型別。
    • int32:已簽署的 32 位元型別。
    • int64:已簽署的 64 位元型別。
    • string:ASCII 字串類型。
    • vector:向量類型。如要瞭解向量中元素的類型,請參閱 element
  • max_size:(選用 non-zero number) (僅限 configuration) 只有在設定 type 為「string」時才支援。這是字串大小上限。

  • max_count:(選用 non-zero number) (僅限 configuration) 只有在設定 type 為「vector」時才支援。這是向量中的元素數量上限。

  • element:(選用 object) (僅限 configuration) 只有在設定 type 為「vector」時才支援。這是設定向量中的元素類型。

    範例 (簡單型別):

    { type: "uint8" }
    

    範例 (字串類型):

    {
      type: "string",
      max_size: 100,
    }
    
  • value:(選用 any) (僅限 configuration) 設定的值。

  • delivery:(選用 string) (僅限 protocol) 指定架構在使用者要求能力時,從這個元件的傳出目錄開啟通訊協定的時間。允許的值包括:

    • eager:(預設) 只要有消費者元件要求,架構就會立即開啟能力。
    • on_readable:當連線要求中管道化的伺服器端點可讀取時,架構就會開啟能力。

use

object 陣列 (選填)

針對可執行元件,在執行階段宣告這個元件在其 命名空間中需要的功能。除非另有指定,否則功能會從 parent 路由,且每個能力都必須透過這個元件和能力來源之間的所有元件,擁有有效的路徑。

功能欄位

這項功能支援下列能力鍵。必須設定其中一項:

  • service:(選用 string or array of strings)
  • directory:(選用 string)
  • protocol:(選用 string or array of strings)
  • dictionary:(選用 string)
  • storage:(選用 string)
  • event_stream:(選用 string or array of strings)
  • runner:(選用 string)
  • config:(選用 string)

其他欄位

並支援下列額外欄位:

  • from:(選用 stringstring) 能力來源。預設值為 parent。 下列其中一項權限:

    • parent:元件的父項。
    • debug:指派給這個元件的環境中,其中一個 [debug_capabilities][fidl-environment-decl]。
    • framework:元件架構執行階段。
    • self:這個元件。
    • #<capability-name>:衍生出所要求能力的其他能力名稱。
    • #<child-name>:子項元件例項的參照

    [fidl-環境-decl]:/reference/fidl/fuchsia.component.decl#Environment

  • path:(選用 string) 在元件的命名空間中安裝能力的路徑。如果是通訊協定,預設值為 /svc/${protocol}directorystorage 必須提供這項資訊。如果宣告包含能力名稱陣列和執行元件功能,則不允許使用此屬性。

  • numbered_handle:(選用 string) 序數 processargs (又稱 「編號控制代碼」),透過該控制代碼,通往這個通訊協定的管道會傳送至元件的 processargs。

  • rights:(選用 array of string) (僅限 directory) 要套用至元件命名空間中目錄的最大目錄權限

  • subdir:(選用 string) (僅限 directory) 目錄能力中的子目錄,可在元件的命名空間中提供。

  • scope:(選用 string or array of strings) (僅限 event_stream) 定義後,事件串流只會包含範圍內定義的元件相關事件。

  • filter:(選用 object) (僅限 event_stream) 要求的事件串流功能需要指定篩選器,參照事件串流中事件適用的通訊協定。篩選器內容會是從「名稱」對應到「通訊協定名稱」的物件。

  • dependency:(選用 string) 來源與這個元件之間的依附元件類型,可以是下列其中一種:

    • strong:強依附元件,用於判斷關機順序。元件管理員保證會在來源停止前停止目標。此為預設值。
    • weak:弱依附元件,關閉時會遭到忽略。當元件管理員停止父項領域時,來源可能會在用戶端之前停止。弱依附元件的用戶端必須能夠處理這些依附元件無法使用的情況。執行元件功能不允許使用這項屬性,因為執行器功能一律為 strong 依附元件。
  • availability:(選填 string) 這項能力供應情形的預期。下列其中一個項目:

    • required (預設):必要依附元件,如果沒有這項能力,元件就無法運作。
    • optional:選用依附元件,即使沒有這項能力,元件也能運作 (但如果沒有這項能力,部分功能可能會停用)。
    • transitional:來源可能會完全省略路徑,甚至不必從 void 路由。用於介紹新功能的柔和轉場效果。 這項屬性不適用於執行元件功能,因為執行器功能一律為 required

    詳情請參閱適用情形說明文件。

  • key:(選用 string) (僅限 config) 這個能力將在元件的 config 區塊中設定的設定金鑰。

  • type:(選用 string) (僅限 config) 設定類型,可以是下列其中一種:

    • bool:布林類型。
    • uint8:未簽署的 8 位元型別。
    • uint16:無符號 16 位元型別。
    • uint32:未簽署的 32 位元型別。
    • uint64:不帶正負號的 64 位元型別。
    • int8:已簽署的 8 位元型別。
    • int16:已簽署的 16 位元型別。
    • int32:已簽署的 32 位元型別。
    • int64:已簽署的 64 位元型別。
    • string:ASCII 字串類型。
    • vector:向量類型。請參閱 element,瞭解向量中的元素類型
  • max_size:(選用 non-zero number) (僅限 configuration) 只有在設定 type 為「string」時才支援。這是字串大小上限。

  • max_count:(選用 non-zero number) (僅限 configuration) 只有在設定 type 為「vector」時才支援。這是向量中的元素數量上限。

  • element:(選用 object) (僅限 configuration) 只有在設定 type 為「vector」時才支援。這是設定向量中的元素類型。

    範例 (簡單型別):

    { type: "uint8" }
    

    範例 (字串類型):

    {
      type: "string",
      max_size: 100,
    }
    
  • default:(選用 any) (僅限 configuration) 這項設定的預設值。如果能力為選用功能,且是從 void 路由傳送,則會使用預設值。 只有在 availability 不是 required 時,系統才會支援這項功能。

範例:

use: [
    {
        protocol: [
            "fuchsia.ui.scenic.Scenic",
            "fuchsia.accessibility.Manager",
        ]
    },
    {
        directory: "themes",
        path: "/data/themes",
        rights: [ "r*" ],
    },
    {
        storage: "persistent",
        path: "/data",
    },
    {
        event_stream: [
            "started",
            "stopped",
        ],
        from: "framework",
    },
    {
        runner: "own_test_runner".
        from: "#test_runner",
    },
],

expose

object 陣列 (選填)

宣告提供給父項元件或架構的功能。從 self 或子項元件 expose 都是有效的。

功能欄位

這項功能支援下列能力鍵。必須設定其中一項:

  • service:(選用 string or array of strings)
  • protocol:(選用 string or array of strings)
  • directory:(選用 string)
  • runner:(選用 string)
  • resolver:(選用 string)
  • dictionary:(選用 string)
  • config:(選用 string)

其他欄位

並支援下列額外欄位:

  • from:(string or array of strings) from:能力來源,可以是下列其中一種:
    • self:這個元件。必須有對應的 capability 宣告。
    • framework:元件架構執行階段。
    • #<child-name>:子項元件例項的參照
  • as:(選用 string) 目標所知的能力名稱。如果省略,預設為原始名稱。提供多個能力名稱的陣列時,無法使用 as
  • to:(選用 ) 能力目標。stringparentframework。預設為 parent
  • rights:(選用 array of string) (僅限 directory) 要套用至公開目錄能力的目錄權限上限。
  • subdir:(選用 string) (僅限 directory) 來源目錄中子目錄的相對路徑,可做為路徑能力。
  • event_stream:(選用 string or array of strings) (僅限 event_stream) 要公開的事件串流名稱。
  • scope:(選用 string or array of strings) (僅限 event_stream) 要公開的事件串流範圍。這項功能可用於縮減事件串流參照的元件範圍,使其只參照範圍中定義的元件。
  • availability:(選用 string) availability(選用):這項能力供應情形的預期情況。影響建構時間和執行階段路徑驗證。下列其中一項權限:

    • required (預設):必要依附元件,來源必須存在並提供該元件。如果公開目標需要這項能力才能正常運作,請使用此選項。
    • optional:選用依附元件。如果公開的目標可搭配或不搭配這項能力運作,請使用這項註解。目標不得對能力有 required 依附元件。這項公開內容的最終來源必須是 void 或實際元件。
    • same_as_target:這項能力的可用性預期會與目標相符。如果目標需要這項能力,這個欄位會設為 required。 如果目標對能力有選用依附元件,則欄位會設為 optional
    • transitional:類似 optional,但會容許缺少來源。只有在多步驟程式碼變更的過渡期間,為避免驗證錯誤時,才使用這項功能。

    詳情請參閱適用情形說明文件。

  • source_availability:(選填 string) 這項優惠的來源是否必須存在。下列其中一項權限:

    • required (預設):必須在這個資訊清單中定義來源 (from)。
    • unknown:如果此資訊清單在處理包含項目後,未定義來源 (from),則此優惠的來源會重新編寫為 void

範例:

expose: [
    {
        directory: "themes",
        from: "self",
    },
    {
        protocol: "pkg.Cache",
        from: "#pkg_cache",
        as: "fuchsia.pkg.PackageCache",
    },
    {
        protocol: [
            "fuchsia.ui.app.ViewProvider",
            "fuchsia.fonts.Provider",
        ],
        from: "self",
    },
    {
        runner: "web-chromium",
        from: "#web_runner",
        as: "web",
    },
    {
        resolver: "full-resolver",
        from: "#full-resolver",
    },
],

offer

object 陣列 (選填)

宣告可供子項元件執行個體或子項集合使用的功能。

功能欄位

這項功能支援下列能力鍵。必須設定其中一項:

  • protocol:(選用 string or array of strings)
  • service:(選用 string or array of strings)
  • directory:(選用 string)
  • storage:(選用 string)
  • runner:(選用 string)
  • resolver:(選用 string)
  • event_stream:(選用 string or array of strings)
  • dictionary:(選用 string)
  • config:(選用 string)

其他欄位

並支援下列額外欄位:

  • service:(選用 string or array of strings) 轉送服務時,服務功能名稱
  • protocol:(選用 string or array of strings) 轉送通訊協定時,通訊協定功能名稱
  • directory:(選用 string or array of strings) 路由目錄時,目錄功能名稱
  • runner:(選用 string or array of strings) 轉送執行元件時,執行器功能名稱
  • resolver:(選用 string or array of strings) 路由解析器時,解析器功能名稱
  • storage:(選用 string or array of strings) 轉送儲存空間能力時,儲存空間功能名稱
  • dictionary:(選用 string or array of strings) 路由字典時,字典功能名稱
  • config:(選用 string or array of strings) 轉送設定時,設定能力的名稱
  • from:(string or array of strings) from:能力來源,可以是下列其中一種:
    • parent:元件的父項。這個來源可用於所有能力類型。
    • self:這個元件。必須有對應的 capability 宣告。
    • framework:元件架構執行階段。
    • #<child-name>:子項元件例項的參照。只有在提供通訊協定、目錄或執行元件功能時,才能使用這個來源。
    • void:來源刻意省略。只有在 availabilityoptionaltransitional 時才有效。
  • to:(string or array of strings) 功能目標。下列其中一個值:
    • #<target-name> 或 [#name1, ...]:子項或集合的參照,或是參照陣列。
    • all:包含所有子項參照offer 子句簡寫。
  • as:(選用 string) 能力的明確名稱,目標會使用這個名稱。如果省略,預設為原始名稱。提供多個名稱的陣列時,無法使用 as
  • dependency:(選用 string) 來源與目標之間的依附元件類型,可以是下列其中一種:
    • strong:強依附元件,用於判斷關機順序。元件管理員保證會在來源停止前停止目標。此為預設值。
    • weak:弱依附元件,關機時會遭到忽略。元件管理員停止父項領域時,來源可能會在用戶端之前停止。弱依附元件的用戶端必須能夠處理這些依附元件無法使用的情況。
  • rights:(選用 array of string) (僅限 directory) 要套用至所提供目錄能力的目錄權限上限。
  • subdir:(選用 string) (僅限 directory) 來源目錄中子目錄的相對路徑,可做為路徑能力。
  • event_stream:(選用 string or array of strings) (僅限 event_stream) 提供的事件串流名稱。
  • scope:(選用 string or array of strings) (僅限 event_stream) 定義後,事件串流只會包含範圍內定義的元件相關事件。
  • availability:(選用 string) availability(選用):這項能力供應情形的預期情況。影響建構時間和執行階段路徑驗證。下列其中一項權限:

    • required (預設):必要依附元件,來源必須存在並提供該元件。如果這項優惠的目標需要這項能力才能正常運作,請使用此選項。
    • optional:選用依附元件。如果優惠目標可搭配或不搭配這項能力運作,請使用這項設定。目標不得對能力有 required 依附元件。這項優惠的最終來源必須是 void 或實際元件。
    • same_as_target:這項能力的可用性預期會與目標相符。如果目標需要這項能力,這個欄位會設為 required。 如果目標對能力有選用依附元件,則欄位會設為 optional
    • transitional:類似 optional,但會容許缺少來源。只有在多步驟程式碼變更的過渡期間,為避免驗證錯誤時,才使用這項功能。

    詳情請參閱適用情形說明文件。

  • source_availability:(選填 string) 這項優惠的來源是否必須存在。下列其中一項權限:

    • required (預設):必須在這個資訊清單中定義來源 (from)。
    • unknown:如果此資訊清單在處理包含項目後,未定義來源 (from),則此優惠的來源會重新編寫為 void

範例:

offer: [
    {
        protocol: "fuchsia.logger.LogSink",
        from: "#logger",
        to: [ "#fshost", "#pkg_cache" ],
        dependency: "weak",
    },
    {
        protocol: [
            "fuchsia.ui.app.ViewProvider",
            "fuchsia.fonts.Provider",
        ],
        from: "#session",
        to: [ "#ui_shell" ],
        dependency: "strong",
    },
    {
        directory: "blobfs",
        from: "self",
        to: [ "#pkg_cache" ],
    },
    {
        directory: "fshost-config",
        from: "parent",
        to: [ "#fshost" ],
        as: "config",
    },
    {
        storage: "cache",
        from: "parent",
        to: [ "#logger" ],
    },
    {
        runner: "web",
        from: "parent",
        to: [ "#user-shell" ],
    },
    {
        resolver: "full-resolver",
        from: "parent",
        to: [ "#user-shell" ],
    },
    {
        event_stream: "stopped",
        from: "framework",
        to: [ "#logger" ],
    },
],

facets

object (選填)

內含元件可自行解讀的中繼資料。元件架構不會強制執行這個部分的結構定義,但第三方可能會要求其層面遵守特定結構定義。

config

object (選填)

元件定義的設定結構。每個鍵代表架構中的單一欄位。

設定欄位是 JSON 物件,且必須定義 type,可以是下列字串之一:booluint8int8uint16int16uint32int32uint64int64stringvector

範例:

config: {
    debug_mode: {
        type: "bool"
    },
}

根據預設,系統會從元件的套件解析欄位。如要在執行階段變更值,必須使用 mutability 規範符。

範例:

config: {
    verbose: {
        type: "bool",
        mutability: [ "parent" ],
    },
},

目前僅支援 "parent" 可變動性指定符。

字串必須將 max_size 屬性定義為非零整數。

範例:

config: {
    verbosity: {
        type: "string",
        max_size: 20,
    }
}

向量必須將 max_count 屬性設為非零整數。向量也必須將 element 屬性設為 JSON 物件,說明向量中包含的元素。向量可包含布林值、整數和字串,但不能包含其他向量。

範例:

config: {
    tags: {
        type: "vector",
        max_count: 20,
        element: {
            type: "string",
            max_size: 50,
        }
    }
}