Google se compromete a impulsar la igualdad racial para las comunidades afrodescendientes. Obtén información al respecto.

Implementación de la biblioteca SDK de Java

La plataforma Android contiene un gran número de bibliotecas compartidas de Java que opcionalmente se pueden incluir en la ruta de clase de aplicaciones con el <uses-library> etiqueta 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. Sin embargo, tenga en cuenta que la mayoría de las bibliotecas no tienen estas funciones.

El java_sdk_library tipo de módulo ayuda a gestionar las bibliotecas de este tipo. Los fabricantes de dispositivos pueden utilizar este mecanismo para sus propias bibliotecas Java compartidas, a fin de mantener la compatibilidad con versiones anteriores de sus API. Si los fabricantes de dispositivos utilizan sus propias bibliotecas compartidas de Java a través de la <uses-library> etiqueta en lugar de la ruta bootclass, java_sdk_library puede verificar que las bibliotecas de Java son API-estable.

Los java_sdk_library implementos opcionales API SDK para el uso de aplicaciones. Bibliotecas implementan a través de java_sdk_library en su fichero de construcción ( Android.bp ) realizar las siguientes operaciones:

  • Las bibliotecas talones se generan para incluir stubs , stubs.system y stubs.test . Estas bibliotecas talones se crean mediante el reconocimiento de @hide , @SystemApi y @TestApi anotaciones.
  • El java_sdk_library gestiona los archivos de especificación API (tales como current.txt ) en un subdirectorio API. Estos archivos se comparan con el código más reciente para garantizar que sean las versiones más recientes. Si no es así, 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.
  • 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 java_sdk_library módulos proporcionados como parte de AOSP lugar sus versiones publicadas anteriormente en prebuilts/sdk/<latest number> .
  • Con respecto a la especificación API de archivos de cheques, puede realizar una de las siguientes tres cosas:
    • Deje que continúen las comprobaciones. (No hagas nada).
    • Cheques Deshabilitar añadiendo lo siguiente a java_sdk_library :
      unsafe_ignore_missing_latest_api: true,
    • Proporcionar API vacías para nuevos java_sdk_library módulos mediante la creación de archivos de texto vacío denominado module_name.txt en la version/scope/api directorio .
  • 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

Un java_sdk_library llamada X crea la siguiente:

  1. Dos copias de la biblioteca de aplicación: una biblioteca llamada X y otro llamado X.impl . Biblioteca X se instala en el dispositivo. Biblioteca X.impl es allí sólo si el acceso explícita a la biblioteca de aplicación es necesaria por otros módulos, como para su uso en pruebas. Tenga en cuenta que rara vez se necesita acceso explícito.
  2. Los ámbitos se pueden habilitar y deshabilitar para personalizar el acceso. (De manera similar a los modificadores de acceso a palabras clave de Java, un alcance público proporciona una amplia gama de acceso; un alcance de prueba contiene API que solo se usan en pruebas). Para cada alcance habilitado, la biblioteca crea lo siguiente:
    • Un módulo de fuente talones (de droidstubs tipo de módulo) - consume la fuente de la aplicación y da salida a un conjunto de fuentes de código auxiliar junto con el archivo de especificación API.
    • A talones de biblioteca (de java_library tipo de módulo) - es la versión compilada de los stubs. Las librerías utilizadas para compilar esto no son los mismos que los proporcionados por la java_sdk_library , lo que asegura los detalles de implementación no se escapan en los talones de la API.
    • Si necesita bibliotecas adicionales para compilar los talones, utilizar los stub_only_libs y stub_only_static_libs propiedades a suministrarlos.

