Dichiarare un flag aconfig

Puoi utilizzare i flag aconfig nel codice Java, C, C++ e Rust. Il sistema di compilazione AOSP avvia uno strumento chiamato aconfig utilizzato per generare una libreria di metodi specifica per la lingua che puoi utilizzare per accedere al valore di ogni flag. Prima di poter generare la libreria, devi dichiarare i flag e aggiungerli alla compilazione.

Dichiara un flag aconfig per Java

Per dichiarare un flag aconfig per Java:

  1. In una directory in cui esiste il nuovo codice, crea un file con l'estensione.aconfig, ad esempio my_new_aconfig_flag_declarations.aconfig. Un file aconfig è un file proto di testo che segue uno schema standard.

  2. Aggiungi una dichiarazione di flag simile alla seguente:

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

    Dove:

    • package, se combinato con il nome del flag, fornisce una chiave univoca. In Java, impostare package su foo.bar genera una classe creata automaticamente denominata foo.bar.Flags. In C++, i metodi di accesso ai flag si chiamerebbero foo::bar::"flagname". Gli indicatori nello stesso file di dichiarazione appartengono allo stesso pacchetto, ma più file di dichiarazione possono contribuire con indicatori allo stesso pacchetto.

    • container definisce una raccolta di codice che viene compilata e inviata insieme come file binario. I contenitori validi sono system, vendor, system_ext, product, name.of.apex e name.of.apk.

    • name contiene il nome del flag contenente solo lettere minuscole, trattini bassi e numeri.

    • namespace contiene lo spazio dei nomi per i contributi. Devi collaborare con il revisore di Google assegnato per determinare il tuo spazio dei nomi. Se utilizzi i flag di lancio delle funzionalità per mantenere la stabilità del tuo mirror AOSP, puoi utilizzare lo spazio dei nomi come preferisci.

    • description contiene una breve descrizione della funzionalità o della modifica segnalata.

    • bug è il numero del bug associato al nuovo contributo di codice. Devi collaborare con il revisore di Google assegnato per determinare il tuo bug. Se utilizzi i flag di lancio delle funzionalità per mantenere la stabilità del tuo mirror AOSP, puoi utilizzare il numero di monitoraggio dei bug o <none>.

  3. Salva il file ed esci dall'editor.

Configura la build

Dopo aver dichiarato il flag, configura la compilazione in modo che possa generare il codice della libreria utilizzato per accedere al valore del flag.

  1. Nel file di build Android.bp, aggiungi una sezione aconfig_declarations simile alla seguente:

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

    Dove:

    • name contiene il nome della dichiarazione contenente solo lettere minuscole, trattini bassi e numeri.
    • package contiene lo stesso nome del pacchetto utilizzato nella dichiarazione.
    • srcs contiene il nome del file .aconfig in cui è dichiarato il flag.

  2. Salva il file ed esci dall'editor.

Dichiarare un flag aconfig per C e C++

Per dichiarare un flag aconfig per C e C++:

  1. In una directory in cui esiste il nuovo codice, crea un file con l'estensione.aconfig, ad esempio my_new_aconfig_flag_declarations.aconfig. Un file aconfig è un file proto di testo che segue uno schema standard.

  2. Aggiungi una dichiarazione di flag simile alla seguente:

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

    Dove:

    • package, se combinato con il nome del flag, fornisce una chiave univoca. In Java, impostare package su foo.bar genera una classe creata automaticamente denominata foo.bar.Flags. In C++, i metodi di accesso ai flag si chiamerebbero foo::bar::"flagname". Gli indicatori nello stesso file di dichiarazione appartengono allo stesso pacchetto, ma più file di dichiarazione possono contribuire con indicatori allo stesso pacchetto.

    • container definisce una raccolta di codice che viene compilata e inviata insieme come file binario. I contenitori validi sono system, vendor, system_ext, product, name.of.apex e name.of.apk.

    • name contiene il nome del flag contenente solo lettere minuscole, trattini bassi e numeri.

    • namespace contiene lo spazio dei nomi per i contributi. Devi collaborare con il revisore di Google assegnato per determinare il tuo spazio dei nomi. Se utilizzi i flag di lancio delle funzionalità per mantenere la stabilità del tuo mirror AOSP, puoi utilizzare lo spazio dei nomi come preferisci.

    • description contiene una breve descrizione della funzionalità o della modifica segnalata.

    • bug è il numero del bug associato al nuovo contributo di codice. Devi collaborare con il revisore di Google assegnato per determinare il tuo bug. Se utilizzi i flag di lancio delle funzionalità per mantenere la stabilità del tuo mirror AOSP, puoi utilizzare il numero di monitoraggio dei bug o <none>.

  3. Salva il file ed esci dall'editor.

Configura la build

