Внедрить библиотеку Java SDK

Платформа Android содержит большое количество общих библиотек Java, которые могут быть опционально включены в classpath приложений с тегом <uses-library> в манифесте приложения. Приложения ссылаются на эти библиотеки, поэтому относитесь к ним как к остальной части API Android с точки зрения совместимости, обзора API и поддержки инструментов. Однако следует отметить, что большинство библиотек не имеют этих функций.

Тип модуля java_sdk_library помогает управлять библиотеками такого рода. Производители устройств могут использовать этот механизм для своих собственных общих библиотек Java, чтобы поддерживать обратную совместимость для своих API. Если производители устройств используют свои собственные общие библиотеки Java через тег <uses-library> вместо пути bootclass, java_sdk_library может проверить, что эти библиотеки Java являются API-стабильными.

java_sdk_library реализует необязательные API SDK для использования приложениями. Библиотеки, реализованные через java_sdk_library в вашем файле сборки ( Android.bp ), выполняют следующие операции:

• Библиотеки заглушек генерируются для включения stubs , stubs.system и stubs.test . Эти библиотеки заглушек создаются путем распознавания аннотаций @hide , @SystemApi и @TestApi .
• java_sdk_library управляет файлами спецификации API (например, current.txt ) в подкаталоге API. Эти файлы проверяются на соответствие последнему коду, чтобы убедиться, что они являются самыми последними версиями. Если это не так, вы получите сообщение об ошибке, в котором объясняется, как их обновить. Вручную просмотрите все изменения обновлений, чтобы убедиться, что они соответствуют вашим ожиданиям.
  
  Чтобы обновить все API, используйте m update-api . Чтобы проверить актуальность API, используйте m checkapi .
• Файлы спецификации API проверяются на соответствие последним опубликованным версиям Android, чтобы гарантировать обратную совместимость API с более ранними выпусками. Модули java_sdk_library , предоставляемые как часть AOSP, размещают свои ранее выпущенные версии в prebuilts/sdk/<latest number> .
• Что касается проверки файлов спецификации API, вы можете выполнить одно из следующих трех действий:
• Разрешите проверкам продолжиться. (Ничего не делайте.)
• Отключите проверки, добавив в java_sdk_library следующее:
  unsafe_ignore_missing_latest_api: true,
• Предоставьте пустые API для новых модулей java_sdk_library , создав пустые текстовые файлы с именами module_name.txt в каталоге version/scope/api .
• Если установлена ​​библиотека реализации для среды выполнения, генерируется и устанавливается XML-файл.

Как работает java_sdk_library

Библиотека java_sdk_library с именем X создает следующее:

1. Две копии библиотеки реализации: одна библиотека называется X , а другая называется X.impl . Библиотека X установлена ​​на устройстве. Библиотека X.impl присутствует только в том случае, если другим модулям требуется явный доступ к библиотеке реализации, например, для использования при тестировании. Обратите внимание, что явный доступ требуется редко.
2. Области действия можно включать и отключать для настройки доступа. (Подобно модификаторам доступа по ключевым словам Java, публичная область действия обеспечивает широкий диапазон доступа; тестовая область действия содержит API, используемые только при тестировании.) Для каждой включенной области действия библиотека создает следующее:
• Исходный модуль заглушек (типа модуля droidstubs ) — потребляет исходный код реализации и выводит набор исходных кодов заглушек вместе с файлом спецификации API.
• Библиотека заглушек (типа модуля java_library ) — это скомпилированная версия заглушек. Библиотеки, используемые для компиляции, не совпадают с теми, которые поставляются в java_sdk_library , что гарантирует, что детали реализации не попадут в заглушки API.
• Если вам нужны дополнительные библиотеки для компиляции заглушек, используйте свойства stub_only_libs и stub_only_static_libs для их предоставления.

Если java_sdk_library называется « X » и компилируется как « X », всегда называйте его так и не изменяйте его. Сборка выберет подходящую библиотеку. Чтобы убедиться, что у вас самая подходящая библиотека, проверьте свои заглушки, чтобы увидеть, не внесла ли сборка ошибки. Внесите необходимые исправления, следуя этим рекомендациям:

• Убедитесь, что у вас есть соответствующая библиотека, просмотрев командную строку и проверив, какие заглушки там перечислены, чтобы определить область действия:
• Область действия слишком широка: Зависимая библиотека нуждается в определенном объеме API. Но вы видите API, включенные в библиотеку, которые выходят за рамки этого объема, например системные API, включенные в публичные API.
• Область действия слишком узкая: Зависимая библиотека не имеет доступа ко всем необходимым библиотекам. Например, зависимая библиотека должна использовать системный API, но вместо этого получает публичный API. Обычно это приводит к ошибке компиляции, поскольку необходимые API отсутствуют.
• Чтобы исправить библиотеку, выполните только одно из следующих действий:
• Измените sdk_version , чтобы выбрать нужную вам версию. ИЛИ
• Явно укажите соответствующую библиотеку, например <X>.stubs или <X>.stubs.system .

Использование java_sdk_library X

Библиотека реализации X используется, когда на нее ссылаются из apex.java_libs . Однако из-за ограничения Сунга, когда на библиотеку X ссылаются из другого модуля java_sdk_library в той же библиотеке APEX, необходимо явно использовать X.impl , а не библиотеку X .

