将系统属性作为 API 实现

系统属性是在系统范围内共享信息（通常是配置）的一种便捷方式。每个分区都可以在内部使用自己的系统属性。跨分区访问属性（例如，/vendor 访问 /system 定义的属性）时，可能会出现问题。从 Android 8.0 开始，可以升级某些分区（如 /system），而 /vendor 保持不变。由于系统属性只是不具有架构的字符串键值对的全局字典，因此很难稳定属性。/system 分区可以更改或移除 /vendor 分区所依赖的属性，而不会另行通知。

从 Android 10 版本开始，跨分区访问的系统属性已架构化为 Sysprop 说明文件，并且用于访问属性的 API 会生成为 C++ 和 Rust 的具体函数及 Java 类。这些 API 使用起来更方便，因为访问时不需要魔法字符串（如 ro.build.date），而且它们可以是静态类型的。在构建时也会检查 ABI 稳定性；如果发生不兼容的更改，build 会中断。此检查充当各个分区之间明确定义的接口。这些 API 还可以在 Rust、Java 和 C ++ 之间实现一致性。

将系统属性定义为 API

您可以使用 Sysprop 说明文件 (.sysprop) 将系统属性定义为 API，该文件使用 protobuf 的 TextFormat，其架构如下：

// File: sysprop.proto

syntax = "proto3";

package sysprop;

enum Access {
  Readonly = 0;
  Writeonce = 1;
  ReadWrite = 2;
}

enum Owner {
  Platform = 0;
  Vendor = 1;
  Odm = 2;
}

enum Scope {
  Public = 0;
  Internal = 2;
}

enum Type {
  Boolean = 0;
  Integer = 1;
  Long = 2;
  Double = 3;
  String = 4;
  Enum = 5;
  UInt = 6;
  ULong = 7;

  BooleanList = 20;
  IntegerList = 21;
  LongList = 22;
  DoubleList = 23;
  StringList = 24;
  EnumList = 25;
  UIntList = 26;
  ULongList = 27;
}

message Property {
  string api_name = 1;
  Type type = 2;
  Access access = 3;
  Scope scope = 4;
  string prop_name = 5;
  string enum_values = 6;
  bool integer_as_bool = 7;
  string legacy_prop_name = 8;
}

message Properties {
  Owner owner = 1;
  string module = 2;
  repeated Property prop = 3;
}

一个 Sysprop 说明文件包含一条属性消息，用来描述一组属性。其字段的含义如下。

字段	含义
`owner`	设为拥有以下属性的分区：`Platform`、`Vendor` 或 `Odm`。
`module`	用于创建放置生成的 API 的命名空间 (C++) 或静态最终类 (Java)。例如，`com.android.sysprop.BuildProperties` 将是 C++ 中的命名空间 `com::android::sysprop::BuildProperties`，并且也是 Java 中 `com.android.sysprop` 中的软件包中的 `BuildProperties` 类。
`prop`	属性列表。

Property 消息字段的含义如下。

字段	含义
`api_name`	生成的 API 的名称。
`type`	此属性的类型。
`access`	`Readonly`：仅生成 getter API `Writeonce`、`ReadWrite`：生成 getter 和 setter API 注意：前缀为 `ro.` 的属性可能无法使用 `ReadWrite` 访问权限。
`scope`	`Internal`：只有所有者可以访问。 `Public`：所有人都可以访问，但 NDK 模块除外。
`prop_name`	底层系统属性的名称，例如 `ro.build.date`。
`enum_values`	（仅 `Enum` 和 `EnumList`）一个竖条 (\|) 分隔的字符串，由可能的枚举值组成。例如，`value1\|value2`。
`integer_as_bool`	（仅限 `Boolean`、`BooleanList`）让 setter 使用 `0` 和 `1`，而不是 `false` 和 `true`。
`legacy_prop_name`	（可选，仅限 `Readonly` 属性）底层系统属性的旧名称。调用 getter 时，如果 `prop_name` 不存在，getter API 会尝试读取 `prop_name` 并使用 `legacy_prop_name`。在弃用现有属性并迁移到新属性时，请使用 `legacy_prop_name`。

每种类型的属性都会映射到 C++、Java 和 Rust 中的以下类型。

类型	C++	Java	Rust
布尔值	`std::optional<bool>`	`Optional<Boolean>`	`bool`
整数	`std::optional<std::int32_t>`	`Optional<Integer>`	`i32`
UInt	`std::optional<std::uint32_t>`	`Optional<Integer>`	`u32`
Long	`std::optional<std::int64_t>`	`Optional<Long>`	`i64`
ULong	`std::optional<std::uint64_t>`	`Optional<Long>`	`u64`
Double	`std::optional<double>`	`Optional<Double>`	`f64`
String	`std::optional<std::string>`	`Optional<String>`	`String`
Enum	`std::optional<{api_name}_values>`	`Optional<{api_name}_values>`	`{ApiName}Values`
T List	`std::vector<std::optional<T>>`	`List<T>`	`Vec<T>`

