Cette page a été traduite par l'API Cloud Translation.

Implémenter la bibliothèque du SDK Java

La plate-forme Android contient un grand nombre de bibliothèques Java partagées. qui peut éventuellement être inclus dans le classpath des applications avec le paramètre Balise <uses-library> dans le fichier manifeste de l'application. Lien vers les applications par rapport à ces bibliothèques. Vous devez donc les traiter comme le reste de l'API Android. en termes de compatibilité, d'examen des API et de compatibilité avec les outils. Notez toutefois que que la plupart des bibliothèques n'ont pas ces fonctionnalités.

Le type de module java_sdk_library permet de gérer les bibliothèques de ce type. Les fabricants d'appareils peuvent utiliser ce mécanisme des bibliothèques Java partagées, afin de maintenir la rétrocompatibilité pour leurs API. Si les fabricants d'appareils utilisent leurs propres bibliothèques Java partagées via le <uses-library> au lieu du chemin d'accès à la classe de démarrage, java_sdk_library peut vérifier que ces bibliothèques Java sont API stable.

Le java_sdk_library implémente les API facultatives du SDK à utiliser par applications. Les bibliothèques implémentées via java_sdk_library dans votre fichier de compilation (Android.bp) effectue les opérations suivantes:

Les bibliothèques de bouchons sont générées pour inclure stubs, stubs.system et stubs.test. Ces Les bibliothèques de bouchons sont créées en reconnaissant @hide, les annotations @SystemApi et @TestApi.
java_sdk_library gère les fichiers de spécification d'API. (par exemple, current.txt) dans un sous-répertoire d'API. Ces fichiers sont vérifiés par rapport au code le plus récent afin de s'assurer qu'ils sont versions actuelles. Si ce n'est pas le cas, vous recevez un message d'erreur indiquant explique comment les mettre à jour. Examinez manuellement toutes les modifications apportées à pour vous assurer qu'elles répondent à vos attentes.

Pour mettre à jour toutes les API, utilisez m update-api. Pour vérifier qu'une API est à jour, utiliser m checkapi.
Les fichiers de spécifications de l'API sont vérifiés par rapport à la dernière versions d'Android publiées pour garantir la rétrocompatibilité de l'API avec les versions antérieures. Les modules java_sdk_library fournis dans le cadre d'AOSP, les versions précédentes prebuilts/sdk/<latest number>
En ce qui concerne les vérifications des fichiers de spécification d'API, l'une des trois choses suivantes:

Autorisez les vérifications. (Ne faites rien.)
Désactivez les vérifications en ajoutant le code suivant à java_sdk_library:
unsafe_ignore_missing_latest_api: true,
Fournir des API vides pour les nouveaux modules java_sdk_library en créant des fichiers texte vides nommés module_name.txt le répertoire version/scope/api.

Si la bibliothèque d'implémentation pour l'environnement d'exécution est installée, un fichier XML est généré et installé.

Fonctionnement de java_sdk_library

Un élément java_sdk_library appelé X crée les éléments suivants:

Deux copies de la bibliothèque d'implémentation: une bibliothèque appelée X et une autre appelée X.impl. La bibliothèque X est installée sur l'appareil. La bibliothèque X.impl n'est disponible que si l'accès explicite à la bibliothèque d'implémentation est nécessaire à d'autres modules, par exemple pour être utilisée dans tests. Notez qu'un accès explicite est rarement nécessaire.
Vous pouvez activer et désactiver les niveaux d'accès pour personnaliser l'accès. (semblable à Java des modificateurs d'accès par mot clé, un champ d'application public offre un large éventail d'accès ; un le champ d'application de test contient des API uniquement utilisées pour les tests.) Pour chaque champ d'application activé, crée les éléments suivants:

Module source bouchons (de type droidstubs) : utilise la source d'implémentation et génère un ensemble de sources bouchons, ainsi que le fichier de spécification de l'API.
Une bibliothèque de bouchons (de type de module java_library) est la version compilée des bouchons. Les bibliothèques utilisées pour compiler ce code ne sont pas identiques à celles fournies à java_sdk_library, ce qui garantit les détails de l'implémentation ne sont pas divulgués dans les bouchons d'API.
Si vous avez besoin de bibliothèques supplémentaires pour compiler les bouchons, utilisez la méthode stub_only_libs et stub_only_static_libs pour les fournir.

Si un java_sdk_library est appelé "X" et est en cours compilées sous le nom "X", faites-le toujours référence ainsi et ne modifiez pas La compilation sélectionne une bibliothèque appropriée. Pour vous assurer de disposer des la bibliothèque la plus appropriée, inspectez vos bouchons pour voir si le build a introduit les erreurs. Apportez les corrections nécessaires en suivant ces conseils:

