Объявить флаг aconfig

Флаги aconfig можно использовать в коде Java, C, C++ и Rust. Система сборки AOSP запускает инструмент aconfig, используемый для генерации библиотеки методов, специфичных для каждого языка, которые можно использовать для доступа к значению каждого флага. Прежде чем генерировать библиотеку, необходимо объявить флаги и добавить их в сборку.

Объявить флаг aconfig для Java

Чтобы объявить флаг aconfig для Java:

  1. В директории, где находится новый код, создайте файл с расширением .aconfig , например, my_new_aconfig_flag_declarations.aconfig . Файл aconfig — это текстовый протокольный файл, соответствующий стандартной схеме.

  2. Добавьте объявление флага, аналогичное следующему:

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

    Где:

    • package в сочетании с именем флага предоставляет уникальный ключ. В Java установка package в foo.bar приводит к созданию автоматически сгенерированного класса с именем foo.bar.Flags . В C++ методы доступа к флагам будут называться foo::bar::" flagname " . Флаги в одном и том же файле объявления принадлежат одному и тому же пакету, но несколько файлов объявления могут добавлять флаги в один и тот же пакет.

    • container определяет набор кода, который собирается и распространяется вместе в виде бинарного файла. Допустимыми контейнерами являются system , vendor , system_ext , product , name.of.apex и name.of.apk .

    • В name содержится название флага, включающее только строчные буквы, подчеркивания и цифры.

    • namespace содержит пространство имен для внесения вклада. Вам необходимо сотрудничать с назначенным рецензентом Google, чтобы определить свое пространство имен. Если вы используете флаги запуска функций для поддержания стабильности вашего собственного зеркала AOSP, вы можете использовать namespace по своему усмотрению.

    • description содержит краткое описание отмеченной функции или изменения.

    • bug — это номер ошибки, связанный с новым внесенным кодом. Для определения bug вам необходимо сотрудничать с назначенным рецензентом Google. Если вы используете флаги запуска функций для поддержания стабильности вашего собственного зеркала AOSP, вы можете использовать свой номер отслеживания ошибок или <none> .

  3. Сохраните файл и закройте редактор.

Настройте сборку

После объявления флага настройте сборку таким образом, чтобы она могла сгенерировать библиотечный код, используемый для доступа к значению флага.

  1. В файл сборки Android.bp добавьте раздел aconfig_declarations , аналогичный следующему:

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

    Где:

    • name содержит название декларации, включающее только строчные буквы, подчеркивания и цифры.
    • package содержит то же имя пакета, что и в объявлении.
    • srcs содержит имя файла .aconfig , в котором объявлен флаг.

  2. Сохраните файл и закройте редактор.

Объявить флаг aconfig для C и C++

Чтобы объявить флаг aconfig для C и C++:

  1. В директории, где находится новый код, создайте файл с расширением .aconfig , например, my_new_aconfig_flag_declarations.aconfig . Файл aconfig — это текстовый протокольный файл, соответствующий стандартной схеме.

  2. Добавьте объявление флага, аналогичное следующему:

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

    Где:

    • package в сочетании с именем флага предоставляет уникальный ключ. В Java установка package в foo.bar приводит к созданию автоматически сгенерированного класса с именем foo.bar.Flags . В C++ методы доступа к флагам будут называться foo::bar::" flagname " . Флаги в одном и том же файле объявления принадлежат одному и тому же пакету, но несколько файлов объявления могут добавлять флаги в один и тот же пакет.

    • container определяет набор кода, который собирается и распространяется вместе в виде бинарного файла. Допустимыми контейнерами являются system , vendor , system_ext , product , name.of.apex и name.of.apk .

    • В name содержится название флага, включающее только строчные буквы, подчеркивания и цифры.

    • namespace содержит пространство имен для внесения вклада. Вам необходимо сотрудничать с назначенным рецензентом Google, чтобы определить свое пространство имен. Если вы используете флаги запуска функций для поддержания стабильности вашего собственного зеркала AOSP, вы можете использовать namespace по своему усмотрению.

    • description содержит краткое описание отмеченной функции или изменения.

    • bug — это номер ошибки, связанный с новым внесенным кодом. Для определения bug вам необходимо сотрудничать с назначенным рецензентом Google. Если вы используете флаги запуска функций для поддержания стабильности вашего собственного зеркала AOSP, вы можете использовать свой номер отслеживания ошибок или <none> .

  3. Сохраните файл и закройте редактор.

Настройте сборку

