Aconfig-Flag deklarieren

Sie können aconfig-Flags in Java-, C-, C++- und Rust-Code verwenden. Das AOSP-Build-System startet das Tool „aconfig“, mit dem eine sprachspezifische Bibliothek mit Methoden generiert wird, mit denen Sie auf den Wert der einzelnen Flags zugreifen können. Bevor Sie die Bibliothek generieren können, müssen Sie Flags deklarieren und dem Build hinzufügen.

Aconfig-Flag für Java deklarieren

So deklarieren Sie ein aconfig-Flag für Java:

  1. Erstellen Sie in einem Verzeichnis, in dem sich der neue Code befindet, eine Datei mit der Erweiterung .aconfig, z. B. my_new_aconfig_flag_declarations.aconfig. Eine „aconfig“-Datei ist eine Text-Proto-Datei, die einem Standardschema folgt.

  2. Fügen Sie eine Flag-Deklaration ähnlich der folgenden hinzu:

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

    Dabei gilt:

    • package ergibt in Kombination mit dem Flag-Namen einen eindeutigen Schlüssel. Wenn Sie in Java package auf foo.bar festlegen, wird automatisch eine Klasse mit dem Namen foo.bar.Flags generiert. In C++ würden Flag-Accessor-Methoden foo::bar::"flagname" heißen. Flags in derselben Deklarationsdatei gehören zum selben Paket. Mehrere Deklarationsdateien können jedoch Flags zum selben Paket beitragen.

    • container definiert eine Sammlung von Code, der zusammen als Binärdatei erstellt und ausgeliefert wird. Gültige Container sind system, vendor, system_ext, product, name.of.apex und name.of.apk.

    • name enthält den Namen des Flags, der nur Kleinbuchstaben, Unterstriche und Zahlen enthält.

    • namespace enthält den Namespace für Beiträge. Sie müssen mit dem zugewiesenen Google-Prüfer zusammenarbeiten, um Ihren Namespace zu ermitteln. Wenn Sie Feature-Launch-Flags verwenden, um die Stabilität Ihres eigenen AOSP-Mirrors zu gewährleisten, können Sie den Namespace beliebig verwenden.

    • description enthält eine kurze Beschreibung der Funktion oder Änderung, die gekennzeichnet ist.

    • bug ist die Fehlernummer, die mit dem neuen Codebeitrag verknüpft ist. Sie müssen mit dem zugewiesenen Google-Prüfer zusammenarbeiten, um Ihre bug zu ermitteln. Wenn Sie Feature-Launch-Flags verwenden, um die Stabilität Ihres eigenen AOSP-Mirrors zu gewährleisten, können Sie Ihre Bug-Tracking-Nummer oder <none> verwenden.

  3. Speichern Sie die Datei und beenden Sie den Editor.

Build einrichten

Nachdem Sie das Flag deklariert haben, richten Sie den Build so ein, dass der Bibliothekscode generiert werden kann, mit dem auf den Wert des Flags zugegriffen wird.

  1. Fügen Sie in Ihrer Android.bp-Build-Datei einen aconfig_declarations-Abschnitt ähnlich dem folgenden hinzu:

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

    Dabei gilt:

    • name enthält den Namen der Deklaration, der nur Kleinbuchstaben, Unterstriche und Zahlen enthält.
    • package enthält denselben Paketnamen, der in der Deklaration verwendet wird.
    • srcs enthält den Namen der .aconfig-Datei, in der das Flag deklariert ist.

  2. Speichern Sie die Datei und beenden Sie den Editor.

Aconfig-Flag für C und C++ deklarieren