Когда java_sdk_library ссылается из другого места, используется библиотека заглушек. Библиотека заглушек выбирается в соответствии с настройкой свойства sdk_version зависимого модуля. Например, модуль, который указывает sdk_version: "current" , использует публичные заглушки, тогда как модуль, который указывает sdk_version: "system_current" использует системные заглушки. Если точное совпадение найти не удается, используется ближайшая библиотека заглушек. java_sdk_library , которая предоставляет только публичный API, будет предоставлять публичные заглушки для всех.

Примеры и источники

Свойства srcs и api_packages должны присутствовать в java_sdk_library .

java_sdk_library {
        name: "com.android.future.usb.accessory",
        srcs: ["src/**/*.java"],
        api_packages: ["com.android.future.usb"],
    }

AOSP рекомендует (но не требует), чтобы новые экземпляры java_sdk_library явно включали области API, которые они хотят использовать. Вы также можете (опционально) перенести существующие экземпляры java_sdk_library , чтобы явно включить области API, которые они будут использовать:

java_sdk_library {
         name: "lib",
         public: {
           enabled: true,
         },
         system: {
           enabled: true,
         },
         …
    }

Чтобы настроить библиотеку impl , используемую для среды выполнения, используйте все обычные свойства java_library , такие как hostdex , compile_dex и errorprone .

java_sdk_library {
        name: "android.test.base",

        srcs: ["src/**/*.java"],

        errorprone: {
          javacflags: ["-Xep:DepAnn:ERROR"],
        },

        hostdex: true,

        api_packages: [
            "android.test",
            "android.test.suitebuilder.annotation",
            "com.android.internal.util",
            "junit.framework",
        ],

        compile_dex: true,
    }

Для настройки библиотек-заглушек используйте следующие свойства:

• merge_annotations_dirs и merge_inclusion_annotations_dirs .
• api_srcs : список необязательных исходных файлов, которые являются частью API, но не частью библиотеки времени выполнения.
• stubs_only_libs : список библиотек Java, которые находятся в classpath при создании заглушек.
• hidden_api_packages : Список имен пакетов, которые необходимо скрыть от API.
• droiddoc_options : Дополнительный аргумент для metalava .
• droiddoc_option_files : выводит список файлов, на которые можно ссылаться из droiddoc_options , используя $(location <label>) , где <file> — это запись в списке.
• annotations_enabled .

java_sdk_library — это java_library , но это не модуль droidstubs , поэтому он не поддерживает все свойства droidstubs . Следующий пример взят из файла сборки библиотеки android.test.mock .

java_sdk_library {
        name: "android.test.mock",

        srcs: [":android-test-mock-sources"],
        api_srcs: [
            // Note: The following aren’t APIs of this library. Only APIs under the
            // android.test.mock package are taken. These do provide private APIs
            // to which android.test.mock APIs reference. These classes are present
            // in source code form to access necessary comments that disappear when
            // the classes are compiled into a Jar library.
            ":framework-core-sources-for-test-mock",
            ":framework_native_aidl",
        ],

        libs: [
            "framework",
            "framework-annotations-lib",
            "app-compat-annotations",
            "Unsupportedappusage",
        ],

        api_packages: [
            "android.test.mock",
        ],
        permitted_packages: [
            "android.test.mock",
        ],
        compile_dex: true,
        default_to_stubs: true,
    }

Поддерживать обратную совместимость

Система сборки проверяет, поддерживают ли API обратную совместимость, сравнивая последние файлы API с сгенерированными файлами API во время сборки. java_sdk_library выполняет проверку совместимости, используя информацию, предоставленную prebuilt_apis . Все библиотеки, собранные с помощью java_sdk_library , должны иметь файлы API в последней версии api_dirs в prebuilt_apis . Когда вы выпускаете версию, списки файлов API и библиотеки заглушек можно получить с помощью dist build с PRODUCT=sdk_phone_armv7-sdk .

Свойство api_dirs — это список каталогов версий API в prebuilt_apis . Каталоги версий API должны располагаться на уровне каталога Android.bp .

prebuilt_apis {
       name: "foo",
       api_dirs: [
           "1",
           "2",
             ....
           "30",
           "current",
       ],
    }

Настройте каталоги со структурой version / scope /api/ в каталоге prebuilds. version соответствует уровню API, а scope определяет, является ли каталог общедоступным, системным или тестовым.

• version / scope содержит библиотеки Java.
• version / scope /api содержит файлы API .txt . Создайте здесь пустые текстовые файлы с именами module_name .txt и module_name -removed.txt .

   ├── 30
   │   ├── public
   │   │   ├── api
   │   │   │   ├── android.test.mock-removed.txt
   │   │   │   └── android.test.mock.txt
   │   │   └── android.test.mock.jar
   │   ├── system
   │   │   ├── api
   │   │   │   ├── android.test.mock-removed.txt
   │   │   │   └── android.test.mock.txt
   │   │   └── android.test.mock.jar
   │   └── test
   │       ├── api
   │       │   ├── android.test.mock-removed.txt
   │       │   └── android.test.mock.txt
   │       └── android.test.mock.jar
   └── Android.bp