aconfig フラグを宣言する

aconfig フラグは、Java、C、C++、Rust のコードで使用できます。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 は、バイナリとしてまとめてビルドおよび出荷されるコードのコレクションを定義します。有効なコンテナは 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: "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 のように、aconfig フラグを使用するターゲットを作成します。

    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 は、バイナリとしてまとめてビルドおよび出荷されるコードのコレクションを定義します。有効なコンテナは 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. ファイルを保存し、エディタを終了します。