前提条件
本教程假定您已完成入门指南,并且能够构建和运行 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 枚举(用于列出写入操作的已知错误)以及包含一个方法 (WriteItem) 的 Store 协议。按照定义,此库只能将值写入存储区,但在键值对存储区示例系列中,您将增强此库以支持嵌套存储区、读取值和其他功能。
为 FIDL 库创建 GN 目标
现在,您已定义 FIDL,接下来需要创建其他代码可以依赖的 gn 目标。
创建新文件 BUILD.gn:
touch vendor/fidl-tutorials/building-fidl/BUILD.gn
并添加以下 build 规则:
# 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 和 cpp 绑定。
接下来,构建代码:
fx build
探索生成的绑定
现在,代码已构建完成,您可以探索为绑定生成的代码。如需查看生成的代码,请浏览以下目录:
| 绑定类型 | 目录 |
|---|---|
| 铁锈色 | //out/default/fidling/gen/vendor/fidl-tutorials/building-fidl/examples.keyvaluestore.baseline/rust/ |
| 新 C++ | //out/default/fidling/gen/vendor/fidl-tutorials/building-fidl/examples.keyvaluestore.baseline/cpp/fidl/examples.keyvaluestore.baseline/cpp/ |
如需了解详情,请参阅生成的代码。
后续步骤
现在,您已完成本教程,可以开始探索完整的键值对示例系列了。