Deklarowanie flagi aconfig

Flagi aconfig możesz stosować w kodzie w językach Java, C, C++ i Rust. System kompilacji AOSP uruchamia narzędzie o nazwie aconfig, które służy do generowania biblioteki metod w określonym języku. Możesz jej używać do uzyskiwania dostępu do wartości każdego z tych sygnałów. Zanim wygenerujesz bibliotekę, musisz zadeklarować flagi i dodać je do kompilacji.

Deklarowanie flagi aconfig w Javie

Aby zadeklarować flagę aconfig w przypadku Javy:

  1. W katalogu, w którym znajduje się nowy kod, utwórz plik z rozszerzeniem .aconfig, np. my_new_aconfig_flag_declarations.aconfig. Plik aconfig to plik tekstowy proto, który jest zgodny ze standardowym schematem.

  2. Dodaj deklarację flagi podobną do tej:

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

    Gdzie:

    • package w połączeniu z nazwą flagi tworzy unikalny klucz. W Javie ustawienie package na foo.bar powoduje automatyczne wygenerowanie klasy o nazwie foo.bar.Flags. W C++ metody dostępu do flagi miałyby nazwę foo::bar::"flagname". Flagi w tym samym pliku deklaracji należą do tego samego pakietu, ale wiele plików deklaracji może zawierać flagi tego samego pakietu.

    • container określa zbiór kodu, który jest kompilowany i dostarczany razem jako plik binarny. Prawidłowe kontenery to system, vendor, system_ext, product, name.of.apex i name.of.apk.

    • name zawiera nazwę flagi, która składa się tylko z małych liter, podkreśleń i cyfr.

    • namespace zawiera przestrzeń nazw dla wpłat. Aby określić przestrzeń nazw, musisz współpracować z przypisanym recenzentem Google. Jeśli używasz flag uruchamiania funkcji, aby zachować stabilność własnego klona AOSP, możesz używać przestrzeni nazw w dowolny sposób.

    • description zawiera krótki opis funkcji lub zmiany, która jest oznaczona.

    • bug to numer błędu powiązany z nowym kodem. Musisz współpracować z przydzielonym recenzentem z Google, aby określić bug. Jeśli używasz flag uruchamiania funkcji, aby zachować stabilność własnej kopii AOSP, możesz użyć numeru śledzenia błędów lub symbolu <none>.

  3. Zapisz plik i zamknij edytor.

Konfigurowanie kompilacji

Po zadeklarowaniu flagi skonfiguruj kompilację tak, aby mogła generować kod biblioteki używany do uzyskiwania dostępu do wartości flagi.

  1. W pliku kompilacji Android.bp dodaj sekcję aconfig_declarations podobną do tej:

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

    Gdzie:

    • name zawiera nazwę deklaracji, która składa się tylko z małych liter, podkreśleń i cyfr.
    • package zawiera tę samą nazwę pakietu, która została użyta w deklaracji.
    • srcs zawiera nazwę pliku .aconfig, w którym zadeklarowano flagę.

  2. Zapisz plik i zamknij edytor.

Deklarowanie flagi aconfig dla języków C i C++

Aby zadeklarować flagę aconfig w przypadku języków C i C++:

  1. W katalogu, w którym znajduje się nowy kod, utwórz plik z rozszerzeniem .aconfig, np. my_new_aconfig_flag_declarations.aconfig. Plik aconfig to plik tekstowy proto, który jest zgodny ze standardowym schematem.

  2. Dodaj deklarację flagi podobną do tej:

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

    Gdzie:

    • package w połączeniu z nazwą flagi tworzy unikalny klucz. W Javie ustawienie package na foo.bar powoduje automatyczne wygenerowanie klasy o nazwie foo.bar.Flags. W C++ metody dostępu do flagi miałyby nazwę foo::bar::"flagname". Flagi w tym samym pliku deklaracji należą do tego samego pakietu, ale wiele plików deklaracji może zawierać flagi tego samego pakietu.

    • container określa zbiór kodu, który jest kompilowany i dostarczany razem jako plik binarny. Prawidłowe kontenery to system, vendor, system_ext, product, name.of.apex i name.of.apk.

    • name zawiera nazwę flagi, która składa się tylko z małych liter, podkreśleń i cyfr.

    • namespace zawiera przestrzeń nazw dla wpłat. Aby określić przestrzeń nazw, musisz współpracować z przypisanym recenzentem Google. Jeśli używasz flag uruchamiania funkcji, aby zachować stabilność własnego klona AOSP, możesz używać przestrzeni nazw w dowolny sposób.

    • description zawiera krótki opis funkcji lub zmiany, która jest oznaczona.

    • bug to numer błędu powiązany z nowym kodem. Musisz współpracować z przydzielonym recenzentem z Google, aby określić bug. Jeśli używasz flag uruchamiania funkcji, aby zachować stabilność własnej kopii AOSP, możesz użyć numeru śledzenia błędów lub symbolu <none>.

  3. Zapisz plik i zamknij edytor.

Konfigurowanie kompilacji

