Cómo declarar una marca de aconfig

Puedes usar las marcas aconfig en código de Java, C, C++ y Rust. El sistema de compilación de AOSP lanza una herramienta llamada aconfig que se utiliza con el objetivo de generar una biblioteca específica para el lenguaje con métodos que sirven para acceder al valor de cada marca. Antes de poder generar la biblioteca, debes declarar marcas y agregarlas a la compilación.

Cómo declarar una marca de aconfig para Java

Para declarar una marca de aconfig para Java, haz lo siguiente:

  1. En un directorio donde se encuentre el código nuevo, crea un archivo con la extensión .aconfig, por ejemplo, my_new_aconfig_flag_declarations.aconfig. Un archivo .aconfig es un archivo .proto de texto que sigue un esquema estándar.

  2. Agrega una declaración de marca que se parezca a la siguiente:

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

    En la que:

    • package proporciona una clave única cuando se combina con el nombre de la marca. En Java, establecer package en foo.bar da como resultado una clase autogenerada llamada foo.bar.Flags. En C++, los métodos de acceso a las marcas se llamarían foo::bar::"flagname". Las marcas en el mismo archivo de declaración pertenecen al mismo paquete, pero varios archivos de declaración pueden aportar marcas al mismo paquete.

    • container define una recopilación de código que se compila y envía como objeto binario. Los contenedores válidos son system, vendor, system_ext, product, name.of.apex y name.of.apk.

    • name contiene el nombre de la marca, que incluye solo letras en minúscula, guiones bajos y números.

    • namespace contiene el espacio de nombres para las contribuciones. Para determinar tu espacio de nombres, debes trabajar con tu revisor de Google designado. Si utilizas marcas de lanzamiento de funciones para mantener la estabilidad de tu propia duplicación de AOSP, puedes usar el espacio de nombres como lo desees.

    • description contiene una descripción breve de la función o el cambio que se marcó.

    • bug es el número de error asociado con la contribución del código nuevo. Para determinar tu bug, debes trabajar con tu revisor de Google designado. Si utilizas marcas de lanzamiento de funciones para mantener la estabilidad de tu propia duplicación de AOSP, puedes usar tu número de seguimiento de errores o <none>.

  3. Guarda el archivo y sal del editor.

Cómo configurar la compilación

Después de declarar la marca, configura la compilación para que genere el código de la biblioteca que se utilizó para acceder al valor de la marca.

  1. En tu archivo de compilación Android.bp, agrega una sección aconfig_declarations similar a la siguiente:

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

    En la que:

    • name contiene el nombre de la declaración, que incluye solo letras en minúscula, guiones bajos y números.
    • package contiene el mismo nombre de paquete que se usó en la declaración.
    • srcs contiene el nombre del archivo .aconfig en el que se declaró la marca.

  2. Guarda el archivo y sal del editor.

Cómo declarar una marca de aconfig para C y C++

Para declarar una marca de aconfig para C y C++, haz lo siguiente:

  1. En un directorio donde se encuentre el código nuevo, crea un archivo con la extensión .aconfig, por ejemplo, my_new_aconfig_flag_declarations.aconfig. Un archivo .aconfig es un archivo .proto de texto que sigue un esquema estándar.

  2. Agrega una declaración de marca que se parezca a la siguiente:

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

    En la que:

    • package proporciona una clave única cuando se combina con el nombre de la marca. En Java, establecer package en foo.bar da como resultado una clase autogenerada llamada foo.bar.Flags. En C++, los métodos de acceso a las marcas se llamarían foo::bar::"flagname". Las marcas en el mismo archivo de declaración pertenecen al mismo paquete, pero varios archivos de declaración pueden aportar marcas al mismo paquete.

    • container define una recopilación de código que se compila y envía como objeto binario. Los contenedores válidos son system, vendor, system_ext, product, name.of.apex y name.of.apk.

    • name contiene el nombre de la marca, que incluye solo letras en minúscula, guiones bajos y números.

    • namespace contiene el espacio de nombres para las contribuciones. Para determinar tu espacio de nombres, debes trabajar con tu revisor de Google designado. Si utilizas marcas de lanzamiento de funciones para mantener la estabilidad de tu propia duplicación de AOSP, puedes usar el espacio de nombres como lo desees.

    • description contiene una descripción breve de la función o el cambio que se marcó.

    • bug es el número de error asociado con la contribución del código nuevo. Para determinar tu bug, debes trabajar con tu revisor de Google designado. Si utilizas marcas de lanzamiento de funciones para mantener la estabilidad de tu propia duplicación de AOSP, puedes usar tu número de seguimiento de errores o <none>.

  3. Guarda el archivo y sal del editor.

Cómo configurar la compilación

