La plataforma Android contiene una gran cantidad de bibliotecas Java compartidas que, opcionalmente, se pueden incluir en la ruta de clase de las aplicaciones con la etiqueta <uses-library>
en el manifiesto de la aplicación. Las aplicaciones se vinculan con estas bibliotecas, así que trátelas como el resto de la API de Android en términos de compatibilidad, revisión de API y soporte de herramientas. Tenga en cuenta, sin embargo, que la mayoría de las bibliotecas no tienen estas características.
El tipo de módulo java_sdk_library
ayuda a administrar bibliotecas de este tipo. Los fabricantes de dispositivos pueden usar este mecanismo para sus propias bibliotecas Java compartidas, para mantener la compatibilidad con versiones anteriores de sus API. Si los fabricantes de dispositivos usan sus propias bibliotecas de Java compartidas a través de la etiqueta <uses-library>
en lugar de la ruta de la clase de arranque, java_sdk_library
puede verificar que esas bibliotecas de Java sean API estables.
java_sdk_library
implementa API de SDK opcionales para que las usen las aplicaciones. Las bibliotecas implementadas a través de java_sdk_library
en su archivo de compilación ( Android.bp
) realizan las siguientes operaciones:
- Las bibliotecas de stubs se generan para incluir
stubs
,stubs.system
ystubs.test
. Estas bibliotecas de stubs se crean reconociendo@hide
,@SystemApi
y@TestApi
. -
java_sdk_library
administra archivos de especificación de API (comocurrent.txt
) en un subdirectorio de API. Estos archivos se comparan con el código más reciente para garantizar que sean las versiones más recientes. Si no lo están, recibirá un mensaje de error que explica cómo actualizarlos. Revise manualmente todos los cambios de actualización para asegurarse de que coincidan con sus expectativas.
Para actualizar todas las API, usem update-api
. Para verificar que una API esté actualizada, usem checkapi
. - Los archivos de especificación de API se comparan con las versiones de Android publicadas más recientemente para garantizar que la API sea compatible con versiones anteriores. Los módulos
java_sdk_library
proporcionados como parte de AOSP colocan sus versiones publicadas anteriormente enprebuilts/sdk/<latest number>
. - Con respecto a las comprobaciones de los archivos de especificación de API, puede hacer una de las siguientes tres cosas:
- Permita que los cheques continúen. (No hagas nada.)
- Deshabilite las comprobaciones agregando lo siguiente a
java_sdk_library
:
unsafe_ignore_missing_latest_api: true,
- Proporcione API vacías para los nuevos módulos
java_sdk_library
creando archivos de texto vacíos denominadosmodule_name.txt
en el directorioversion/scope/api
. - Si la biblioteca de implementación para el tiempo de ejecución está instalada, se genera e instala un archivo XML.
Cómo funciona java_sdk_library
Una java_sdk_library
llamada X
crea lo siguiente:
- Dos copias de la biblioteca de implementación: una biblioteca llamada
X
y otra llamadaX.impl
. La bibliotecaX
está instalada en el dispositivo. La bibliotecaX.impl
está allí solo si otros módulos necesitan acceso explícito a la biblioteca de implementación, como para usar en pruebas. Tenga en cuenta que rara vez se necesita acceso explícito. - Los ámbitos se pueden habilitar y deshabilitar para personalizar el acceso. (Al igual que los modificadores de acceso de palabras clave de Java, un ámbito público proporciona una amplia gama de acceso; un ámbito de prueba contiene API que solo se utilizan en las pruebas). Para cada ámbito habilitado, la biblioteca crea lo siguiente:
- Un módulo fuente de stubs (del tipo de módulo
droidstubs
): consume la fuente de implementación y genera un conjunto de fuentes de stub junto con el archivo de especificación API. - Una biblioteca de stubs (del tipo de módulo
java_library
) - es la versión compilada de los stubs. Las bibliotecas utilizadas para compilar esto no son las mismas que se proporcionan ajava_sdk_library
, lo que garantiza que los detalles de implementación no se filtren en los apéndices de la API. - Si necesita bibliotecas adicionales para compilar los stubs, use las propiedades
stub_only_libs
ystub_only_static_libs
para suministrarlas.
Si una java_sdk_library
se llama " X
" y se está compilando como " X
", consúltela siempre de esa manera y no la modifique. La compilación seleccionará una biblioteca adecuada. Para asegurarse de tener la biblioteca más adecuada, inspeccione sus stubs para ver si la compilación introdujo errores. Realice las correcciones necesarias utilizando esta guía:
- Verifique que tiene una biblioteca adecuada mirando en la línea de comando e inspeccionando qué stubs se enumeran allí para determinar su alcance:
- El alcance es demasiado amplio: la biblioteca dependiente necesita un cierto alcance de API. Pero ve API incluidas en la biblioteca que quedan fuera de ese alcance, como las API del sistema incluidas con las API públicas.
- El ámbito es demasiado limitado: la biblioteca dependiente no tiene acceso a todas las bibliotecas necesarias. Por ejemplo, la biblioteca dependiente necesita usar la API del sistema, pero obtiene la API pública en su lugar. Esto suele dar como resultado un error de compilación porque faltan las API necesarias.
- Para reparar la biblioteca, realice solo una de las siguientes acciones:
- Cambie
sdk_version
para seleccionar la versión que necesita. O - Especifique explícitamente la biblioteca adecuada, como
<X>.stubs
o<X>.stubs.system
.
uso de java_sdk_library X
La biblioteca de implementación X
se usa cuando se hace referencia a ella desde apex.java_libs
. Sin embargo, debido a una limitación de Soong, cuando se hace referencia a la biblioteca X
desde otro módulo java_sdk_library
dentro de la misma biblioteca APEX, se debe usar explícitamente X.impl
, no la biblioteca X
Cuando se hace referencia a java_sdk_library
desde otro lugar, se utiliza una biblioteca de stubs. La biblioteca de stubs se selecciona de acuerdo con la configuración de la propiedad sdk_version
del módulo dependiente. Por ejemplo, un módulo que especifica sdk_version: "current"
usa los stubs públicos, mientras que un módulo que especifica sdk_version: "system_current"
usa los stubs del sistema. Si no se puede encontrar una coincidencia exacta, se utiliza la biblioteca de código auxiliar más cercana. Una java_sdk_library
que solo proporciona una API pública proporcionará los stubs públicos para todos.
![Flujo de compilación con la biblioteca SDK de Java](https://source.android.google.cn/static/devices/architecture/images/build-flow-java-lib.png?hl=es-419)
Ejemplos y fuentes
Las propiedades srcs
y api_packages
deben estar presentes en java_sdk_library
.
java_sdk_library { name: "com.android.future.usb.accessory", srcs: ["src/**/*.java"], api_packages: ["com.android.future.usb"], }
AOSP recomienda (pero no exige) que las nuevas instancias java_sdk_library
habiliten explícitamente los ámbitos de API que desean usar. También puede (opcionalmente) migrar instancias existentes de java_sdk_library
para habilitar explícitamente los ámbitos de API que usarán:
java_sdk_library { name: "lib", public: { enabled: true, }, system: { enabled: true, }, … }
Para configurar la biblioteca impl
utilizada para el tiempo de ejecución, use todas las propiedades normales de java_library
, como hostdex
, compile_dex
y 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, }
Para configurar bibliotecas de apéndices, use las siguientes propiedades:
-
merge_annotations_dirs
ymerge_inclusion_annotations_dirs
. -
api_srcs
: la lista de archivos de origen opcionales que forman parte de la API pero no de la biblioteca de tiempo de ejecución. -
stubs_only_libs
: la lista de bibliotecas de Java que están en el classpath cuando se construyen stubs. -
hidden_api_packages
: la lista de nombres de paquetes que deben ocultarse de la API. -
droiddoc_options
: Argumento adicional para metalava . -
droiddoc_option_files
: enumera los archivos a los que se puede hacer referencia desdedroiddoc_options
usando$(location <label>)
, donde<file>
es una entrada en la lista. -
annotations_enabled
.
java_sdk_library
es una java_library
, pero no es un módulo de droidstubs
y, por lo tanto, no es compatible con todas las propiedades de droidstubs
. El siguiente ejemplo se tomó del archivo de compilación de la biblioteca 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, }
Mantenimiento de la compatibilidad con versiones anteriores
El sistema de compilación comprueba si las API han mantenido la compatibilidad con versiones anteriores comparando los últimos archivos de API con los archivos de API generados en el momento de la compilación. java_sdk_library
realiza la comprobación de compatibilidad utilizando la información proporcionada por prebuilt_apis
. Todas las bibliotecas creadas con java_sdk_library
deben tener archivos API en la última versión de api_dirs
en prebuilt_apis
. Cuando lanza la versión, la API enumera los archivos y las bibliotecas de apéndices se pueden obtener con dist build con PRODUCT=sdk_phone_armv7-sdk
.
La propiedad api_dirs
es una lista de directorios de versiones de API en prebuilt_apis
. Los directorios de la versión de la API deben estar ubicados en el nivel del directorio Android.bp
.
prebuilt_apis { name: "foo", api_dirs: [ "1", "2", .... "30", "current", ], }
Configure los directorios con la estructura version / scope /api/
en el directorio prebuilds. la version
corresponde al nivel de la API y el scope
define si el directorio es público, del sistema o de prueba.
-
version / scope
contiene bibliotecas de Java. -
version / scope /api
contiene archivos API.txt
. Cree archivos de texto vacíos llamadosmodule_name .txt
ymodule_name -removed.txt
aquí.├── 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