Po zadeklarowaniu flagi skonfiguruj kompilację tak, aby mogła generować kod biblioteki używany do uzyskiwania dostępu do wartości flagi.

  1. W pliku kompilacji Android.bp dodaj sekcję aconfig_declarations podobną do tej:

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

    Gdzie:

    • name zawiera nazwę deklaracji, która składa się tylko z małych liter, podkreśleń i cyfr.
    • package zawiera tę samą nazwę pakietu, która została użyta w deklaracji.
    • srcs zawiera nazwę pliku aconfig, w którym zadeklarowano flagę.

  2. W tym samym pliku utwórz element cc_aconfig_library podobny do tego:

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

    Gdzie:

    • name zawiera nazwę biblioteki, która składa się tylko z małych liter, podkreśleń i cyfr.
    • aconfig_declarations zawiera ten sam name, który został użyty w deklaracji.

    cc_aconfig_libraryCel kompilacji wywołuje generowanie kodu w C lub C++, które tworzy bibliotekę z wygenerowanym kodem w czasie kompilacji.

    Biblioteka CC aconfig jest podobna do biblioteki CC, ale ma opcje takie jak vendor_available, product_available, host_supported i vndk. Jeśli cel kompilacji zależny od tego cc_aconfig_library wymaga określonego typu wariantów, może być też konieczne dodanie odpowiedniego ustawienia w celu biblioteki CC aconfig. Jeśli na przykład w przypadku nadrzędnego celu kompilacji parametr vendor_available ma wartość true, w tym celu cc_aconfig_library możesz też ustawić parametr vendor_available na wartość true.

    Po dodaniu tego celu kompilacji Twój kod będzie miał dostęp do tej biblioteki. Możesz dołączyć tę bibliotekę za pomocą składni static_lib lub shared_lib. Jeśli chcesz dodać tę bibliotekę jako static_lib, dodaj zależność shared_lib od server_configurable_flags. Krok 3 pokazuje, jak włączyć bibliotekę flag wygenerowanego kodu do libexample_cpp_lib.

  3. Utwórz środowisko docelowe, które korzysta z flag aconfig, np. tak jak w tym przykładzie: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"],
}

    Gdzie:

    • shared_libs zawiera dodatkowe zależności wymagane w przypadku flag aconfig.
    • static_libs to nazwa biblioteki utworzonej przez kompilację zgodnie z polem cc_aconfig_library name w kroku 2. Tworząc wpis cc_library z nazwą biblioteki statycznej, możesz teraz używać w kodzie flag aconfig.

Deklarowanie flagi aconfig w Rust

Aby zadeklarować flagę aconfig dla języka Rust:

  1. W katalogu, w którym znajduje się nowy kod, utwórz plik z rozszerzeniem .aconfig, np. my_new_aconfig_flag_declarations.aconfig. Plik aconfig to plik tekstowy proto, który jest zgodny ze standardowym schematem.

  2. Dodaj deklarację flagi podobną do tej:

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

    Gdzie:

    • package w połączeniu z nazwą flagi tworzy unikalny klucz. W Javie ustawienie package na foo.bar powoduje automatyczne wygenerowanie klasy o nazwie foo.bar.Flags. W C++ metody dostępu do flagi miałyby nazwę foo::bar::"flagname". Flagi w tym samym pliku deklaracji należą do tego samego pakietu, ale wiele plików deklaracji może zawierać flagi tego samego pakietu.

    • container określa zbiór kodu, który jest kompilowany i dostarczany razem jako plik binarny. Prawidłowe kontenery to system, vendor, system_ext, product, name.of.apex i name.of.apk.

    • name zawiera nazwę flagi, która składa się tylko z małych liter, podkreśleń i cyfr.

    • namespace zawiera przestrzeń nazw dla wpłat. Aby określić przestrzeń nazw, musisz współpracować z przypisanym recenzentem Google. Jeśli używasz flag uruchamiania funkcji, aby zachować stabilność własnego klona AOSP, możesz używać przestrzeni nazw w dowolny sposób.

    • description zawiera krótki opis funkcji lub zmiany, która jest oznaczona.

    • bug to numer błędu powiązany z nowym kodem. Musisz współpracować z przydzielonym recenzentem z Google, aby określić bug. Jeśli używasz flag uruchamiania funkcji, aby zachować stabilność własnej kopii AOSP, możesz użyć numeru śledzenia błędów lub symbolu <none>.

  3. Zapisz plik i zamknij edytor.

Konfigurowanie kompilacji

Po zadeklarowaniu flagi skonfiguruj kompilację tak, aby mogła generować kod biblioteki używany do uzyskiwania dostępu do wartości flagi.

  1. W pliku kompilacji Android.bp dodaj sekcję aconfig_declarations podobną do tej:

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

    Gdzie:

    • name zawiera nazwę deklaracji, która składa się tylko z małych liter, podkreśleń i cyfr.
    • package zawiera tę samą nazwę pakietu, która została użyta w deklaracji.
    • srcs zawiera nazwę pliku aconfig, w którym zadeklarowano flagę.

  2. Utwórz rust_aconfig_library podobne do tego w przykładzie poniżej. Ten cel wywołuje Rust Codegen i tworzy bibliotekę Rust z wygenerowanym kodem w czasie kompilacji.

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

    Gdzie:

    • name zawiera nazwę deklaracji, która składa się tylko z małych liter, podkreśleń i cyfr.
    • crate_name zawiera tę samą nazwę pakietu, która została użyta w deklaracji.
    • aconfig_declarations zawiera ten sam name, który został użyty w deklaracji.

    Dzięki tej zmianie Twój kod może zależeć od tej biblioteki Rusta.

  3. W tym samym pliku utwórz wpis rust_library podobny do tego:

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

    Ten przykład umożliwia uwzględnienie w docelowych kompilacjach kodu źródłowego libexample_demo_flags_rust biblioteki flag wygenerowanego kodu.

  4. Zapisz plik i zamknij edytor.