Vérifiez que vous disposez d'une bibliothèque appropriée en consultant la ligne de commande et en inspectant les bouchons qui y figurent pour déterminer votre champ d'application:

Le champ d'application est trop large: la bibliothèque en dépend nécessite un certain champ d'application d'API. Toutefois, vous voyez que des API incluses dans la bibliothèque ne relèvent pas de ce champ d'application, comme les API système incluses dans les API publiques.
Le champ d'application est trop restreint: la bibliothèque en question n'a pas accès à toutes les les bibliothèques requises. Par exemple, la bibliothèque dépendante doit utiliser le l'API système, mais obtient l'API publique à la place. Cela se traduit généralement par Erreur de compilation, car les API nécessaires sont manquantes.

Pour corriger la bibliothèque, n'effectuez qu'une seule des actions suivantes:

Modifiez sdk_version pour sélectionner la version dont vous avez besoin. OU
Spécifiez explicitement la bibliothèque appropriée, par exemple <X>.stubs. ou <X>.stubs.system.

Utilisation de java_sdk_library X

La bibliothèque d'implémentation X est utilisée lorsqu'elle est référencée à partir de apex.java_libs Toutefois, en raison d'une limitation de Soong, lorsque la bibliothèque X est référencé à partir d'un autre module java_sdk_library. dans la même bibliothèque APEX, X.impl de manière explicite doit être utilisé, et non la bibliothèque X.

Lorsque le java_sdk_library est référencé ailleurs, un bouchon est utilisée. La bibliothèque de bouchons est sélectionnée en fonction paramètre de la propriété sdk_version du module. Par exemple, un module spécifie que sdk_version: "current" utilise les bouchons publics, alors qu'une qui spécifie sdk_version: "system_current" utilise l'élément bouchons système. Si aucune correspondance exacte n'est trouvée, la bibliothèque de bouchons la plus proche est utilisé. Un java_sdk_library qui ne fournit qu'une API publique fournir les bouchons publics pour tout le monde.

**Figure 1**. Flux de compilation avec la bibliothèque du SDK Java

Exemples et sources

Les propriétés srcs et api_packages doivent être présent dans java_sdk_library.

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

L'AOSP recommande (mais ne nécessite pas) cette nouvelle java_sdk_library d'activer explicitement les champs d'application d'API qu'elles souhaitent utiliser. Vous pouvez également Migrez (facultatif) les instances java_sdk_library existantes vers activer explicitement les champs d'application d'API qu'ils utiliseront:

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

Pour configurer la bibliothèque impl utilisée pour l'environnement d'exécution, utilisez toutes les propriétés java_library normales, telles que hostdex, compile_dex et 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,
    }

Pour configurer les bibliothèques de bouchons, utilisez les propriétés suivantes:

merge_annotations_dirs et merge_inclusion_annotations_dirs.
api_srcs: liste des fichiers sources facultatifs qui font partie de l'API, mais pas dans la bibliothèque d'exécution.
stubs_only_libs: liste des bibliothèques Java qui se trouvent dans le fichier classpath lors de la création de bouchons.
hidden_api_packages: liste des noms de packages qui doivent être cachées dans l'API.
droiddoc_options: argument supplémentaire pour metalava.
droiddoc_option_files: liste les fichiers pouvant être référencés à partir de droiddoc_options en utilisant $(location <label>), où <file> est une entrée de la liste.
annotations_enabled.

Le java_sdk_library est de type java_library, mais pas du le module droidstubs et n'est donc pas compatible avec tous les droidstubs. propriétés. L'exemple suivant est issu de Compilation de la bibliothèque 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,
    }

Maintenir la rétrocompatibilité

Le système de compilation vérifie si les API ont été gérées en comparant les derniers fichiers API aux fichiers de l'API au moment de la compilation. Le java_sdk_library effectue les vérification de la compatibilité à l'aide des informations fournies par prebuilt_apis. Toutes les bibliothèques compilées avec java_sdk_library doivent comporter des fichiers API dans la dernière version de api_dirs (prebuilt_apis). Lorsque vous publiez la version, l'API répertorie les fichiers et les bouchons Les bibliothèques peuvent être obtenues à l'aide du build dist avec PRODUCT=sdk_phone_armv7-sdk.

La propriété api_dirs est une liste des répertoires des versions de l'API. dans prebuilt_apis. Les répertoires de versions d'API doivent être situé au niveau du répertoire Android.bp.

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

Configurez les répertoires avec version/scope/api/. dans le répertoire prédéfini. version correspond au niveau d'API, et scope définit si le répertoire est public, système ou test.

version/scope contient des bibliothèques Java.

version/scope/api contient l'API .txt fichiers. Créez des fichiers texte vides nommés module_name.txt et module_name-removed.txt ici.

 ├── 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