So deklarieren Sie ein aconfig-Flag für C und C++:

  1. Erstellen Sie in einem Verzeichnis, in dem sich der neue Code befindet, eine Datei mit der Erweiterung .aconfig, z. B. my_new_aconfig_flag_declarations.aconfig. Eine „aconfig“-Datei ist eine Text-Proto-Datei, die einem Standardschema folgt.

  2. Fügen Sie eine Flag-Deklaration ähnlich der folgenden hinzu:

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

    Dabei gilt:

    • package ergibt in Kombination mit dem Flag-Namen einen eindeutigen Schlüssel. Wenn Sie in Java package auf foo.bar festlegen, wird automatisch eine Klasse mit dem Namen foo.bar.Flags generiert. In C++ würden Flag-Accessor-Methoden foo::bar::"flagname" heißen. Flags in derselben Deklarationsdatei gehören zum selben Paket. Mehrere Deklarationsdateien können jedoch Flags zum selben Paket beitragen.

    • container definiert eine Sammlung von Code, der zusammen als Binärdatei erstellt und ausgeliefert wird. Gültige Container sind system, vendor, system_ext, product, name.of.apex und name.of.apk.

    • name enthält den Namen des Flags, der nur Kleinbuchstaben, Unterstriche und Zahlen enthält.

    • namespace enthält den Namespace für Beiträge. Sie müssen mit dem zugewiesenen Google-Prüfer zusammenarbeiten, um Ihren Namespace zu ermitteln. Wenn Sie Feature-Launch-Flags verwenden, um die Stabilität Ihres eigenen AOSP-Mirrors zu gewährleisten, können Sie den Namespace beliebig verwenden.

    • description enthält eine kurze Beschreibung der Funktion oder Änderung, die gekennzeichnet ist.

    • bug ist die Fehlernummer, die mit dem neuen Codebeitrag verknüpft ist. Sie müssen mit dem zugewiesenen Google-Prüfer zusammenarbeiten, um Ihre bug zu ermitteln. Wenn Sie Feature-Launch-Flags verwenden, um die Stabilität Ihres eigenen AOSP-Mirrors zu gewährleisten, können Sie Ihre Bug-Tracking-Nummer oder <none> verwenden.

  3. Speichern Sie die Datei und beenden Sie den Editor.

Build einrichten

Nachdem Sie das Flag deklariert haben, richten Sie den Build so ein, dass der Bibliothekscode generiert werden kann, mit dem auf den Wert des Flags zugegriffen wird.

  1. Fügen Sie in Ihrer Android.bp-Build-Datei einen aconfig_declarations-Abschnitt ähnlich dem folgenden hinzu:

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

    Dabei gilt:

    • name enthält den Namen der Deklaration, der nur Kleinbuchstaben, Unterstriche und Zahlen enthält.
    • package enthält denselben Paketnamen, der in der Deklaration verwendet wird.
    • srcs enthält den Namen der aconfig-Datei, in der das Flag deklariert ist.

  2. Erstellen Sie in derselben Datei ein cc_aconfig_library-Ziel, das dem folgenden ähnelt:

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

    Dabei gilt:

    • name enthält den Namen der Bibliothek, die nur Kleinbuchstaben, Unterstriche und Zahlen enthält.
    • aconfig_declarations enthält denselben name, der in der Erklärung verwendet wird.

    Das Build-Ziel cc_aconfig_library ruft die C- oder C++-Codegenerierung auf, wodurch zur Build-Zeit eine Bibliothek mit dem generierten Code erstellt wird.

    Die CC-Aconfig-Bibliothek ähnelt einem CC-Bibliotheksziel, hat aber Optionen wie vendor_available, product_available, host_supported und vndk. Wenn für das Build-Ziel, das von diesem cc_aconfig_library abhängt, bestimmte Varianten erforderlich sind, müssen Sie möglicherweise auch die entsprechende Einstellung im CC-Aconfig-Bibliotheksziel hinzufügen. Wenn beispielsweise für das übergeordnete Build-Ziel vendor_available auf true festgelegt ist, sollten Sie vendor_available auch für dieses cc_aconfig_library-Ziel auf true festlegen.

    Nachdem Sie dieses Build-Ziel hinzugefügt haben, kann Ihr Code auf diese Bibliothek zugreifen. Sie können diese Bibliothek mit der Syntax static_lib oder shared_lib einbinden. Wenn Sie diese Bibliothek als static_lib hinzufügen möchten, fügen Sie eine shared_lib-Abhängigkeit von server_configurable_flags hinzu. In Schritt 3 wird gezeigt, wie Sie die Bibliothek mit dem Flag für generierten Code in libexample_cpp_lib einfügen.

  3. Erstellen Sie ein Ziel, das die aconfig-Flags verwendet, z. B. das folgende Beispiel 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"],
}

    Dabei gilt:

    • shared_libs enthält zusätzliche Abhängigkeiten, die für aconfig-Flags erforderlich sind.
    • static_libs ist der Name der Bibliothek, die vom Build gemäß dem Feld cc_aconfig_library name in Schritt 2 erstellt wird. Wenn Sie einen cc_library-Eintrag mit dem Namen der statischen Bibliothek erstellen, können Sie die aconfig-Flags in Ihrem Code verwenden.