Después de declarar la marca, configura la compilación para que genere el código de la biblioteca que se utilizó para acceder al valor de la marca.

  1. En tu archivo de compilación Android.bp, agrega una sección aconfig_declarations similar a la siguiente:

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

    En la que:

    • name contiene el nombre de la declaración, que incluye solo letras en minúscula, guiones bajos y números.
    • package contiene el mismo nombre de paquete que se usó en la declaración.
    • srcs contiene el nombre del archivo de aconfig en el que se declaró la marca.

  2. En el mismo archivo, crea un destino cc_aconfig_library similar al siguiente:

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

    En la que:

    • name contiene el nombre de la biblioteca, que incluye solo letras en minúscula, guiones bajos y números.
    • aconfig_declarations contiene el mismo name que se usó en la declaración.

    El destino de compilación cc_aconfig_library invoca codegen de C o C++, que crea una biblioteca con el código generado durante el tiempo de compilación.

    La biblioteca de CC de aconfig es similar a un destino de biblioteca de CC, pero tiene opciones como vendor_available, product_available, host_supported y vndk. Si el destino de compilación que depende de esta cc_aconfig_library requiere un cierto tipo de variantes, es posible que también debas agregar el parámetro de configuración correspondiente en el destino de la biblioteca de CC de aconfig. Por ejemplo, si el destino de compilación superior tiene vendor_available establecido en true, también podrías establecer vendor_available en true en este destino de cc_aconfig_library.

    Luego de que agregues ese destino de compilación, tu código podrá acceder a esta biblioteca. Puedes incluir la biblioteca con la sintaxis static_lib o shared_lib. Si quieres agregar esta biblioteca como static_lib, incluye una dependencia shared_lib en server_configurable_flags. El paso 3 muestra cómo incluir la biblioteca de marcas del código generadas en libexample_cpp_lib.

  3. Crea un destino que use las marcas de aconfig, como la siguiente cc_library de ejemplo:

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

    En la que:

    • shared_libs incluye dependencias adicionales requeridas para las marcas de aconfig.
    • static_libs es el nombre de la biblioteca que crea la compilación de acuerdo con el campo name de cc_aconfig_library del paso 2. Si creas una entrada cc_library con el nombre de la biblioteca estática, puedes usar marcas de aconfig en tu código.

Cómo declarar una marca de aconfig para Rust

Para declarar una marca de aconfig para Rust, haz lo siguiente:

  1. En un directorio donde se encuentre el código nuevo, crea un archivo con la extensión .aconfig, por ejemplo, my_new_aconfig_flag_declarations.aconfig. Un archivo .aconfig es un archivo .proto de texto que sigue un esquema estándar.

  2. Agrega una declaración de marca que se parezca a la siguiente:

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

    En la que:

    • package proporciona una clave única cuando se combina con el nombre de la marca. En Java, establecer package en foo.bar da como resultado una clase autogenerada llamada foo.bar.Flags. En C++, los métodos de acceso a las marcas se llamarían foo::bar::"flagname". Las marcas en el mismo archivo de declaración pertenecen al mismo paquete, pero varios archivos de declaración pueden aportar marcas al mismo paquete.

    • container define una recopilación de código que se compila y envía como objeto binario. Los contenedores válidos son system, vendor, system_ext, product, name.of.apex y name.of.apk.

    • name contiene el nombre de la marca, que incluye solo letras en minúscula, guiones bajos y números.

    • namespace contiene el espacio de nombres para las contribuciones. Para determinar tu espacio de nombres, debes trabajar con tu revisor de Google designado. Si utilizas marcas de lanzamiento de funciones para mantener la estabilidad de tu propia duplicación de AOSP, puedes usar el espacio de nombres como lo desees.

    • description contiene una descripción breve de la función o el cambio que se marcó.

    • bug es el número de error asociado con la contribución del código nuevo. Para determinar tu bug, debes trabajar con tu revisor de Google designado. Si utilizas marcas de lanzamiento de funciones para mantener la estabilidad de tu propia duplicación de AOSP, puedes usar tu número de seguimiento de errores o <none>.

  3. Guarda el archivo y sal del editor.

Cómo configurar la compilación

Después de declarar la marca, configura la compilación para que genere el código de la biblioteca que se utilizó para acceder al valor de la marca.

  1. En tu archivo de compilación Android.bp, agrega una sección aconfig_declarations similar a la siguiente:

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

    En la que:

    • name contiene el nombre de la declaración, que incluye solo letras en minúscula, guiones bajos y números.
    • package contiene el mismo nombre de paquete que se usó en la declaración.
    • srcs contiene el nombre del archivo de aconfig en el que se declaró la marca.

  2. Crea un destino rust_aconfig_library que se parezca al ejemplo que se muestra a continuación. Este destino invoca codegen de Rust y crea una biblioteca de Rust con el código generado durante el tiempo de compilación.

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

    En la que:

    • name contiene el nombre de la declaración, que incluye solo letras en minúscula, guiones bajos y números.
    • crate_name contiene el mismo nombre de paquete que se usó en la declaración.
    • aconfig_declarations contiene el mismo name que se usó en la declaración.

    Con ese cambio, tu código puede depender de esta biblioteca de Rust.

  3. En el mismo archivo, crea una entrada rust_library similar a la siguiente:

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

    Este ejemplo permite que los destinos de compilación libexample_demo_flags_rust del código fuente incluyan la biblioteca de marcas del código generadas.

  4. Guarda el archivo y sal del editor.