下面的示例展示了定义三个属性的 Sysprop 说明文件：

# File: android/sysprop/PlatformProperties.sysprop

owner: Platform
module: "android.sysprop.PlatformProperties"
prop {
    api_name: "build_date"
    type: String
    prop_name: "ro.build.date"
    scope: Public
    access: Readonly
}
prop {
    api_name: "date_utc"
    type: Integer
    prop_name: "ro.build.date_utc"
    scope: Internal
    access: Readonly
}
prop {
    api_name: "device_status"
    type: Enum
    enum_values: "on|off|unknown"
    prop_name: "device.status"
    scope: Public
    access: ReadWrite
}

定义系统属性库

您现在可以使用 Sysprop 说明文件定义 sysprop_library 模块。 sysprop_library 用作 C++、Java 和 Rust 的 API。对于 sysprop_library 的每个实例，构建系统会在内部生成一个 rust_library、一个 java_library 和一个 cc_library。

// File: Android.bp
sysprop_library {
    name: "PlatformProperties",
    srcs: ["android/sysprop/PlatformProperties.sysprop"],
    property_owner: "Platform",
    vendor_available: true,
}

您必须在源代码中包含 API 列表文件以进行 API 检查。为此，请创建 API 文件和一个 api 目录。将 api 目录放在与 Android.bp 相同的目录中。API 文件名包括 <module_name>-current.txt 和 <module_name>-latest.txt。<module_name>-current.txt 保留当前源代码的 API 签名，而 <module_name>-latest.txt 保留最新的冻结 API 签名。构建系统通过在构建时比较这些 API 文件和生成的 API 文件来检查 API 是否已更改，并在 current.txt 与源代码不匹配时发出错误消息和更新 current.txt 文件的说明。下面是一个目录和文件组织示例：

├── api
│   ├── PlatformProperties-current.txt
│   └── PlatformProperties-latest.txt
└── Android.bp

Rust、Java 和 C++ 客户端模块都可以关联到 sysprop_library 以使用生成的 API。构建系统会创建从客户端到生成的 C++、Java 和 Rust 库的关联，从而使客户端能够访问生成的 API。

java_library {
    name: "JavaClient",
    srcs: ["foo/bar.java"],
    libs: ["PlatformProperties"],
}

cc_binary {
    name: "cc_client",
    srcs: ["baz.cpp"],
    shared_libs: ["PlatformProperties"],
}

rust_binary {
    name: "rust_client",
    srcs: ["src/main.rs"],
    rustlibs: ["libplatformproperties_rust"],
}

请注意，系统会通过以下方式生成 Rust 库名称：将 sysprop_library 名称转换为小写形式，将 . 和 - 替换为 _，然后附加 lib 和附加 _rust。

在前面的示例中，您可以按如下方式访问定义的属性。

Rust 示例：

use platformproperties::DeviceStatusValues;

fn foo() -> Result<(), Error> {
  // Read "ro.build.date_utc". default value is -1.
  let date_utc = platformproperties::date_utc()?.unwrap_or_else(-1);

  // set "device.status" to "unknown" if "ro.build.date" is not set.
  if platformproperties::build_date()?.is_none() {
    platformproperties::set_device_status(DeviceStatusValues::UNKNOWN);
  }

  …
}

Java 示例：

import android.sysprop.PlatformProperties;

…

static void foo() {
    …
    // read "ro.build.date_utc". default value is -1
    Integer dateUtc = PlatformProperties.date_utc().orElse(-1);

    // set "device.status" to "unknown" if "ro.build.date" is not set
    if (!PlatformProperties.build_date().isPresent()) {
        PlatformProperties.device_status(
            PlatformProperties.device_status_values.UNKNOWN
        );
    }
    …
}
…

C++ 示例：

#include <android/sysprop/PlatformProperties.sysprop.h>
using namespace android::sysprop;

…

void bar() {
    …
    // read "ro.build.date". default value is "(unknown)"
    std::string build_date = PlatformProperties::build_date().value_or("(unknown)");

    // set "device.status" to "on" if it's "unknown" or not set
    using PlatformProperties::device_status_values;
    auto status = PlatformProperties::device_status();
    if (!status.has_value() || status.value() == device_status_values::UNKNOWN) {
        PlatformProperties::device_status(device_status_values::ON);
    }
    …
}
…