aconfig-Flag für Rust deklarieren

So deklarieren Sie ein aconfig-Flag für Rust:

  1. Erstellen Sie in einem Verzeichnis, in dem sich der neue Code befindet, eine Datei mit der Erweiterung .aconfig, z. B. my_new_aconfig_flag_declarations.aconfig. Eine „aconfig“-Datei ist eine Text-Proto-Datei, die einem Standardschema folgt.

  2. Fügen Sie eine Flag-Deklaration ähnlich der folgenden hinzu:

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

    Dabei gilt:

    • package ergibt in Kombination mit dem Flag-Namen einen eindeutigen Schlüssel. Wenn Sie in Java package auf foo.bar festlegen, wird automatisch eine Klasse mit dem Namen foo.bar.Flags generiert. In C++ würden Flag-Accessor-Methoden foo::bar::"flagname" heißen. Flags in derselben Deklarationsdatei gehören zum selben Paket. Mehrere Deklarationsdateien können jedoch Flags zum selben Paket beitragen.

    • container definiert eine Sammlung von Code, der zusammen als Binärdatei erstellt und ausgeliefert wird. Gültige Container sind system, vendor, system_ext, product, name.of.apex und name.of.apk.

    • name enthält den Namen des Flags, der nur Kleinbuchstaben, Unterstriche und Zahlen enthält.

    • namespace enthält den Namespace für Beiträge. Sie müssen mit dem zugewiesenen Google-Prüfer zusammenarbeiten, um Ihren Namespace zu ermitteln. Wenn Sie Feature-Launch-Flags verwenden, um die Stabilität Ihres eigenen AOSP-Mirrors zu gewährleisten, können Sie den Namespace beliebig verwenden.

    • description enthält eine kurze Beschreibung der Funktion oder Änderung, die gekennzeichnet ist.

    • bug ist die Fehlernummer, die mit dem neuen Codebeitrag verknüpft ist. Sie müssen mit dem zugewiesenen Google-Prüfer zusammenarbeiten, um Ihre bug zu ermitteln. Wenn Sie Feature-Launch-Flags verwenden, um die Stabilität Ihres eigenen AOSP-Mirrors zu gewährleisten, können Sie Ihre Bug-Tracking-Nummer oder <none> verwenden.

  3. Speichern Sie die Datei und beenden Sie den Editor.

Build einrichten

Nachdem Sie das Flag deklariert haben, richten Sie den Build so ein, dass der Bibliothekscode generiert werden kann, mit dem auf den Wert des Flags zugegriffen wird.

  1. Fügen Sie in Ihrer Android.bp-Build-Datei einen aconfig_declarations-Abschnitt ähnlich dem folgenden hinzu:

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

    Dabei gilt:

    • name enthält den Namen der Deklaration, der nur Kleinbuchstaben, Unterstriche und Zahlen enthält.
    • package enthält denselben Paketnamen, der in der Deklaration verwendet wird.
    • srcs enthält den Namen der aconfig-Datei, in der das Flag deklariert ist.

  2. Erstellen Sie ein rust_aconfig_library-Zielvorhaben ähnlich dem folgenden Beispiel. Dieses Ziel ruft Rust Codegen auf und erstellt während der Build-Zeit eine Rust-Bibliothek mit dem generierten Code.

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

    Dabei gilt:

    • name enthält den Namen der Deklaration, der nur Kleinbuchstaben, Unterstriche und Zahlen enthält.
    • crate_name enthält denselben Paketnamen, der in der Deklaration verwendet wird.
    • aconfig_declarations enthält denselben name, der in der Erklärung verwendet wird.

    Durch diese Änderung kann Ihr Code von dieser Rust-Bibliothek abhängen.

  3. Erstellen Sie in derselben Datei einen rust_library-Eintrag, der dem folgenden ähnelt:

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

    In diesem Beispiel können die Build-Ziele für Ihren Quellcode libexample_demo_flags_rust die Bibliothek mit dem Flag für generierten Code enthalten.

  4. Speichern Sie die Datei und beenden Sie den Editor.