Dichiarare un flag aconfig

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

Dichiarare 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 sarebbero denominati foo::bar::"flagname". I flag nello stesso file di dichiarazione appartengono allo stesso pacchetto, ma più file di dichiarazione possono contribuire con flag allo stesso pacchetto.

    • container definisce una raccolta di codice compilato e spedito insieme come 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 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 di bug associato al nuovo contributo di codice. Devi collaborare con il revisore 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 build 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, l'impostazione di package su foo.bar genera una classe generata automaticamente denominata foo.bar.Flags. In C++, i metodi di accesso ai flag sarebbero denominati foo::bar::"flagname". I flag nello stesso file di dichiarazione appartengono allo stesso pacchetto, ma più file di dichiarazione possono contribuire con flag allo stesso pacchetto.

    • container definisce una raccolta di codice compilato e spedito insieme come 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 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 di bug associato al nuovo contributo di codice. Devi collaborare con il revisore 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 build 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 C o C++ Codegen, che crea una libreria con il codice generato al momento della build.

    La libreria CC aconfig è simile a una libreria CC di destinazione, ma ha opzioni come vendor_available, product_available, host_supported e vndk. Se la build di destinazione dipende da questo cc_aconfig_library richiede un determinato tipo di varianti, potresti anche dover aggiungere l'impostazione corrispondente nella libreria di configurazione CC. Ad esempio, se la build di destinazione principale ha vendor_available impostato su true, potresti anche impostare vendor_available su true in questa destinazione cc_aconfig_library.

    Dopo aver aggiunto questo target di build, il tuo codice può accedere a questa libreria. Puoi includere questa libreria utilizzando la sintassi static_lib o shared_lib. Se vuoi aggiungere questa libreria come static_lib, aggiungi una dipendenza shared_lib da server_configurable_flags. Il passaggio 3 mostra come includere la libreria dei flag di codice generato in libexample_cpp_lib.

  3. Crea una destinazione che utilizzi i flag aconfig, come il seguente esempio 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 build 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 tuo 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, l'impostazione di package su foo.bar genera una classe generata automaticamente denominata foo.bar.Flags. In C++, i metodi di accesso ai flag sarebbero denominati foo::bar::"flagname". I flag nello stesso file di dichiarazione appartengono allo stesso pacchetto, ma più file di dichiarazione possono contribuire con flag allo stesso pacchetto.

    • container definisce una raccolta di codice compilato e spedito insieme come 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 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 di bug associato al nuovo contributo di codice. Devi collaborare con il revisore 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 build 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 successivo. Questo target richiama 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 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 alle destinazioni di build del codice sorgente libexample_demo_flags_rust di includere la libreria di flag generati dal codice.

  4. Salva il file ed esci dall'editor.