Declarar uma flag aconfig

Você pode usar flags aconfig em códigos Java, C, C++ e Rust. O sistema de build do AOSP inicia uma ferramenta chamada aconfig, usada para gerar uma biblioteca de métodos específica da linguagem que você pode usar para acessar o valor de cada flag. Antes de gerar a biblioteca, declare as flags e as adicione ao build.

Declarar uma flag aconfig em Java

Para declarar uma flag aconfig em Java, siga estas instruções:

  1. Em um diretório onde o novo código já exista, crie um arquivo com a extensão .aconfig, por exemplo, my_new_aconfig_flag_declarations.aconfig. Um arquivo aconfig é um arquivo textproto 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 ao nome da flag, fornece uma chave exclusiva. Em Java, definir package como foo.bar resulta em uma classe autogerada chamada foo.bar.Flags. Em C++, os métodos do acessador seriam chamados 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 um conjunto de códigos compilados e enviados ao mesmo tempo como um binário. system, vendor, system_ext, product, name.of.apex e name.of.apk são contêineres válidos.

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

    • namespace contém o namespace para contribuições. Você precisa trabalhar com o avaliador 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, use o namespace como achar melhor.

    • description contém uma descrição breve do recurso ou da mudança que vai receber uma flag.

    • bug é o número do bug associado à nova contribuição de código. Você precisa trabalhar com o avaliador 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 seu número de rastreamento de bugs ou <none>.

  3. Salve o arquivo e saia do editor.

Configurar o build

Depois de declarar sua flag, configure o build para gerar o código de biblioteca usado para acessar o valor da flag.

  1. No seu 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 apenas com 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 foi declarada.

  2. Salve o arquivo e saia do editor.

Declarar uma flag aconfig em C e C++

Para declarar uma flag aconfig em C e C++, siga estas instruções:

  1. Em um diretório onde o novo código já exista, crie um arquivo com a extensão .aconfig, por exemplo, my_new_aconfig_flag_declarations.aconfig. Um arquivo aconfig é um arquivo textproto 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 ao nome da flag, fornece uma chave exclusiva. Em Java, definir package como foo.bar resulta em uma classe autogerada chamada foo.bar.Flags. Em C++, os métodos do acessador seriam chamados 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 um conjunto de códigos compilados e enviados ao mesmo tempo como um binário. system, vendor, system_ext, product, name.of.apex e name.of.apk são contêineres válidos.

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

    • namespace contém o namespace para contribuições. Você precisa trabalhar com o avaliador 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, use o namespace como achar melhor.

    • description contém uma descrição breve do recurso ou da mudança que vai receber uma flag.

    • bug é o número do bug associado à nova contribuição de código. Você precisa trabalhar com o avaliador 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 seu número de rastreamento de bugs ou <none>.

  3. Salve o arquivo e saia do editor.

Configurar o build

Depois de declarar sua flag, configure o build para gerar o código de biblioteca usado para acessar o valor da flag.

  1. No seu 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 apenas com 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 foi declarada.

  2. No mesmo arquivo, crie uma cc_aconfig_library de destino semelhante a esta:

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

    Em que:

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

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

    A biblioteca CC aconfig é semelhante a uma biblioteca CC de destino, mas tem opções como vendor_available, product_available, host_supported e vndk. Se o destino do build que depende dessa cc_aconfig_library exigir determinados tipos de variantes, poderá ser necessário adicionar a configuração correspondente na biblioteca CC aconfig de destino. Por exemplo, se vendor_available estiver definido como true no destino de build pai, talvez seja interessante definir vendor_available como true na cc_aconfig_library de destino.

    Depois de receber o destino de build, seu código poderá acessar a biblioteca. Inclua essa biblioteca usando sintaxe static_lib ou shared_lib. Caso você queira adicionar a biblioteca como um static_lib, adicione uma dependência shared_lib nas server_configurable_flags. A etapa 3 mostra como incluir a biblioteca de flags gerada por código em libexample_cpp_lib.

  3. Crie um objeto de destino que use as flags aconfig, como neste exemplo 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"],
}

    Em que:

    • shared_libs inclui dependências extras necessárias para flags aconfig.
    • static_libs é o nome da biblioteca criada pelo build usando o campo cc_aconfig_library name na etapa 2. Ao criar uma entrada cc_library com o nome da biblioteca estática, você pode usar as flags aconfig no seu código.

Declarar uma flag aconfig em Rust

Para declarar uma flag aconfig em Rust, siga estas instruções:

  1. Em um diretório onde o novo código já exista, crie um arquivo com a extensão .aconfig, por exemplo, my_new_aconfig_flag_declarations.aconfig. Um arquivo aconfig é um arquivo textproto 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 ao nome da flag, fornece uma chave exclusiva. Em Java, definir package como foo.bar resulta em uma classe autogerada chamada foo.bar.Flags. Em C++, os métodos do acessador seriam chamados 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 um conjunto de códigos compilados e enviados ao mesmo tempo como um binário. system, vendor, system_ext, product, name.of.apex e name.of.apk são contêineres válidos.

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

    • namespace contém o namespace para contribuições. Você precisa trabalhar com o avaliador 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, use o namespace como achar melhor.

    • description contém uma descrição breve do recurso ou da mudança que vai receber uma flag.

    • bug é o número do bug associado à nova contribuição de código. Você precisa trabalhar com o avaliador 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 seu número de rastreamento de bugs ou <none>.

  3. Salve o arquivo e saia do editor.

Configurar o build

Depois de declarar sua flag, configure o build para gerar o código de biblioteca usado para acessar o valor da flag.

  1. No seu 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 apenas com 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 foi declarada.

  2. Crie uma rust_aconfig_library de destino semelhante ao exemplo a seguir. Esse destino invoca codegen Rust e cria uma biblioteca Rust com o código gerado durante o tempo de 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 apenas com 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, seu código pode depender dessa biblioteca Rust.

  3. No mesmo arquivo, crie uma entrada rust_library semelhante a esta:

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

    O exemplo permite que seu build de código-fonte tenha como destino libexample_demo_flags_rust para incluir a biblioteca de flags gerada por código.

  4. Salve o arquivo e saia do editor.