声明 aconfig 标志

您可以在 Java、C、C++ 和 Rust 代码中使用 aconfig 标志。AOSP 构建系统启动一个名为 aconfig 的工具,该工具用于生成特定于语言的方法库,您可以使用这些方法来访问每个标志的值。在生成库之前,您必须声明标志并将其添加到构建中。

为 Java 声明 aconfig 标志

要为 Java 声明 aconfig 标志,请执行以下操作:

  1. 在新代码所在的目录中,创建一个扩展名为 .aconfig 的文件,例如 my_new_aconfig_flag_declarations.aconfig。aconfig 文件是遵循标准架构的文本 proto 文件。

  2. 添加类似于以下内容的标志声明:

    package: "com.example.android.aconfig.demo.flags"
    container: "system"
    
    flag {
        name: "my_new_flag"
        namespace: "aconfig_demo_namespace"
        description: "This flag controls untested code"
        bug: "<none>"
    }
    

    其中:

    • package 与标志名称结合使用时,会提供唯一的键。在 Java 中,将 package 设置为 foo.bar 会生成一个名为 foo.bar.Flags 的自动生成的类。在 C++ 中,标志访问器方法将命名为 foo::bar::"flagname"。同一声明文件中的标志属于同一软件包,但多个声明文件可以为同一软件包贡献标志。
    • container 定义了一组代码,这些代码被构建并一起作为二进制文件交付。有效的容器包括 systemvendorsystem_extproductname.of.apexname.of.apk

    • name 包含标志的名称,该名称仅包含小写字母、下划线和数字。

    • namespace 包含贡献的命名空间。您必须与指定的 Google 审核人员合作来确定您的命名空间。如果您使用功能启动标志来维护您自己的 AOSP 镜像的稳定性,则可以随意使用命名空间。

    • description 包含对已标记的功能或更改的简要说明。

    • bug 是与新代码贡献关联的 bug 编号。您必须与指定的 Google 审核人员合作来确定您的 bug。如果您使用功能启动标志来维护您自己的 AOSP 镜像的稳定性,则可以使用您的错误跟踪编号或使用 <none>

  3. 保存文件并退出编辑器。

设置构建

声明标志后,请设置构建,以便它可以生成用于访问标志值的库代码。

  1. 在您的 Android.bp 构建文件中,添加类似于以下内容的 aconfig_declarations 部分:

    aconfig_declarations {
      name: "aconfig_demo_flags",
      package: "com.example.android.aconfig.demo.flags",
      srcs: [
        "my_new_aconfig_flag_declarations.aconfig"
      ],
    }
    

    其中:

    • name 包含声明的名称,该名称仅包含小写字母、下划线和数字。
    • package 包含声明中使用的相同软件包名称。
    • srcs 包含声明标志的 .aconfig 文件的名称。
  2. 保存文件并退出编辑器。

为 C 和 C++ 声明 aconfig 标志

要为 C 和 C++ 声明 aconfig 标志,请执行以下操作:

  1. 在新代码所在的目录中,创建一个扩展名为 .aconfig 的文件,例如 my_new_aconfig_flag_declarations.aconfig。aconfig 文件是遵循标准架构的文本 proto 文件。

  2. 添加类似于以下内容的标志声明:

    package: "com.example.android.aconfig.demo.flags"
    container: "system"
    
    flag {
        name: "my_new_flag"
        namespace: "aconfig_demo_namespace"
        description: "This flag controls untested code"
        bug: "<none>"
    }
    

    其中:

    • package 与标志名称结合使用时,会提供唯一的键。在 Java 中,将 package 设置为 foo.bar 会生成一个名为 foo.bar.Flags 的自动生成的类。在 C++ 中,标志访问器方法将命名为 foo::bar::"flagname"。同一声明文件中的标志属于同一软件包,但多个声明文件可以为同一软件包贡献标志。
    • container 定义了一组代码,这些代码被构建并一起作为二进制文件交付。有效的容器包括 systemvendorsystem_extproductname.of.apexname.of.apk

    • name 包含标志的名称,该名称仅包含小写字母、下划线和数字。

    • namespace 包含贡献的命名空间。您必须与指定的 Google 审核人员合作来确定您的命名空间。如果您使用功能启动标志来维护您自己的 AOSP 镜像的稳定性,则可以随意使用命名空间。

    • description 包含对已标记的功能或更改的简要说明。

    • bug 是与新代码贡献关联的 bug 编号。您必须与指定的 Google 审核人员合作来确定您的 bug。如果您使用功能启动标志来维护您自己的 AOSP 镜像的稳定性,则可以使用您的错误跟踪编号或使用 <none>

  3. 保存文件并退出编辑器。

设置构建