Si un java_sdk_library se llama “ X ”, y está siendo compilado contra como “ X ”, se refieren siempre a ella de esa manera y no lo modifique. La compilación seleccionará una biblioteca adecuada. Para asegurarse de tener la biblioteca más adecuada, inspeccione sus códigos auxiliares 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 ves API incluidas en la biblioteca que quedan fuera de ese alcance, como las API del sistema incluidas con las API públicas.
    • El alcance es demasiado estrecho: 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. Por lo general, esto da como resultado un error de compilación porque faltan las API necesarias.
  • Para solucionar la biblioteca, hacer sólo una de las siguientes acciones:
    • Cambiar el sdk_version para seleccionar la versión que necesita. O
    • Explícitamente especificar la biblioteca apropiada, tal como <X>.stubs o <X>.stubs.system .

uso de java_sdk_library X

La biblioteca de ejecución X se utiliza cuando se hace referencia desde apex.java_libs . Sin embargo, debido a una limitación Soong, cuando biblioteca X se hace referencia de otro java_sdk_library módulo dentro de la misma biblioteca de APEX, X.impl explícitamente debe ser utilizado, no biblioteca X .

Cuando el java_sdk_library es referenciado de otra parte, se utiliza una biblioteca stubs. La biblioteca talones se selecciona de acuerdo con el módulo de función sdk_version valor de la propiedad. Por ejemplo, un módulo que especifica sdk_version: "current" usos de los talones pública, mientras que un módulo que especifica sdk_version: "system_current" utiliza los talones del sistema. Si no se puede encontrar una coincidencia exacta, se utiliza la biblioteca de códigos auxiliar más cercana. Un java_sdk_library que sólo proporciona una API pública suministrará los talones públicos para todos.

Genere flujo con la biblioteca Java SDK
Figura 1. Construir con flujo biblioteca de Java SDK

Ejemplos y fuentes

Los srcs y api_packages propiedades deben estar presentes en el 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 requiere) que los nuevos java_sdk_library casos permiten explícitamente la API alcances que desea utilizar. Puede también (opcionalmente) migran existente java_sdk_library casos para permitir explícitamente la API alcances que vamos a usar:

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

Para configurar el impl biblioteca usada para tiempo de ejecución, utilizar todas las normales java_library propiedades, tales 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 stubs, use las siguientes propiedades:

  • merge_annotations_dirs y merge_inclusion_annotations_dirs .
  • api_srcs : La lista de los archivos de origen opcionales que forman parte de la API, pero no forma parte de la biblioteca de tiempo de ejecución.
  • stubs_only_libs : La lista de bibliotecas de Java que se encuentran en la ruta de clase en la construcción de los talones.
  • hidden_api_packages : La lista de nombres de paquetes que deben ser escondido de la API.
  • droiddoc_options : argumento adicional para metalava .
  • droiddoc_option_files : muestra los archivos que pueden ser referenciadas desde dentro droiddoc_options utilizando $(location <label>) , donde <file> es una entrada en la lista.
  • annotations_enabled .

El java_sdk_library es un java_library , pero no es un droidstubs módulo y así no soporta todos los droidstubs propiedades. El siguiente ejemplo fue tomado de la construcción de la biblioteca android.test.mock archivo.

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

Mantener la compatibilidad con versiones anteriores

El sistema de compilación verifica si las API han mantenido la compatibilidad con versiones anteriores comparando los archivos de API más recientes con los archivos de API generados en el momento de la compilación. Los java_sdk_library realiza la comprobación de la compatibilidad usando la información proporcionada por prebuilt_apis . Todas las bibliotecas construidas con java_sdk_library deben tener archivos de la API en la versión más reciente de api_dirs en prebuilt_apis . Al soltar la versión, los archivos de listas de API y bibliotecas talones se pueden obtener con la construcción dist con PRODUCT=sdk_phone_armv7-sdk .

El api_dirs propiedad está lista de directorios versión de la API en prebuilt_apis . Los directorios API de versiones deben estar ubicados en el Android.bp nivel de directorio.

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

Configurar los directorios con la version / scope /api/ estructura bajo el directorio prebuilts. version corresponde al nivel de principios activos y de scope define si el directorio es pública, sistema o de prueba.

  • version / scope contiene bibliotecas de Java.
  • version / scope /api contiene API .txt archivos. Crear archivos de texto vacío denominado module_name .txt y module_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