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

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

Тип модуля java_sdk_library помогает управлять библиотеками такого типа. Производители устройств могут использовать этот механизм для своих собственных общих библиотек Java, чтобы обеспечить обратную совместимость своих API. Если производители устройств используют свои собственные общие библиотеки Java через тег <uses-library> вместо пути к загрузочному классу, 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, которые находятся в пути к классам при создании заглушек.
• hidden_api_packages : список имен пакетов, которые должны быть скрыты от API.
• droiddoc_options : дополнительный аргумент для металавы .
• 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 с помощью 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/ в каталоге prebuilts. 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