宣告 aconfig 旗標

您可以在 Java、C、C++ 和 Rust 程式碼中使用設定旗標。AOSP 建構系統會啟動名為 aconfig 的工具，用於產生可用來存取每個標記值的語言專屬方法程式庫。產生前的準備作業 程式庫，您必須宣告標記並將其新增至建構作業。

宣告 Java 的 aconfig 標記

如要宣告 Java 的設定標記：

  1. 在現有程式碼所在的目錄中建立具有副檔名的檔案 .aconfig，例如 my_new_aconfig_flag_declarations.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 是與新程式碼貢獻相關的錯誤編號。您必須與指派的 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 檔案是遵循標準結構定義的文字檔案。

  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 是與新程式碼貢獻相關的錯誤編號。您必須與指派的 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已設為 true，建議您一併設定 此cc_aconfig_library目標中的vendor_available到 true。

    新增此建構目標後，您的程式碼便可存取這個程式庫。您可以使用 static_lib 或 shared_lib 語法納入這個程式庫。請注意，如果您想將這個程式庫新增為 static_lib，請在 server_configurable_flags 上新增 shared_lib 依附元件。步驟 3 說明如何將程式碼產生的旗標程式庫 libexample_cpp_lib。

  3. 建立使用設定旗標的目標，如下列範例所示 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 包含設定標記所需的額外依附元件。
    • static_libs 是根據步驟 2 中的 cc_aconfig_library name 欄位所建立的程式庫名稱。您現在可以使用靜態資料庫名稱建立 cc_library 項目，在程式碼中使用 aconfig 標記。

宣告 Rust 的設定旗標

如要為 Rust 宣告 aconfig 標記，請按照下列步驟操作：

  1. 在含有新程式碼的目錄中，建立擴充功能為 .aconfig 的檔案，例如 my_new_aconfig_flag_declarations.aconfig。aconfig 檔案是遵循標準結構定義的文字檔案。

  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 是與新程式碼貢獻相關的錯誤編號。您必須與指派的 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 目標。這個 target 叫用 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. 儲存檔案並關閉編輯器。