声明标志后,请设置构建,以便它可以生成用于访问标志值的库代码。

  1. 在您的 Android.bp 构建文件中,添加类似于以下内容的 aconfig_declarations 部分:

    aconfig_declarations {
      name: "aconfig_demo_flags",
      package: "com.example.android.aconfig.demo.flags",
      srcs: [
        "my_new_aconfig_flag_declarations.aconfig"
      ],
    }
    

    其中:

    • name 包含声明的名称,该名称仅包含小写字母、下划线和数字。
    • package 包含声明中使用的相同软件包名称。
    • srcs 包含声明标志的 aconfig 文件的名称。
  2. 在同一文件中,创建一个类似于以下内容的 cc_aconfig_library 目标:

    cc_aconfig_library {
        name: "aconfig_demo_flags_c_lib",
        aconfig_declarations: "aconfig_demo_flags",
    }
    

    其中:

    • name 包含库的名称,该名称仅包含小写字母、下划线和数字。
    • aconfig_declarations 包含声明中使用的相同 name

    cc_aconfig_library 构建目标会调用 C 或 C++ 代码生成,这会在构建时创建一个包含生成的代码的库。

    CC aconfig 库类似于 CC 库目标,但具有诸如 vendor_availableproduct_availablehost_supportedvndk 之类的选项。如果依赖于此 cc_aconfig_library 的构建目标需要特定类型的变体,您可能还需要在此 CC aconfig 库目标中添加相应的设置。例如,如果父构建目标的 vendor_available 设置为 true,您可能还希望在此 cc_aconfig_library 目标中将 vendor_available 设置为 true

    添加此构建目标后,您的代码可以访问此库。您可以使用 static_libshared_lib 语法包含此库。请注意,如果您想将此库添加为 static_lib,请在 server_configurable_flags 上添加 shared_lib 依赖项。步骤 3 展示了如何将生成的代码标志库包含到 libexample_cpp_lib 中。

  3. 创建一个使用 aconfig 标志的目标,例如以下示例 cc_library

    cc_library {
        name: "libexample_cpp_lib",
        srcs: ["src/example_cpp_lib.cc"],
        double_loadable: true,
        cflags: [
            "-Wall",
            "-Werror",
            "-Wno-unused-function",
            "-Wno-unused-parameter",
        ],
        header_libs: [
            "jni_headers",
        ],
        shared_libs: [
            "server_configurable_flags",
        ],
        static_libs: [
            "aconfig_demo_flags_c_lib",
        ],
        export_include_dirs: ["src/include"],
    }
    

    其中:

    • shared_libs 包括 aconfig 标志所需的额外依赖项。
    • static_libs 是库的名称,该库由构建根据步骤 2 中的 cc_aconfig_library name 字段创建。通过使用静态库名称创建 cc_library 条目,您现在可以在代码中使用 aconfig 标志。

为 Rust 声明 aconfig 标志

要为 Rust 声明 aconfig 标志,请执行以下操作:

  1. 在新代码所在的目录中,创建一个扩展名为 .aconfig 的文件,例如 my_new_aconfig_flag_declarations.aconfig。aconfig 文件是遵循标准架构的文本 proto 文件。

  2. 添加类似于以下内容的标志声明:

    package: "com.example.android.aconfig.demo.flags"
    container: "system"
    
    flag {
        name: "my_new_flag"
        namespace: "aconfig_demo_namespace"
        description: "This flag controls untested code"
        bug: "<none>"
    }
    

    其中:

    • package 与标志名称结合使用时,会提供唯一的键。在 Java 中,将 package 设置为 foo.bar 会生成一个名为 foo.bar.Flags 的自动生成的类。在 C++ 中,标志访问器方法将命名为 foo::bar::"flagname"。同一声明文件中的标志属于同一软件包,但多个声明文件可以为同一软件包贡献标志。
    • container 定义了一组代码,这些代码被构建并一起作为二进制文件交付。有效的容器包括 systemvendorsystem_extproductname.of.apexname.of.apk

    • name 包含标志的名称,该名称仅包含小写字母、下划线和数字。

    • namespace 包含贡献的命名空间。您必须与指定的 Google 审核人员合作来确定您的命名空间。如果您使用功能启动标志来维护您自己的 AOSP 镜像的稳定性,则可以随意使用命名空间。

    • description 包含对已标记的功能或更改的简要说明。

    • bug 是与新代码贡献关联的 bug 编号。您必须与指定的 Google 审核人员合作来确定您的 bug。如果您使用功能启动标志来维护您自己的 AOSP 镜像的稳定性,则可以使用您的错误跟踪编号或使用 <none>

  3. 保存文件并退出编辑器。

设置构建

声明标志后,请设置构建,以便它可以生成用于访问标志值的库代码。

  1. 在您的 Android.bp 构建文件中,添加类似于以下内容的 aconfig_declarations 部分:

    aconfig_declarations {
      name: "aconfig_demo_flags",
      package: "com.example.android.aconfig.demo.flags",
      srcs: [
        "my_new_aconfig_flag_declarations.aconfig"
      ],
    }
    

    其中:

    • name 包含声明的名称,该名称仅包含小写字母、下划线和数字。
    • package 包含声明中使用的相同软件包名称。
    • srcs 包含声明标志的 aconfig 文件的名称。
  2. 创建一个类似于以下示例的 rust_aconfig_library 目标。此目标调用 Rust 代码生成,并在构建时创建一个包含生成的代码的 Rust 库。

    rust_aconfig_library {
      name: "libaconfig_demo_flags_rust",
      crate_name: "aconfig_demo_flags_rust",
      aconfig_declarations: "aconfig_demo_flags",
    }
    

    其中:

    • name 包含声明的名称,该名称仅包含小写字母、下划线和数字。
    • crate_name 包含声明中使用的相同软件包名称。
    • aconfig_declarations 包含声明中使用的相同 name

    通过此更改,您的代码可以依赖于此 Rust 库。

  3. 在同一文件中,创建一个类似于以下内容的 rust_library 条目:

    rust_library {
      name: "libexample_lib",
      rustlibs: [
          "libaconfig_demo_flags_rust",
      ]
    }
    

    此示例允许您的源代码构建目标 libexample_demo_flags_rust 包含生成的代码标志库。

  4. 保存文件并退出编辑器。