集成商开发套件 (IDK)

此文件夹包含有关开发 Fuchsia 集成开发套件 (IDK) 的信息。

下载 Fuchsia IDK

支持

请注意，Fuchsia 目前不支持公开使用 Fuchsia IDK。IDK 中的 API 随时都可能发生变更，恕不另行通知。

策略

Fuchsia 采用模块化方法向开发者公开 Fuchsia 平台。

此策略的核心是集成开发套件 (IDK)，它是从提交更改中提及的 Git 代码库中提炼出来的。此 IDK 包含一小组库和工具，这些库和工具是开始构建和运行以 Fuchsia 为目标平台的程序所必需的。IDK 中的内容代表了 Fuchsia 平台开发者向潜在开发者提供的最基本合约。

Fuchsia IDK 不适合立即使用。它不包含对工具链或构建系统的任何引用，实际上也不需要任何特定的工具链或构建系统实例。虽然这可能被视为缺点，但实际上这是一种功能，是构建功能齐全的 SDK 的分层方法中不可或缺的一部分。虽然 IDK 未绑定到特定构建系统，但它包含可用于为各种构建系统提供支持的元数据，从而生成各种 SDK 发行版本。将 IDK 与这些各种发行版本明确分开，可实现非常灵活的发布方案和迭代周期。

本文档重点介绍了 IDK 创建流程的详细信息。IDK 中包含的（托管在 //idk/docs 下）文档包含有关如何使用 IDK 的信息。

哪些内容属于 IDK？

默认情况下，Fuchsia 树中的一段代码无法添加到任何 IDK：参与是严格的选择决定。此外，此决策会在代码的 build 文件中本地编码。这样做是出于以下几个原因：

  1. 修改代码的开发者需要尽早了解对外部客户的潜在影响；
  2. 将该代码发布到 IDK 可能需要开发者提供额外的信息，以便告知构建系统如何正确地将该代码包含在 SDK 中；
  3. 知道代码是否可以包含在 IDK 中后，构建系统就可以对该代码执行额外的检查，以确保其符合 IDK 标准。

为了能在 IDK 中提供，一段代码必须遵循一组标准和准则。

基础架构

SDK 创建流水线由两部分组成：

  1. 后端，使用构建系统生成包含已编译工件、源文件和元数据的 tarball；
  2. 前端，用于对该 tarball 应用转换，并转换为 SDK 分发包等。

后端

后端实际上只是构建系统的一种特殊用途。换句话说，运行 SDK 后端相当于向 Fuchsia 构建系统传递一组正确的参数，后者反过来会生成具有设定布局的归档文件。此处介绍了后端的内部运作机制。

后端不仅会生成 IDK，还会用作 API 演变的控制机制。IDK 公开的 API Surface 会捕获在一组代表其元素的参考文件中：开发者需要通过更新相关参考文件（其最新版本也是由后端生成的）来明确确认对此 Surface 的修改。此机制的目的是在发布周期中尽早检测并防止对 IDK 的意外更改，并为我们提供工具来观察和审核 API 接口的演变。

前端

“前端”一词用于描述提取 Fuchsia IDK 归档文件并对其应用转换的任何进程。

在 Fuchsia 树中，前端用于生成 SDK 发行版，例如可使用 Bazel 的工作区。

前端还可用于调整 Fuchsia IDK 归档以便在特定开发环境中使用，例如为给定构建系统生成 build 文件。归档文件本身包含丰富的元数据，因此可以进行此类处理。

IDK 和 IDK 插件

Core IDK 由 //sdk:core 目标表示。该 IDK 还配有多个 IDK 插件：

  • //sdk:e2e_testing：适用于 Fuchsia 的端到端测试框架；
  • //sdk:fuchsia_dart：用于构建模组和代理的 Dart SDK。

在内部，这些目标都是 sdk GN 模板的实例。

食谱

生成 IDK 归档文件

代表 IDK 的各种目标始终包含在 build 图中。如需构建 IDK 的内容，请构建上述任一目标。

请注意，这将生成并验证 IDK 内容，但实际上不会使用这些内容构建归档文件。

如需构建归档文件，请运行以下命令：

fx set minimal.x64
fx build sdk:final_fuchsia_idk

生成的归档文件将位于 <outdir>/sdk/archive/fuchsia_idk.tar.gz 下。

IDK 包含 Fuchsia 开发所需的主机工具。默认情况下，在本地构建 IDK 时，它仅包含适用于当前主机架构（x64 或 arm64）的主机工具。在 x64 主机上构建 IDK 时，您还可以通过设置以下内容来添加 arm64 主机工具：

fx set minimal.x64 --args=sdk_cross_compile_host_tools=true

向 IDK 添加内容

第一步是将相应内容提供给 SDK。为此，请使用后端文档中列出的一组模板。下一步是将这些内容添加到现有的 IDK 定义。对于目标 //path/to/my:super_target，可通过将隐式 //path/to/my:super_target_sdk 目标设为 sdk 目标的依赖项来实现此目的。

请注意，某些内容类型需要 .api 源文件来描述 IDK 元素的 API 状态。这些文件由构建系统生成。为了为此类文件的第一个版本提供种子，请让构建系统告诉您它预计在哪里找到该文件，然后创建此文件并将其留空，最后再次运行构建：它将再次告诉您从哪里获取初始版本。

有一些 build 步骤可用于验证 IDK 的内容不会意外修改。未确认的修改会导致构建失败，直到源代码树中的相关参考文件更新为止。在本地迭代某些公共 API 时，如果必须反复更新引用文件，可能会很繁琐。如需将构建错误转换为警告，请使用以下额外的 GN 参数进行配置和构建：warn_no_sdk_changes=true。