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, l'impostazione di package su foo.bar genera una classe generata automaticamente denominata foo.bar.Flags. In C++, i metodi di accesso ai flag si chiamerebbero foo::bar::"flagname". Flag nella stessa dichiarazione di un file appartiene allo stesso pacchetto, ma più file di dichiarazione possono contribuiscano con l'invio di flag 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 Google assegnato per determinare il tuo spazio dei nomi. Se utilizzi di lancio delle funzionalità per mantenere la stabilità del tuo mirror AOSP, usa lo spazio dei nomi come preferisci.

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

    • bug è il numero di bug associato al nuovo contributo del codice. Devi collaborare con il revisore di Google assegnato per determinare il tuo bug. Se l'utilizzo di flag di lancio delle funzionalità per mantenere la stabilità del tuo mirror AOSP, puoi usare il numero di tracciamento dei bug oppure usare <none>.

  3. Salva il file ed esci dall'editor.

Configurare 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 al 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 di pacchetto utilizzato nella dichiarazione.
    • srcs contiene il nome del file .aconfig in cui è dichiarato il flag.

  2. Salva il file ed esci dall'editor.

Dichiara 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, l'impostazione di package su foo.bar genera una classe generata automaticamente denominata foo.bar.Flags. In C++, i metodi di accesso ai flag si chiamerebbero foo::bar::"flagname". Flag nella stessa dichiarazione di un file appartiene allo stesso pacchetto, ma più file di dichiarazione possono contribuiscano con l'invio di flag 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 Google assegnato per determinare il tuo spazio dei nomi. Se utilizzi di lancio delle funzionalità per mantenere la stabilità del tuo mirror AOSP, usa lo spazio dei nomi come preferisci.

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

    • bug è il numero di bug associato al nuovo contributo del codice. Devi collaborare con il revisore di Google assegnato per determinare il tuo bug. Se l'utilizzo di flag di lancio delle funzionalità per mantenere la stabilità del tuo mirror AOSP, puoi usare il numero di tracciamento dei bug oppure usare <none>.

  3. Salva il file ed esci dall'editor.

Configurare 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 al 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 viene dichiarato il flag.

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

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

    Dove:

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

    La destinazione della build cc_aconfig_library richiama il codegen C o C++, che crea una libreria con il codice generato al momento della creazione.

    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 della build che dipende da questo cc_aconfig_library richiede per alcuni tipi di varianti, potresti dover aggiungere l'impostazione corrispondente nel target della libreria aconfig in 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 una destinazione che utilizza i flag aconfig, come l'esempio seguente 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"],
}

    Dove:

    • shared_libs include 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.

Dichiara 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, l'impostazione di package su foo.bar genera una classe generata automaticamente denominata foo.bar.Flags. In C++, i metodi di accesso ai flag si chiamerebbero foo::bar::"flagname". Flag nella stessa dichiarazione di un file appartiene allo stesso pacchetto, ma più file di dichiarazione possono contribuiscano con l'invio di flag 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 Google assegnato per determinare il tuo spazio dei nomi. Se utilizzi di lancio delle funzionalità per mantenere la stabilità del tuo mirror AOSP, usa lo spazio dei nomi come preferisci.

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

    • bug è il numero di bug associato al nuovo contributo del codice. Devi collaborare con il revisore di Google assegnato per determinare il tuo bug. Se l'utilizzo di flag di lancio delle funzionalità per mantenere la stabilità del tuo mirror AOSP, puoi usare il numero di tracciamento dei bug oppure usare <none>.

  3. Salva il file ed esci dall'editor.

Configurare 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 a:

    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 viene dichiarato il flag.

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

    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 tuo 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 alla build del codice sorgente di scegliere come target libexample_demo_flags_rust per includere la libreria di flag generati dal codice.

  4. Salva il file ed esci dall'editor.