Convertir JAR en AAR

Un projet Android peut nécessiter un AAR lorsqu'une bibliothèque fournie est distribuée sous forme de JAR, mais nécessite également des ressources Android, des entrées de manifeste ou des métadonnées de bibliothèque. La conversion regroupe les classes JVM existantes dans un conteneur de bibliothèque Android ; elle ne transforme pas automatiquement le code Java pour ordinateur de bureau en code compatible avec Android.

Qu'est-ce que le format JAR ?

Un JAR (Java ARchive) est un package basé sur ZIP contenant des fichiers JVM .class, des ressources, des métadonnées et, éventuellement, un manifeste identifiant une classe principale exécutable. Les bibliothèques Java et Kotlin, les applications de bureau, Maven, Gradle, IntelliJ IDEA et Android Studio utilisent couramment des fichiers JAR.

Un JAR peut être utilisé directement par un projet Android lorsque son bytecode et ses dépendances sont compatibles avec Android. Il ne fournit pas intrinsèquement de ressources Android, de manifeste de bibliothèque Android, de règles R8 pour les consommateurs, de bibliothèques natives ni de métadonnées de packaging spécifiques à Android.

Qu'est-ce que le format AAR ?

Un AAR (Android ARchive) est le format d'archive de bibliothèque de l'Android Gradle Plugin. Il s'agit également d'un fichier ZIP contenant normalement classes.jar et AndroidManifest.xml, ainsi que, éventuellement, res/, assets/, jni/, prefab/, lint.jar, proguard.txt et des fichiers de symboles de ressources.

Un AAR peut fournir des ressources Android, des déclarations de manifeste, des bibliothèques natives, des règles de réduction pour les consommateurs et du code de bibliothèque compilé sous la forme d'un seul artefact de bibliothèque Android. Gradle fusionne ces composants dans une application. L'archive ne contient pas automatiquement les dépendances Maven externes ; celles-ci sont normalement déclarées dans les métadonnées de publication ou fournies séparément.

Comment empaqueter un JAR en tant qu'AAR

Inspecter d'abord le JAR

Répertoriez son contenu avec l'outil du JDK avant de l'empaqueter :

jar tf vendor.jar

Vérifiez qu'il contient des classes de bibliothèque et non une application de bureau, puis contrôlez son niveau de bytecode Java. Le compilateur D8 d'Android peut traiter le bytecode Java pris en charge, mais les classes qui appellent des API réservées aux ordinateurs de bureau, telles que AWT, Swing ou des modules JDK indisponibles, ne deviendront pas utilisables sur Android par le seul empaquetage.

Wrapper minimal pour une bibliothèque Java pure

Pour un JAR qui ne nécessite ni code source Android, ni ressources, ni déclarations de manifeste supplémentaires, créez un répertoire AAR contenant le JAR sous le nom requis classes.jar ainsi qu'un manifeste :

mkdir aar-temp
cp vendor.jar aar-temp/classes.jar
printf '%s\n' '<manifest xmlns:android="http://schemas.android.com/apk/res/android" />' > aar-temp/AndroidManifest.xml
(cd aar-temp && zip -r ../vendor.aar classes.jar AndroidManifest.xml)

Sous Windows, le jar du JDK ou 7-Zip peut créer l'archive ZIP : ajoutez classes.jar et AndroidManifest.xml à la racine de l'archive, puis enregistrez-la sous le nom vendor.aar. Ne les placez pas dans un répertoire supplémentaire.

Il s'agit d'une opération d'empaquetage, et non d'une compilation ou d'une conversion de dépendances. Si le JAR nécessite également des ressources Android, ajoutez-les à la racine de l'AAR sous res/ ; ajoutez les ressources d'application sous assets/ ainsi que les déclarations requises dans AndroidManifest.xml.

Utiliser un module de bibliothèque Android pour les ajouts Android

1. Dans Android Studio, choisissez File → New → New Module → Android Library, puis sélectionnez un SDK minimal approprié.
2. Placez le code source Android, les ressources, les ressources d'application et les déclarations de manifeste dans les répertoires src/main du module.
3. Ajoutez le JAR d'origine comme dépendance de compilation si le code du module l'utilise :

dependencies {
    implementation files('libs/vendor.jar')
}

Pour Kotlin DSL, utilisez implementation(files("libs/vendor.jar")). La compilation du module avec ./gradlew :mylibrary:assembleRelease crée un AAR dans un chemin tel que mylibrary/build/outputs/aar/mylibrary-release.aar.

Une compilation standard de bibliothèque Android n'intègre généralement pas une dépendance JAR locale dans l'AAR obtenu. La dépendance reste séparée ; un consommateur peut donc avoir besoin du JAR d'origine. Pour distribuer une seule archive, utilisez soit le wrapper minimal lorsqu'aucun code Android compilé supplémentaire n'est nécessaire, soit fusionnez le JAR dans classes.jar à l'aide d'une tâche d'empaquetage personnalisée, soit utilisez un plugin Gradle fat-AAR maintenu après avoir vérifié sa compatibilité avec la version de l'Android Gradle Plugin du projet. Une solution fat-AAR peut créer des classes en double et des conflits de dépendances.

Vérifications de compatibilité et de qualité

Renommer vendor.jar en vendor.aar n'est pas valide, car un AAR attend la bibliothèque compilée sous classes.jar ainsi qu'un manifeste Android. Vérifiez l'archive avec unzip -l vendor.aar ou 7-Zip.

Faites correspondre le niveau de bytecode de la bibliothèque aux paramètres de compatibilité Java et Kotlin de la compilation Android. Vérifiez ses dépendances transitives, les autorisations ou composants requis dans le manifeste, les bibliothèques natives, les références de ressources et les règles R8 pour les consommateurs ; un wrapper manuel ne peut pas générer les informations manquantes.

Testez l'AAR dans une application Android distincte utilisant des versions compatibles de l'Android Gradle Plugin, du SDK de compilation et du SDK minimal. Si la bibliothèque contient uniquement des classes Java compatibles avec Android et aucun contenu spécifique à Android, distribuer le JAR d'origine peut être plus simple que produire un AAR.

Outils en ligne et pour ordinateur de bureau

Il n'existe pas de convertisseur JAR vers AAR en ligne fiable et polyvalent, car le résultat correct dépend des ressources Android, des déclarations de manifeste, des dépendances et de la compatibilité du bytecode. Évitez de téléverser des bibliothèques propriétaires vers des services d'archives en ligne. Utilisez Android Studio avec l'Android Gradle Plugin pour les compilations de modules, et la commande jar du JDK ou 7-Zip pour un empaquetage local transparent des archives.