Déclarer un indicateur aconfig

Vous pouvez utiliser des indicateurs 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 à une langue que vous pouvez utiliser pour accéder à la valeur de chaque indicateur. Avant de pouvoir générer la bibliothèque, vous devez déclarer des indicateurs et les ajouter à la compilation.

Déclarer un flag aconfig pour Java

Pour déclarer un indicateur aconfig pour Java :

1. Dans un répertoire où se trouve le nouveau code, 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 du flag, fournit une clé unique. En Java, définir package sur foo.bar génère automatiquement une classe nommée foo.bar.Flags. En C++, les méthodes d'accesseur d'indicateur seraient nommées foo::bar::"flagname". Les indicateurs d'un même fichier de déclaration appartiennent au même package, mais plusieurs fichiers de déclaration peuvent contribuer aux indicateurs d'un même package.

   • container définit un ensemble de code qui est compilé et distribué 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 du flag, qui ne doit comporter que des lettres minuscules, des traits de soulignement et des chiffres.

   • namespace contient l'espace de noms pour les contributions. Vous devez collaborer avec l'examinateur Google qui vous a été attribué pour déterminer votre espace de noms. Si vous utilisez des indicateurs de lancement de fonctionnalité 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 correspond au numéro du bug associé à la nouvelle contribution de code. Vous devez collaborer avec l'examinateur Google qui vous a été attribué pour déterminer votre bug. Si vous utilisez des indicateurs de lancement de fonctionnalité pour maintenir la stabilité de votre propre miroir AOSP, vous pouvez utiliser votre numéro de suivi des bugs ou <none>.

   Remarque : L'utilisation d'options dans les APK qui ne sont pas créés avec une partition APEX ou système n'est pas acceptée.

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

Configurer la compilation

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

1. Dans votre fichier de compilation Android.bp, ajoutez une section aconfig_declarations semblable à ce qui suit :

   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 doit comporter 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'indicateur est déclaré.

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

Déclarer un indicateur aconfig pour C et C++

Pour déclarer un indicateur aconfig pour C et C++ :

1. Dans un répertoire où se trouve le nouveau code, 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 du flag, fournit une clé unique. En Java, définir package sur foo.bar génère automatiquement une classe nommée foo.bar.Flags. En C++, les méthodes d'accesseur d'indicateur seraient nommées foo::bar::"flagname". Les indicateurs d'un même fichier de déclaration appartiennent au même package, mais plusieurs fichiers de déclaration peuvent contribuer aux indicateurs d'un même package.

   • container définit un ensemble de code qui est compilé et distribué 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 du flag, qui ne doit comporter que des lettres minuscules, des traits de soulignement et des chiffres.

   • namespace contient l'espace de noms pour les contributions. Vous devez collaborer avec l'examinateur Google qui vous a été attribué pour déterminer votre espace de noms. Si vous utilisez des indicateurs de lancement de fonctionnalité 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 correspond au numéro du bug associé à la nouvelle contribution de code. Vous devez collaborer avec l'examinateur Google qui vous a été attribué pour déterminer votre bug. Si vous utilisez des indicateurs de lancement de fonctionnalité pour maintenir la stabilité de votre propre miroir AOSP, vous pouvez utiliser votre numéro de suivi des bugs ou <none>.

   Remarque : L'utilisation d'options dans les APK qui ne sont pas créés avec une partition APEX ou système n'est pas acceptée.

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

Configurer la compilation

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

1. Dans votre fichier de compilation Android.bp, ajoutez une section aconfig_declarations semblable à ce qui suit :

   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 doit comporter 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'indicateur est déclaré.

2. Dans le même fichier, créez une cible cc_aconfig_library semblable à ce qui suit :

   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 doit contenir 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 dépendant de ce cc_aconfig_library nécessite certains types 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 défini vendor_available 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'indicateurs de code généré dans libexample_cpp_lib.

3. Créez une cible qui utilise les indicateurs aconfig, comme dans l'exemple suivant : 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"],
   }
   

   Où :

   • shared_libs inclut les dépendances supplémentaires requises pour les indicateurs aconfig.
   • static_libs correspond au nom de la bibliothèque créée par la compilation, conformément au champ cc_aconfig_library name de 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 indicateurs aconfig dans votre code.

Déclarer un flag aconfig pour Rust

Pour déclarer un indicateur aconfig pour Rust :

1. Dans un répertoire où se trouve le nouveau code, 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 du flag, fournit une clé unique. En Java, définir package sur foo.bar génère automatiquement une classe nommée foo.bar.Flags. En C++, les méthodes d'accesseur d'indicateur seraient nommées foo::bar::"flagname". Les indicateurs d'un même fichier de déclaration appartiennent au même package, mais plusieurs fichiers de déclaration peuvent contribuer aux indicateurs d'un même package.

   • container définit un ensemble de code qui est compilé et distribué 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 du flag, qui ne doit comporter que des lettres minuscules, des traits de soulignement et des chiffres.

   • namespace contient l'espace de noms pour les contributions. Vous devez collaborer avec l'examinateur Google qui vous a été attribué pour déterminer votre espace de noms. Si vous utilisez des indicateurs de lancement de fonctionnalité 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 correspond au numéro du bug associé à la nouvelle contribution de code. Vous devez collaborer avec l'examinateur Google qui vous a été attribué pour déterminer votre bug. Si vous utilisez des indicateurs de lancement de fonctionnalité pour maintenir la stabilité de votre propre miroir AOSP, vous pouvez utiliser votre numéro de suivi des bugs ou <none>.

   Remarque : L'utilisation d'options dans les APK qui ne sont pas créés avec une partition APEX ou système n'est pas acceptée.

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

Configurer la compilation

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

1. Dans votre fichier de compilation Android.bp, ajoutez une section aconfig_declarations semblable à ce qui suit :

   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 doit comporter 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'indicateur est déclaré.

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é lors 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 doit comporter 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.

   Grâce à 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'indicateurs de code généré.

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