建立 FIDL 程式庫

必要條件

本教學課程假設您已完成入門指南,並可建構及執行 Fuchsia。您應熟悉在 Fuchsia 上執行元件,這部分請參閱「執行範例元件」。

總覽

在本教學課程中,您將定義及建構 FIDL 程式庫 examples.keyvaluestore.baseline。完成後,您將瞭解如何編寫 FIDL 檔案、設定必要的 GN 規則,以及建構 FIDL 繫結。

本教學課程的完整來源位於 //examples/fidl/new/key_value_store/baseline/fidl/

定義 FIDL 程式庫

首先,請從 Fuchsia 結帳作業執行下列指令,為本教學課程建立目錄:

mkdir -p vendor/fidl-tutorials/building-fidl

建立新檔案 key_value_store.test.fidl

touch vendor/fidl-tutorials/building-fidl/key_value_store.test.fidl

FIDL 檔案名稱使用 .fidl 副檔名。與 C 標頭檔類似,FIDL 檔案會定義資料型別,並宣告功能介面。這些宣告會與 FIDL 專屬資料型別搭配使用,在 FIDL 端點之間進行通訊。

將下列 FIDL 程式碼新增至 key_value_store.test.fidl

// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.baseline;

/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
    key string:128;
    value vector<byte>:64000;
};

/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
    UNKNOWN = 0;
    INVALID_KEY = 1;
    INVALID_VALUE = 2;
    ALREADY_EXISTS = 3;
};

/// A very basic key-value store - so basic, in fact, that one may only write to it, never read!
@discoverable
open protocol Store {
    /// Writes an item to the store.
    flexible WriteItem(struct {
        attempt Item;
    }) -> () error WriteError;
};

這項 FIDL 定義了 Item 型別,代表商店中的項目;WriteError 列舉,列出寫入作業的已知錯誤;以及 Store 通訊協定,其中包含一個方法:WriteItem。如定義所述,這個程式庫只能將值寫入商店,但在鍵/值商店範例系列中,您會擴增這個程式庫,以支援巢狀商店、讀取值和其他功能。

為 FIDL 程式庫建立 GN 目標

定義 FIDL 後,您需要建立其他程式碼可依附的 gn 目標。

建立新檔案 BUILD.gn

touch vendor/fidl-tutorials/building-fidl/BUILD.gn

並新增下列建構規則:

# Copyright 2022 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

import("//build/fidl/fidl.gni")

# Builds the FIDL library into a set of language specific bindings. Bindings for a given language
# may be imported by depending on this target, followed by a language-specific underscore:
#
#   ":examples.keyvaluestore.baseline_rust"
#   ":examples.keyvaluestore.baseline_cpp"
#   ...and so on
#
fidl("examples.keyvaluestore.baseline") {
  sources = [ "key_value_store.test.fidl" ]
  excluded_checks = [ "wrong-prefix-for-platform-source-library" ]
  enable_rust_next = true
}

gn 範本 fidl("examples.keyvaluestore.baseline") 會建立必要的目標,以便從其他程式碼使用這個程式庫。

編譯 FIDL 程式庫

如要建構新的 FIDL 程式庫,請執行下列 fx set 指令:

fx set core.x64\
  --with //vendor/fidl-tutorials/building-fidl:examples.keyvaluestore.baseline_rust\
  --with //vendor/fidl-tutorials/building-fidl:examples.keyvaluestore.baseline_cpp

這個指令會設定 fx build,產生 Rust 和 C++ 繫結。

接著,建構程式碼:

fx build

探索產生的繫結

程式碼建構完成後,您就可以探索為繫結產生的程式碼。如要查看產生的程式碼,請瀏覽下列目錄:

繫結類型 目錄
鐵鏽色 //out/default/fidling/gen/vendor/fidl-tutorials/building-fidl/examples.keyvaluestore.baseline/rust/
new c++ //out/default/fidling/gen/vendor/fidl-tutorials/building-fidl/examples.keyvaluestore.baseline/cpp/fidl/examples.keyvaluestore.baseline/cpp/

詳情請參閱生成的程式碼

後續步驟

您已完成本教學課程,現在可以探索完整的鍵/值儲存空間範例系列