Déclarer un indicateur aconfig

Vous pouvez utiliser des options aconfig dans du code Java, C, C++ et Rust. Le système de compilation AOSP lance un outil appelé aconfig, qui permet de générer une bibliothèque de méthodes spécifiques à un langage que vous pouvez utiliser pour accéder à la valeur de chaque option. Avant de pouvoir générer la bibliothèque, vous devez déclarer des options et les ajouter à la compilation.

Déclarer une option aconfig pour Java

Pour déclarer une option aconfig pour Java :

  1. Dans un répertoire où le nouveau code existe, créez un fichier avec l'extension .aconfig, par exemple my_new_aconfig_flag_declarations.aconfig. Un fichier aconfig est un fichier proto texte qui suit un schéma standard.

  2. Ajoutez une déclaration d'option semblable à la suivante :

    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>"
}

    Où :

    • package, combiné au nom de l'option, fournit une clé unique. En Java, la définition de package sur foo.bar génère automatiquement une classe nommée foo.bar.Flags. En C++, les méthodes d'accès aux options seraient nommées foo::bar::"flagname". Les options du même fichier de déclaration appartiennent au même package, mais plusieurs fichiers de déclaration peuvent contribuer à un même package.

    • container définit une collection de code qui est compilée et distribuée ensemble sous forme de binaire. Les conteneurs valides sont system, vendor, system_ext, product, name.of.apex, et name.of.apk.

    • name contient le nom de l'option, qui ne contient que des lettres minuscules, des traits de soulignement et des chiffres.

    • namespace contient l'espace de noms pour les contributions. Vous devez collaborer avec le réviseur Google attribué pour déterminer votre espace de noms. Si vous utilisez des options de lancement de fonctionnalités pour maintenir la stabilité de votre propre miroir AOSP, vous pouvez utiliser l'espace de noms comme vous le souhaitez.

    • description contient une brève description de la fonctionnalité ou de la modification signalée.

    • bug est le numéro de bug associé à la nouvelle contribution de code. Vous devez collaborer avec le réviseur Google attribué pour déterminer votre bug. Si vous utilisez des options de lancement de fonctionnalités pour maintenir la stabilité de votre propre miroir AOSP, vous pouvez utiliser votre numéro de suivi des bugs ou utiliser <none>.

  3. Enregistrez le fichier et quittez l'éditeur.

Configurer la compilation

Une fois que vous avez déclaré votre option, configurez la compilation afin qu'elle puisse générer le code de la bibliothèque utilisé pour accéder à la valeur de l'option.

  1. Dans votre fichier de compilation Android.bp, ajoutez une section aconfig_declarations semblable à la suivante :

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

    Où :

    • name contient le nom de la déclaration, qui ne contient que des lettres minuscules, des traits de soulignement et des chiffres.
    • package contient le même nom de package que celui utilisé dans la déclaration.
    • srcs contient le nom du fichier .aconfig dans lequel l'option est déclarée.

  2. Enregistrez le fichier et quittez l'éditeur.

Déclarer une option aconfig pour C et C++

Pour déclarer une option aconfig pour C et C++ :

  1. Dans un répertoire où le nouveau code existe, créez un fichier avec l'extension .aconfig, par exemple my_new_aconfig_flag_declarations.aconfig. Un fichier aconfig est un fichier proto texte qui suit un schéma standard.

  2. Ajoutez une déclaration d'option semblable à la suivante :

    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>"
}

    Où :

    • package, combiné au nom de l'option, fournit une clé unique. En Java, la définition de package sur foo.bar génère automatiquement une classe nommée foo.bar.Flags. En C++, les méthodes d'accès aux options seraient nommées foo::bar::"flagname". Les options du même fichier de déclaration appartiennent au même package, mais plusieurs fichiers de déclaration peuvent contribuer à un même package.

    • container définit une collection de code qui est compilée et distribuée ensemble sous forme de binaire. Les conteneurs valides sont system, vendor, system_ext, product, name.of.apex, et name.of.apk.

    • name contient le nom de l'option, qui ne contient que des lettres minuscules, des traits de soulignement et des chiffres.

    • namespace contient l'espace de noms pour les contributions. Vous devez collaborer avec le réviseur Google attribué pour déterminer votre espace de noms. Si vous utilisez des options de lancement de fonctionnalités pour maintenir la stabilité de votre propre miroir AOSP, vous pouvez utiliser l'espace de noms comme vous le souhaitez.

    • description contient une brève description de la fonctionnalité ou de la modification signalée.

    • bug est le numéro de bug associé à la nouvelle contribution de code. Vous devez collaborer avec le réviseur Google attribué pour déterminer votre bug. Si vous utilisez des options de lancement de fonctionnalités pour maintenir la stabilité de votre propre miroir AOSP, vous pouvez utiliser votre numéro de suivi des bugs ou utiliser <none>.

  3. Enregistrez le fichier et quittez l'éditeur.

Configurer la compilation

