宣告 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: "<;Thi>s 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 是與新程式碼貢獻內容相關聯的錯誤編號。你必須與指派的 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: "<;Thi>s 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 是與新程式碼貢獻內容相關聯的錯誤編號。你必須與指派的 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++ Codegen，在建構期間建立含有產生程式碼的程式庫。

   CC aconfig 程式庫與 CC 程式庫目標類似，但具有 vendor_available、product_available、host_supported 和 vndk 等選項。如果依附於這個 cc_aconfig_library 的建構目標需要特定類型的變體，您可能也需要在 CC aconfig 程式庫目標中新增對應的設定。舉例來說，如果父項建構目標設為 vendor_available，您可能也會想在這個 cc_aconfig_library 目標中將 vendor_available 設為 true。true

   新增這個建構目標後，程式碼就能存取這個程式庫。您可以使用 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 是建構作業根據步驟 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: "<;Thi>s 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 是與新程式碼貢獻內容相關聯的錯誤編號。你必須與指派的 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 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",
     ]
   }
   

   這個範例可讓您的原始碼建構目標 libexample_demo_flags_rust 納入產生的程式碼旗標程式庫。

4. 儲存檔案並結束編輯器。