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 fichiers 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 une option aconfig pour Java

Pour déclarer un indicateur aconfig pour Java :

  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 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, lorsqu'il est combiné au nom de l'option, fournit une clé unique. En Java, Si vous définissez package sur foo.bar, vous générez automatiquement une classe nommée foo.bar.Flags En C++, les méthodes d'accesseur d'indicateurs sont nommées foo::bar::"flagname" Indicateurs figurant dans la même déclaration au même package, mais plusieurs fichiers de déclaration peuvent ajouter des indicateurs au 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 est le numéro de bug associé à la nouvelle contribution au code. Vous devez collaborer avec l'examinateur Google désigné pour déterminer votre bug. Si vous utilisez utiliser des indicateurs de lancement de fonctionnalité pour maintenir la stabilité de votre propre miroir AOSP, vous pouvez utiliser votre numéro de suivi de bug 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 lettres minuscules, traits de trait de soulignement et 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 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, lorsqu'il est combiné au nom de l'option, fournit une clé unique. En Java, Si vous définissez package sur foo.bar, vous générez automatiquement une classe nommée foo.bar.Flags En C++, les méthodes d'accesseur d'indicateurs sont nommées foo::bar::"flagname" Indicateurs figurant dans la même déclaration au même package, mais plusieurs fichiers de déclaration peuvent ajouter des indicateurs au 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 est le numéro de bug associé à la nouvelle contribution au code. Vous devez collaborer avec l'examinateur Google désigné pour déterminer votre bug. Si vous utilisez utiliser des indicateurs de lancement de fonctionnalité pour maintenir la stabilité de votre propre miroir AOSP, vous pouvez utiliser votre numéro de suivi de bug 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 lettres minuscules, traits de trait de soulignement et 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. Toi pouvez inclure cette bibliothèque à l'aide de static_lib ou Syntaxe 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. Étape 3 montre comment inclure la bibliothèque d'indicateurs 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 aux cc_aconfig_library name à 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 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, lorsqu'il est combiné au nom de l'option, fournit une clé unique. En Java, Si vous définissez package sur foo.bar, vous générez automatiquement une classe nommée foo.bar.Flags En C++, les méthodes d'accesseur d'indicateurs sont nommées foo::bar::"flagname" Indicateurs figurant dans la même déclaration au même package, mais plusieurs fichiers de déclaration peuvent ajouter des indicateurs au 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 est le numéro de bug associé à la nouvelle contribution au code. Vous devez collaborer avec l'examinateur Google désigné pour déterminer votre bug. Si vous utilisez utiliser des indicateurs de lancement de fonctionnalité pour maintenir la stabilité de votre propre miroir AOSP, vous pouvez utiliser votre numéro de suivi de bug ou <none>.

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

Configurer la compilation

Après avoir 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 comme 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 ne contenant que lettres minuscules, traits de trait de soulignement et 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 lettres minuscules, traits de trait de soulignement et 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 autorise vos cibles de compilation de code source libexample_demo_flags_rust pour inclure la bibliothèque d'indicateurs générée par le code.

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