Dopo aver dichiarato il flag, configura la compilazione in modo che possa generare il codice della libreria utilizzato per accedere al valore del flag.

  1. Nel file di build Android.bp, aggiungi una sezione aconfig_declarations simile alla seguente:

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

    Dove:

    • name contiene il nome della dichiarazione contenente solo lettere minuscole, trattini bassi e numeri.
    • package contiene lo stesso nome del pacchetto utilizzato nella dichiarazione.
    • srcs contiene il nome del file aconfig in cui è dichiarato il flag.

  2. Nello stesso file, crea un target cc_aconfig_library simile al seguente:

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

    Dove:

    • name contiene il nome della libreria contenente solo lettere minuscole, trattini bassi e numeri.
    • aconfig_declarations contiene lo stesso name utilizzato nella dichiarazione.

    Il target di build cc_aconfig_library richiama Codegen C o C++, che crea una libreria con il codice generato in fase di compilazione.

    La libreria aconfig di CC è simile a un target della libreria CC, ma offre opzioni come vendor_available, product_available, host_supported e vndk. Se il target di compilazione che dipende da questo cc_aconfig_library richiede un determinato tipo di varianti, potrebbe essere necessario aggiungere anche l'impostazione corrispondente nel target della libreria aconfig di CC. Ad esempio, se il target di compilazione principale ha impostato vendor_available su true, ti consigliamo di impostare vendor_available su true anche in questo target cc_aconfig_library.

    Dopo aver aggiunto questo target di compilazione, il codice può accedere a questa libreria. Puoi includere questa libreria utilizzando la sintassi static_lib o shared_lib. Tieni presente che se vuoi aggiungere questa libreria come static_lib, aggiungi una dipendenza shared_lib da server_configurable_flags. Il passaggio 3 illustra come includere la libreria di flag generata dal codice in libexample_cpp_lib.

  3. Crea un target che utilizzi i flag aconfig, ad esempio il seguente esempiocc_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"],
}

    Dove:

    • shared_libs include le dipendenze aggiuntive necessarie per i flag aconfig.
    • static_libs è il nome della libreria creata dalla compilazione in base al campo cc_aconfig_library name nel passaggio 2. Creando una voce cc_library con il nome della libreria statica, ora puoi utilizzare i flag aconfig nel codice.

Dichiarare un flag aconfig per Rust

Per dichiarare un flag aconfig per Rust:

  1. In una directory in cui esiste il nuovo codice, crea un file con l'estensione.aconfig, ad esempio my_new_aconfig_flag_declarations.aconfig. Un file aconfig è un file proto di testo che segue uno schema standard.

  2. Aggiungi una dichiarazione di flag simile alla seguente:

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

    Dove:

    • package, se combinato con il nome del flag, fornisce una chiave univoca. In Java, impostare package su foo.bar genera una classe creata automaticamente denominata foo.bar.Flags. In C++, i metodi di accesso ai flag si chiamerebbero foo::bar::"flagname". Gli indicatori nello stesso file di dichiarazione appartengono allo stesso pacchetto, ma più file di dichiarazione possono contribuire con indicatori allo stesso pacchetto.

    • container definisce una raccolta di codice che viene compilata e inviata insieme come file binario. I contenitori validi sono system, vendor, system_ext, product, name.of.apex e name.of.apk.

    • name contiene il nome del flag contenente solo lettere minuscole, trattini bassi e numeri.

    • namespace contiene lo spazio dei nomi per i contributi. Devi collaborare con il revisore di Google assegnato per determinare il tuo spazio dei nomi. Se utilizzi i flag di lancio delle funzionalità per mantenere la stabilità del tuo mirror AOSP, puoi utilizzare lo spazio dei nomi come preferisci.

    • description contiene una breve descrizione della funzionalità o della modifica segnalata.

    • bug è il numero del bug associato al nuovo contributo di codice. Devi collaborare con il revisore di Google assegnato per determinare il tuo bug. Se utilizzi i flag di lancio delle funzionalità per mantenere la stabilità del tuo mirror AOSP, puoi utilizzare il numero di monitoraggio dei bug o <none>.

  3. Salva il file ed esci dall'editor.

Configura la build

Dopo aver dichiarato il flag, configura la compilazione in modo che possa generare il codice della libreria utilizzato per accedere al valore del flag.

  1. Nel file di build Android.bp, aggiungi una sezione aconfig_declarations simile alla seguente:

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

    Dove:

    • name contiene il nome della dichiarazione contenente solo lettere minuscole, trattini bassi e numeri.
    • package contiene lo stesso nome del pacchetto utilizzato nella dichiarazione.
    • srcs contiene il nome del file aconfig in cui è dichiarato il flag.

  2. Crea un target rust_aconfig_library simile all'esempio seguente. Questo target invoca Rust Codegen e crea una libreria Rust con il codice generato durante la compilazione.

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

    Dove:

    • name contiene il nome della dichiarazione contenente solo lettere minuscole, trattini bassi e numeri.
    • crate_name contiene lo stesso nome del pacchetto utilizzato nella dichiarazione.
    • aconfig_declarations contiene lo stesso name utilizzato nella dichiarazione.

    Con questa modifica, il codice può dipendere da questa libreria Rust.

  3. Nello stesso file, crea una voce rust_library simile alla seguente:

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

    Questo esempio consente ai target di compilazione del codice sorgente libexample_demo_flags_rust di includere la libreria di flag generata dal codice.

  4. Salva il file ed esci dall'editor.