Declarar uma flag de aconfig

Você pode usar flags aconfig nos códigos Java, C, C++ e Rust. O sistema de build do AOSP inicializa uma ferramenta chamada aconfig, usada para gerar uma biblioteca de métodos específica do idioma que pode ser usada para acessar o valor de cada flag. Antes de gerar a biblioteca, é necessário declarar flags e adicioná-las ao build.

Declarar uma flag aconfig para Java

Para declarar uma flag aconfig para Java:

  1. Em um diretório em que o novo código existe, crie um arquivo com a extensão .aconfig, por exemplo, my_new_aconfig_flag_declarations.aconfig. Um arquivo aconfig é um arquivo proto de texto que segue um esquema padrão.

  2. Adicione uma declaração de flag semelhante a esta:

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

    Em que:

    • package, quando combinado com o nome da flag, fornece uma chave exclusiva. Em Java, definir package como foo.bar resulta em uma classe gerada automaticamente chamada foo.bar.Flags. Em C++, os métodos do acessador de sinalização seriam chamados de foo::bar::"flagname". As flags no mesmo arquivo de declaração pertencem ao mesmo pacote, mas vários arquivos de declaração podem contribuir com flags para o mesmo pacote.

    • container define uma coleção de código que é criada e enviada em conjunto como um binário. Os contêineres válidos são system, vendor, system_ext, product, name.of.apex e name.of.apk.

    • name contém o nome da flag contendo apenas letras minúsculas, sublinhados e números.

    • namespace contém o namespace para contribuições. Você precisa trabalhar com o revisor do Google atribuído para determinar seu namespace. Se você estiver usando flags de lançamento de recursos para manter a estabilidade do seu próprio espelho do AOSP, poderá usar o namespace como quiser.

    • description contém uma breve descrição do recurso ou da mudança sinalizada.

    • bug é o número do bug associado à nova contribuição de código. Trabalhe com o revisor do Google atribuído para determinar seu bug. Se você estiver usando flags de lançamento de recursos para manter a estabilidade do seu próprio espelho do AOSP, use o número de rastreamento de bugs ou <none>.

  3. Salve o arquivo e saia do editor.

Configurar o build

Depois de declarar a flag, configure o build para que ele possa gerar o código da biblioteca usado para acessar o valor da flag.

  1. No arquivo de build Android.bp, adicione uma seção aconfig_declarations semelhante à seguinte:

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

    Em que:

    • name contém o nome da declaração que contém apenas letras minúsculas, sublinhados e números.
    • package contém o mesmo nome de pacote usado na declaração.
    • srcs contém o nome do arquivo .aconfig em que a flag é declarada.

  2. Salve o arquivo e saia do editor.

Declarar uma flag aconfig para C e C++

Para declarar uma flag aconfig para C e C++:

  1. Em um diretório em que o novo código existe, crie um arquivo com a extensão .aconfig, por exemplo, my_new_aconfig_flag_declarations.aconfig. Um arquivo aconfig é um arquivo proto de texto que segue um esquema padrão.

  2. Adicione uma declaração de flag semelhante a esta:

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

    Em que:

    • package, quando combinado com o nome da flag, fornece uma chave exclusiva. Em Java, definir package como foo.bar resulta em uma classe gerada automaticamente chamada foo.bar.Flags. Em C++, os métodos do acessador de sinalização seriam chamados de foo::bar::"flagname". As flags no mesmo arquivo de declaração pertencem ao mesmo pacote, mas vários arquivos de declaração podem contribuir com flags para o mesmo pacote.

    • container define uma coleção de código que é criada e enviada em conjunto como um binário. Os contêineres válidos são system, vendor, system_ext, product, name.of.apex e name.of.apk.

    • name contém o nome da flag contendo apenas letras minúsculas, sublinhados e números.

    • namespace contém o namespace para contribuições. Você precisa trabalhar com o revisor do Google atribuído para determinar seu namespace. Se você estiver usando flags de lançamento de recursos para manter a estabilidade do seu próprio espelho do AOSP, poderá usar o namespace como quiser.

    • description contém uma breve descrição do recurso ou da mudança sinalizada.

    • bug é o número do bug associado à nova contribuição de código. Trabalhe com o revisor do Google atribuído para determinar seu bug. Se você estiver usando flags de lançamento de recursos para manter a estabilidade do seu próprio espelho do AOSP, use o número de rastreamento de bugs ou <none>.

  3. Salve o arquivo e saia do editor.

Configurar o build

