Declara una marca de aconfig

Puedes usar marcas de aconfig en código Java, C, C++ y Rust. El sistema de compilación de AOSP inicia una herramienta llamada aconfig que se usa para generar una biblioteca de métodos específica del lenguaje que puedes usar para acceder al valor de cada marca. Antes de generar la biblioteca, debes declarar marcas y agregarlas a la compilación.

Declara una marca de aconfig para Java

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

  1. En un directorio donde exista 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 similar 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>"
}

    donde:

    • package, cuando se combina con el nombre de la marca, proporciona una clave única. En Java, configurar package como foo.bar da como resultado una clase autogenerada llamada foo.bar.Flags. En C++, los métodos de acceso de 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 contribuir con marcas al mismo paquete.

    • container define una colección de código que se compila y envía juntas como un 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 solo contiene letras minúsculas, guiones bajos y números.

    • namespace contiene el espacio de nombres de las contribuciones. Debes trabajar con el revisor de Google asignado para determinar tu espacio de nombres. Si usas marcas de lanzamiento de funciones para mantener la estabilidad de tu propio espejo de AOSP, puedes usar el espacio de nombres como quieras.

    • description contiene una breve descripción del componente o el cambio que se marcó.

    • bug es el número de error asociado con la nueva contribución de código. Debes trabajar con el revisor de Google asignado para determinar tu bug. Si usas marcas de lanzamiento de funciones para mantener la estabilidad de tu propio espejo 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 tu marca, configura la compilación para que pueda generar el código de la biblioteca que se usa para acceder al valor de la marca.

  1. En el 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"
  ],
}

    donde:

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

  2. Guarda el archivo y sal del editor.

Declara una marca aconfig para C y C++

Si deseas declarar una marca aconfig para C y C++, haz lo siguiente:

  1. En un directorio donde exista 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 similar 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>"
}

    donde:

    • package, cuando se combina con el nombre de la marca, proporciona una clave única. En Java, configurar package como foo.bar da como resultado una clase autogenerada llamada foo.bar.Flags. En C++, los métodos de acceso de 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 contribuir con marcas al mismo paquete.

    • container define una colección de código que se compila y envía juntas como un 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 solo contiene letras minúsculas, guiones bajos y números.

    • namespace contiene el espacio de nombres de las contribuciones. Debes trabajar con el revisor de Google asignado para determinar tu espacio de nombres. Si usas marcas de lanzamiento de funciones para mantener la estabilidad de tu propio espejo de AOSP, puedes usar el espacio de nombres como quieras.

    • description contiene una breve descripción del componente o el cambio que se marcó.

    • bug es el número de error asociado con la nueva contribución de código. Debes trabajar con el revisor de Google asignado para determinar tu bug. Si usas marcas de lanzamiento de funciones para mantener la estabilidad de tu propio espejo 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 tu marca, configura la compilación para que pueda generar el código de la biblioteca que se usa para acceder al valor de la marca.

  1. En el 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"
  ],
}

    donde:

    • name contiene el nombre de la declaración que solo contiene letras minúsculas, guiones bajos y números.
    • package contiene el mismo nombre de paquete que se usa en la declaración.
    • srcs contiene el nombre del archivo aconfig en el que se declara 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",
}

    donde:

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

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

    La biblioteca aconfig de CC es similar a un destino de biblioteca de CC, pero tiene opciones como vendor_available, product_available, host_supported y vndk. Si el objetivo de compilación que depende de este cc_aconfig_library requiere un tipo de variantes determinado, es posible que también debas agregar el parámetro de configuración correspondiente en el objetivo de la biblioteca de aconfig de CC. Por ejemplo, si el destino de compilación superior tiene vendor_available configurado como true, también te recomendamos que configures vendor_available como true en este destino cc_aconfig_library.

    Después de agregar este destino de compilación, tu código podrá acceder a esta biblioteca. Puedes incluir esta biblioteca con la sintaxis static_lib o shared_lib. Ten en cuenta que, si quieres agregar esta biblioteca como static_lib, debes agregar una dependencia shared_lib en server_configurable_flags. En el paso 3, se muestra cómo incluir la biblioteca de marcas generada por código en libexample_cpp_lib.

  3. Crea un destino que use las marcas aconfig, como el siguiente ejemplo de 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"],
}

    donde:

    • shared_libs incluye dependencias adicionales necesarias para las marcas de aconfig.
    • static_libs es el nombre de la biblioteca que crea la compilación según el campo cc_aconfig_library name en el paso 2. Si creas una entrada cc_library con el nombre de la biblioteca estática, ahora puedes usar las 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 exista 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 similar 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>"
}

    donde:

    • package, cuando se combina con el nombre de la marca, proporciona una clave única. En Java, configurar package como foo.bar da como resultado una clase autogenerada llamada foo.bar.Flags. En C++, los métodos de acceso de 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 contribuir con marcas al mismo paquete.

    • container define una colección de código que se compila y envía juntas como un 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 solo contiene letras minúsculas, guiones bajos y números.

    • namespace contiene el espacio de nombres de las contribuciones. Debes trabajar con el revisor de Google asignado para determinar tu espacio de nombres. Si usas marcas de lanzamiento de funciones para mantener la estabilidad de tu propio espejo de AOSP, puedes usar el espacio de nombres como quieras.

    • description contiene una breve descripción del componente o el cambio que se marcó.

    • bug es el número de error asociado con la nueva contribución de código. Debes trabajar con el revisor de Google asignado para determinar tu bug. Si usas marcas de lanzamiento de funciones para mantener la estabilidad de tu propio espejo 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 tu marca, configura la compilación para que pueda generar el código de la biblioteca que se usa 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"
  ],
}

    donde:

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

  2. Crea un destino rust_aconfig_library similar al siguiente ejemplo. Este objetivo invoca Rust Codegen 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",
}

    donde:

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

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

    Esta muestra permite que los destinos de compilación de código fuente libexample_demo_flags_rust incluyan la biblioteca de marcas generadas por código.

  4. Guarda el archivo y sal del editor.