声明 aconfig 标志

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

为 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 定义了作为二进制文件一起构建和分发的代码集合。有效容器包括 system、vendor、system_ext、product、name.of.apex 和 name.of.apk。

   • name 包含标志名称，其中仅包含小写字母、下划线和数字。

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

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

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

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

设置 build

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

1. 在 Android.bp build 文件中，添加一个 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 定义了作为二进制文件一起构建和分发的代码集合。有效容器包括 system、vendor、system_ext、product、name.of.apex 和 name.of.apk。

   • name 包含标志名称，其中仅包含小写字母、下划线和数字。

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

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

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

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

设置 build

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

1. 在 Android.bp build 文件中，添加一个 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 build 目标会调用 C 或 C++ Codegen，后者会在构建时使用生成的代码创建库。

   CC aconfig 库与 CC 库目标类似，但具有 vendor_available、product_available、host_supported 和 vndk 等选项。如果依赖于此 cc_aconfig_library 的 build 目标需要特定类型的变体，您可能还需要在 CC aconfig 库目标中添加相应的设置。例如，如果父 build 目标将 vendor_available 设置为 true，您可能还需要在此 cc_aconfig_library 目标中将 vendor_available 设置为 true。

   添加此 build 目标后，您的代码便可访问此库。您可以使用 static_lib 或 shared_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 是 build 按照第 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 定义了作为二进制文件一起构建和分发的代码集合。有效容器包括 system、vendor、system_ext、product、name.of.apex 和 name.of.apk。

   • name 包含标志名称，其中仅包含小写字母、下划线和数字。

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

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

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

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

设置 build

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

1. 在 Android.bp build 文件中，添加一个类似于以下内容的 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 Codegen，并在构建时使用生成的代码创建 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",
     ]
   }
   

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

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