Depois de declarar a flag, configure o build para que ela possa gerar o código da biblioteca usado para acessar o valor da flag.

  1. No arquivo de build Android.bp, adicione uma seção aconfig_declarations semelhante à seguinte:

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

    Em que:

    • name contém o nome da declaração que contém apenas letras minúsculas, sublinhados e números.
    • package contém o mesmo nome de pacote usado na declaração.
    • srcs contém o nome do arquivo aconfig em que a flag é declarada.

  2. No mesmo arquivo, crie um destino cc_aconfig_library semelhante ao seguinte:

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

    Em que:

    • name contém o nome da biblioteca que contém apenas letras minúsculas, sublinhados e números.
    • aconfig_declarations contém o mesmo name usado na declaração.

    O destino de build cc_aconfig_library invoca o Codegen C ou C++, que cria uma biblioteca com o código gerado no tempo de build.

    A biblioteca CC aconfig é semelhante a um destino de biblioteca CC, mas tem opções como vendor_available, product_available, host_supported e vndk. Se o destino do build que depende desse cc_aconfig_library exigir determinado tipo de variante, talvez seja necessário adicionar a configuração correspondente no destino da biblioteca aconfig CC. Por exemplo, se o destino de build pai tiver vendor_available definido como true, defina vendor_available como true nesse destino cc_aconfig_library.

    Depois de adicionar esse destino de build, o código poderá acessar essa biblioteca. Você pode incluir essa biblioteca usando a sintaxe static_lib ou shared_lib. Se você quiser adicionar essa biblioteca como uma static_lib, adicione uma dependência shared_lib em server_configurable_flags. A etapa 3 mostra como incluir a biblioteca de sinalizações geradas por código em libexample_cpp_lib.

  3. Crie um destino que use as flags aconfig, como o exemplo cc_library a seguir:

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

    Em que:

    • shared_libs inclui dependências extras necessárias para flags aconfig.
    • static_libs é o nome da biblioteca criada pelo build de acordo com o campo name cc_aconfig_library na etapa 2. Ao criar uma entrada cc_library com o nome da biblioteca estática, agora é possível usar as sinalizações aconfig no código.

Declarar uma flag de aconfig para Rust

Para declarar uma flag aconfig para Rust:

  1. Em um diretório em que o novo código existe, crie um arquivo com a extensão .aconfig, por exemplo, my_new_aconfig_flag_declarations.aconfig. Um arquivo aconfig é um arquivo proto de texto que segue um esquema padrão.

  2. Adicione uma declaração de flag semelhante a esta:

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

    Em que:

    • package, quando combinado com o nome da flag, fornece uma chave exclusiva. Em Java, definir package como foo.bar resulta em uma classe gerada automaticamente chamada foo.bar.Flags. Em C++, os métodos do acessador de sinalização seriam chamados de foo::bar::"flagname". As flags no mesmo arquivo de declaração pertencem ao mesmo pacote, mas vários arquivos de declaração podem contribuir com flags para o mesmo pacote.

    • container define uma coleção de código que é criada e enviada em conjunto como um binário. Os contêineres válidos são system, vendor, system_ext, product, name.of.apex e name.of.apk.

    • name contém o nome da flag contendo apenas letras minúsculas, sublinhados e números.

    • namespace contém o namespace para contribuições. Você precisa trabalhar com o revisor do Google atribuído para determinar seu namespace. Se você estiver usando flags de lançamento de recursos para manter a estabilidade do seu próprio espelho do AOSP, poderá usar o namespace como quiser.

    • description contém uma breve descrição do recurso ou da mudança sinalizada.

    • bug é o número do bug associado à nova contribuição de código. Trabalhe com o revisor do Google atribuído para determinar seu bug. Se você estiver usando flags de lançamento de recursos para manter a estabilidade do seu próprio espelho do AOSP, use o número de rastreamento de bugs ou <none>.

  3. Salve o arquivo e saia do editor.

Configurar o build

Depois de declarar a flag, configure o build para que ele possa gerar o código da biblioteca usado para acessar o valor da flag.

  1. No arquivo de build Android.bp, adicione uma seção aconfig_declarations semelhante a esta:

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

    Em que:

    • name contém o nome da declaração que contém apenas letras minúsculas, sublinhados e números.
    • package contém o mesmo nome de pacote usado na declaração.
    • srcs contém o nome do arquivo aconfig em que a flag é declarada.

  2. Crie um destino rust_aconfig_library semelhante ao próximo exemplo. Esse destino invoca o Rust Codegen e cria uma biblioteca Rust com o código gerado durante o build.

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

    Em que:

    • name contém o nome da declaração, que contém apenas letras minúsculas, sublinhados e números.
    • crate_name contém o mesmo nome de pacote usado na declaração.
    • aconfig_declarations contém o mesmo name usado na declaração.

    Com essa mudança, o código pode depender dessa biblioteca do Rust.

  3. No mesmo arquivo, crie uma entrada rust_library semelhante à seguinte:

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

    Esse exemplo permite que os destinos de build do código-fonte libexample_demo_flags_rust incluam a biblioteca de sinalizações geradas pelo código.

  4. Salve o arquivo e saia do editor.