Déclarer un indicateur aconfig

Vous pouvez utiliser les indicateurs aconfig dans le 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écifique à la 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 au build.

Déclarer un indicateur aconfig pour Java

Pour déclarer un indicateur 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 à celle-ci :

   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, associé au nom de l'indicateur, fournit une clé unique. En Java, si vous définissez package sur foo.bar, la classe foo.bar.Flags est générée automatiquement. En C++, les méthodes d'accès aux indicateurs sont nommées foo::bar::"flagname". Les indicateurs 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 un ensemble de code qui est compilé et distribué ensemble en tant que binaire. Les conteneurs valides sont system, vendor, system_ext, product, name.of.apex et name.of.apk.

   • name contient le nom de l'indicateur, qui ne doit contenir 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és pour assurer 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 désigné pour déterminer votre bug. Si vous utilisez des indicateurs 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 <none>.

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

Configurer la compilation

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

1. Dans votre fichier de compilation Android.bp, ajoutez une section aconfig_declarations semblable à celle-ci:

   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 ne contenant 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 à celle-ci :

   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, associé au nom de l'indicateur, fournit une clé unique. En Java, si vous définissez package sur foo.bar, la classe foo.bar.Flags est générée automatiquement. En C++, les méthodes d'accès aux indicateurs sont nommées foo::bar::"flagname". Les indicateurs 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 un ensemble de code qui est compilé et distribué ensemble en tant que binaire. Les conteneurs valides sont system, vendor, system_ext, product, name.of.apex et name.of.apk.

   • name contient le nom de l'indicateur, qui ne doit contenir 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és pour assurer 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 désigné pour déterminer votre bug. Si vous utilisez des indicateurs 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 <none>.

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

Configurer la compilation

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

1. Dans votre fichier de compilation Android.bp, ajoutez une section aconfig_declarations semblable à celle-ci:

   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 ne contenant 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 à celle-ci:

   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 le codegen C ou C++, 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 elle comporte des options telles que vendor_available, product_available, host_supported et vndk. Si la cible de compilation dépendant de cet élément cc_aconfig_library nécessite un certain type de variantes, vous devrez peut-être également ajouter le paramètre correspondant dans la cible de 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 de drapeaux générée par le code dans libexample_cpp_lib.

3. Créez une cible qui utilise les options aconfig, comme dans 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 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 indicateurs aconfig dans votre code.

Déclarer un indicateur aconfig pour Rust

Pour déclarer un indicateur aconfig pour Rust :

1. Dans un répertoire contenant 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 de proto texte qui suit un schéma standard.

2. Ajoutez une déclaration d'option semblable à celle-ci :

   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, associé au nom de l'indicateur, fournit une clé unique. En Java, si vous définissez package sur foo.bar, la classe foo.bar.Flags est générée automatiquement. En C++, les méthodes d'accès aux indicateurs sont nommées foo::bar::"flagname". Les indicateurs 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 un ensemble de code qui est compilé et distribué ensemble en tant que binaire. Les conteneurs valides sont system, vendor, system_ext, product, name.of.apex et name.of.apk.

   • name contient le nom de l'indicateur, qui ne doit contenir 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és pour assurer 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 désigné pour déterminer votre bug. Si vous utilisez des indicateurs 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 <none>.

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

Configurer la compilation

Après avoir déclaré l'indicateur, configurez la compilation afin qu'elle puisse générer le code de bibliothèque utilisé pour accéder à la valeur de l'indicateur.

1. Dans votre fichier de compilation Android.bp, ajoutez une section aconfig_declarations semblable à celle-ci :

   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 ne contenant 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é 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 ne contenant 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 à celle-ci :

   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.