После объявления флага настройте сборку таким образом, чтобы она могла сгенерировать библиотечный код, используемый для доступа к значению флага.

  1. В файл сборки Android.bp добавьте раздел aconfig_declarations , аналогичный следующему:

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

    Где:

    • name содержит название декларации, включающее только строчные буквы, подчеркивания и цифры.
    • package содержит то же имя пакета, что и в объявлении.
    • srcs содержит имя файла aconfig, в котором объявлен флаг.

  2. В том же файле создайте целевой объект cc_aconfig_library , аналогичный следующему:

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

    Где:

    • В name содержится название библиотеки, включающее только строчные буквы, подчеркивания и цифры.
    • В aconfig_declarations содержится то же name , что и в объявлении.

    Цель сборки cc_aconfig_library вызывает генератор кода на C или C++, который создает библиотеку с сгенерированным кодом во время сборки.

    Библиотека CC aconfig аналогична целевому объекту библиотеки CC, но имеет такие параметры, как vendor_available , product_available , host_supported и vndk . Если целевой объект сборки, зависящий от этой cc_aconfig_library требует определенных типов вариантов, вам также может потребоваться добавить соответствующую настройку в целевой объект библиотеки CC aconfig. Например, если в родительском целевом объекте сборки параметр vendor_available установлен в true , вам также может потребоваться установить vendor_available в true в этом целевом объекте cc_aconfig_library .

    После добавления этой цели сборки ваш код сможет получить доступ к этой библиотеке. Вы можете включить эту библиотеку, используя синтаксис static_lib или shared_lib . Обратите внимание: если вы хотите добавить эту библиотеку как static_lib , добавьте зависимость shared_lib от server_configurable_flags . Шаг 3 показывает, как включить сгенерированную кодом библиотеку флагов в libexample_cpp_lib .

  3. Создайте целевой объект, использующий флаги aconfig, например, 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"],
}

    Где:

    • shared_libs включает дополнительные зависимости, необходимые для флагов aconfig.
    • static_libs — это имя библиотеки, создаваемой в процессе сборки в соответствии с name в поле cc_aconfig_library на шаге 2. Создав запись cc_library с именем статической библиотеки, вы теперь можете использовать флаги aconfig в своем коде.

Объявить флаг aconfig для Rust

Чтобы объявить флаг aconfig для Rust:

  1. В директории, где находится новый код, создайте файл с расширением .aconfig , например, my_new_aconfig_flag_declarations.aconfig . Файл aconfig — это текстовый протокольный файл, соответствующий стандартной схеме.

  2. Добавьте объявление флага, аналогичное следующему:

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

    Где:

    • package в сочетании с именем флага предоставляет уникальный ключ. В Java установка package в foo.bar приводит к созданию автоматически сгенерированного класса с именем foo.bar.Flags . В C++ методы доступа к флагам будут называться foo::bar::" flagname " . Флаги в одном и том же файле объявления принадлежат одному и тому же пакету, но несколько файлов объявления могут добавлять флаги в один и тот же пакет.

    • container определяет набор кода, который собирается и распространяется вместе в виде бинарного файла. Допустимыми контейнерами являются system , vendor , system_ext , product , name.of.apex и name.of.apk .

    • В name содержится название флага, включающее только строчные буквы, подчеркивания и цифры.

    • namespace содержит пространство имен для внесения вклада. Вам необходимо сотрудничать с назначенным рецензентом Google, чтобы определить свое пространство имен. Если вы используете флаги запуска функций для поддержания стабильности вашего собственного зеркала AOSP, вы можете использовать namespace по своему усмотрению.

    • description содержит краткое описание отмеченной функции или изменения.

    • bug — это номер ошибки, связанный с новым внесенным кодом. Для определения bug вам необходимо сотрудничать с назначенным рецензентом Google. Если вы используете флаги запуска функций для поддержания стабильности вашего собственного зеркала AOSP, вы можете использовать свой номер отслеживания ошибок или <none> .

  3. Сохраните файл и закройте редактор.

Настройте сборку

После объявления флага настройте сборку таким образом, чтобы она могла сгенерировать библиотечный код, используемый для доступа к значению флага.

  1. В файл сборки Android.bp добавьте раздел aconfig_declarations , аналогичный следующему:

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

    Где:

    • name содержит название декларации, включающее только строчные буквы, подчеркивания и цифры.
    • package содержит то же имя пакета, что и в объявлении.
    • srcs содержит имя файла aconfig, в котором объявлен флаг.

  2. Создайте цель rust_aconfig_library аналогичную следующему примеру. Эта цель запускает Rust Codegen и создает библиотеку Rust с сгенерированным кодом во время сборки.

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

    Где:

    • name содержит название декларации, включающее только строчные буквы, подчеркивания и цифры.
    • crate_name содержит то же имя пакета, что и в объявлении.
    • В aconfig_declarations содержится то же name , что и в объявлении.

    Благодаря этому изменению ваш код сможет использовать эту библиотеку Rust.

  3. В том же файле создайте запись rust_library , аналогичную следующей: 

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

    Этот пример позволяет целевым объектам сборки исходного кода libexample_demo_flags_rust включать сгенерированную библиотеку флагов.

  4. Сохраните файл и закройте редактор.