Une fois que vous avez déclaré votre option, configurez la compilation afin qu'elle puisse générer le code de la bibliothèque utilisé pour accéder à la valeur de l'option.

  1. Dans votre fichier de compilation Android.bp, ajoutez une section aconfig_declarations semblable à la suivante :

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

    Où :

    • name contient le nom de la déclaration, qui ne contient que des lettres minuscules, des traits de soulignement et des chiffres.
    • package contient le même nom de package que celui utilisé dans la déclaration.
    • srcs contient le nom du fichier aconfig dans lequel l'option est déclarée.

  2. Dans le même fichier, créez une cible cc_aconfig_library semblable à la suivante :

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

    Où :

    • name contient le nom de la bibliothèque, qui ne contient que des lettres minuscules, des traits de soulignement et des chiffres.
    • aconfig_declarations contient le même name que celui utilisé dans la déclaration.

    La cible de compilation cc_aconfig_library appelle C ou C++ Codegen, qui crée une bibliothèque avec le code généré au moment de la compilation.

    La bibliothèque aconfig CC est semblable à une cible de bibliothèque CC, mais comporte des options telles que vendor_available, product_available, host_supported et vndk. Si la cible de compilation qui dépend de cette cc_aconfig_library nécessite un certain type de variantes, vous devrez peut-être également ajouter le paramètre correspondant dans la cible de la bibliothèque aconfig CC. Par exemple, si la cible de compilation parente a la valeur vendor_available définie sur true, vous pouvez également définir vendor_available sur true dans cette cible cc_aconfig_library.

    Une fois cette cible de compilation ajoutée, votre code peut accéder à cette bibliothèque. Vous pouvez inclure cette bibliothèque à l'aide de la syntaxe static_lib ou shared_lib. Notez que si vous souhaitez ajouter cette bibliothèque en tant que static_lib, ajoutez une dépendance shared_lib sur server_configurable_flags. L'étape 3 montre comment inclure la bibliothèque d'options générée par le code dans libexample_cpp_lib.

  3. Créez une cible qui utilise les options aconfig, comme l'exemple cc_library suivant :

    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"],
}

    Où :

    • shared_libs inclut les dépendances supplémentaires requises pour les options aconfig.
    • static_libs est le nom de la bibliothèque créée par la compilation conformément au champ name de cc_aconfig_library à l'étape 2. En créant une entrée cc_library avec le nom de la bibliothèque statique, vous pouvez désormais utiliser les options aconfig dans votre code.

Déclarer une option aconfig pour Rust

Pour déclarer une option aconfig pour Rust :

  1. Dans un répertoire où le nouveau code existe, créez un fichier avec l'extension .aconfig, par exemple my_new_aconfig_flag_declarations.aconfig. Un fichier aconfig est un fichier proto texte qui suit un schéma standard.

  2. Ajoutez une déclaration d'option semblable à la suivante :

    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>"
}

    Où :

    • package, combiné au nom de l'option, fournit une clé unique. En Java, la définition de package sur foo.bar génère automatiquement une classe nommée foo.bar.Flags. En C++, les méthodes d'accès aux options seraient nommées foo::bar::"flagname". Les options du même fichier de déclaration appartiennent au même package, mais plusieurs fichiers de déclaration peuvent contribuer à un même package.

    • container définit une collection de code qui est compilée et distribuée ensemble sous forme de binaire. Les conteneurs valides sont system, vendor, system_ext, product, name.of.apex, et name.of.apk.

    • name contient le nom de l'option, qui ne contient que des lettres minuscules, des traits de soulignement et des chiffres.

    • namespace contient l'espace de noms pour les contributions. Vous devez collaborer avec le réviseur Google attribué pour déterminer votre espace de noms. Si vous utilisez des options de lancement de fonctionnalités pour maintenir la stabilité de votre propre miroir AOSP, vous pouvez utiliser l'espace de noms comme vous le souhaitez.

    • description contient une brève description de la fonctionnalité ou de la modification signalée.

    • bug est le numéro de bug associé à la nouvelle contribution de code. Vous devez collaborer avec le réviseur Google attribué pour déterminer votre bug. Si vous utilisez des options de lancement de fonctionnalités pour maintenir la stabilité de votre propre miroir AOSP, vous pouvez utiliser votre numéro de suivi des bugs ou utiliser <none>.

  3. Enregistrez le fichier et quittez l'éditeur.

Configurer la compilation

Une fois que vous avez déclaré votre option, configurez la compilation afin qu'elle puisse générer le code de la bibliothèque utilisé pour accéder à la valeur de l'option.

  1. Dans votre fichier de compilation Android.bp, ajoutez une section aconfig_declarations semblable à la suivante :

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

    Où :

    • name contient le nom de la déclaration, qui ne contient que des lettres minuscules, des traits de soulignement et des chiffres.
    • package contient le même nom de package que celui utilisé dans la déclaration.
    • srcs contient le nom du fichier aconfig dans lequel l'option est déclarée.

  2. Créez une cible rust_aconfig_library semblable à l'exemple suivant. Cette cible appelle Rust Codegen et crée une bibliothèque Rust avec le code généré au moment de la compilation.

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

    Où :

    • name contient le nom de la déclaration, qui ne contient que des lettres minuscules, des traits de soulignement et des chiffres.
    • crate_name contient le même nom de package que celui utilisé dans la déclaration.
    • aconfig_declarations contient le même name que celui utilisé dans la déclaration.

    Avec cette modification, votre code peut dépendre de cette bibliothèque Rust.

  3. Dans le même fichier, créez une entrée rust_library semblable à la suivante :

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

    Cet exemple permet à vos cibles de compilation de code source libexample_demo_flags_rust d'inclure la bibliothèque d'options générée par le code.

  4. Enregistrez le fichier et quittez l'éditeur.