Converti JAR in AAR

Un progetto Android può richiedere un AAR quando una libreria fornita è distribuita come JAR, ma necessita anche di risorse Android, voci nel manifest o metadati della libreria. La conversione inserisce le classi JVM esistenti in un contenitore per librerie Android; non trasforma automaticamente il codice Java desktop in codice compatibile con Android.

Cos'è il formato JAR

Un JAR (Java ARchive) è un pacchetto basato su ZIP che contiene file JVM .class, risorse, metadati e, facoltativamente, un manifest che identifica una classe main eseguibile. Le librerie Java e Kotlin, le applicazioni desktop, Maven, Gradle, IntelliJ IDEA e Android Studio utilizzano comunemente file JAR.

Un JAR può essere utilizzato direttamente da un progetto Android quando il relativo bytecode e le dipendenze sono compatibili con Android. Non fornisce intrinsecamente risorse Android, un manifest per librerie Android, regole R8 per i consumer, librerie native o metadati di packaging specifici di Android.

Cos'è il formato AAR

Un AAR (Android ARchive) è il formato di archivio per librerie dell'Android Gradle Plugin. È anch'esso un file ZIP, che normalmente contiene classes.jar e AndroidManifest.xml, con res/, assets/, jni/, prefab/, lint.jar, proguard.txt e file dei simboli delle risorse opzionali.

Un AAR può fornire risorse Android, dichiarazioni del manifest, librerie native, regole per il restringimento del codice destinate ai consumer e codice compilato della libreria come un unico artifact di libreria Android. Gradle unisce questi componenti in un'applicazione. L'archivio non contiene automaticamente le dipendenze Maven esterne; normalmente queste vengono dichiarate nei metadati di pubblicazione o fornite separatamente.

Come impacchettare un JAR come AAR

Ispezionare prima il JAR

Elencare i relativi contenuti con lo strumento del JDK prima di procedere al packaging:

jar tf vendor.jar

Verificare che contenga classi di libreria anziché un'applicazione desktop e controllare il livello del bytecode Java. Il compilatore D8 di Android può elaborare bytecode Java supportato, ma le classi che chiamano API esclusivamente desktop come AWT, Swing o moduli JDK non disponibili non diventeranno utilizzabili su Android tramite il solo packaging.

Wrapper minimo per una libreria Java pura

Per un JAR che non necessita di codice sorgente Android, risorse o ulteriori dichiarazioni nel manifest, creare una directory AAR contenente il JAR con il nome richiesto classes.jar e un manifest:

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)

Su Windows, JDK jar o 7-Zip possono creare l'archivio ZIP: aggiungere classes.jar e AndroidManifest.xml alla radice dell'archivio, quindi salvarlo come vendor.aar. Non inserirli in una directory aggiuntiva.

Si tratta di un'operazione di packaging, non di una compilazione o conversione delle dipendenze. Se il JAR necessita anche di risorse Android, aggiungerle alla radice dell'AAR nella directory res/; aggiungere gli asset dell'applicazione in assets/ e le dichiarazioni necessarie a AndroidManifest.xml.

Utilizzare un modulo di libreria Android per le aggiunte Android

1. In Android Studio, scegliere File → New → New Module → Android Library e selezionare un SDK minimo appropriato.
2. Inserire il codice sorgente Android, le risorse, gli asset e le dichiarazioni del manifest nelle directory src/main del modulo.
3. Aggiungere il JAR originale come dipendenza in fase di compilazione se il codice del modulo lo richiama:

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

Per Kotlin DSL, utilizzare implementation(files("libs/vendor.jar")). La compilazione del modulo con ./gradlew :mylibrary:assembleRelease crea un AAR in un percorso come mylibrary/build/outputs/aar/mylibrary-release.aar.

Una compilazione standard di una libreria Android generalmente non incorpora una dipendenza JAR locale nell'AAR risultante. La dipendenza rimane separata, quindi un consumer potrebbe aver bisogno del JAR originale. Per distribuire un unico archivio, utilizzare il wrapper minimo quando non è necessario altro codice Android compilato, unire il JAR in classes.jar con un'attività di packaging personalizzata oppure utilizzare un plugin Gradle fat-AAR mantenuto, dopo averne verificato la compatibilità con la versione dell'Android Gradle Plugin del progetto. Una soluzione fat-AAR può creare classi duplicate e conflitti tra dipendenze.

Controlli di compatibilità e qualità

Rinominare vendor.jar in vendor.aar non è valido, perché un AAR richiede la libreria compilata in classes.jar oltre a un manifest Android. Controllare l'archivio con unzip -l vendor.aar o 7-Zip.

Allineare il livello del bytecode della libreria alle impostazioni di compatibilità Java e Kotlin della compilazione Android. Controllare le dipendenze transitive, le autorizzazioni o i componenti richiesti nel manifest, le librerie native, i riferimenti alle risorse e le regole R8 per i consumer; un wrapper manuale non può generare le informazioni mancanti.

Testare l'AAR in un'applicazione Android separata utilizzando versioni compatibili dell'Android Gradle Plugin, del compile SDK e dell'SDK minimo. Se la libreria contiene solo classi Java compatibili con Android e nessun contenuto specifico di Android, distribuire il JAR originale potrebbe essere più semplice che produrre un AAR.

Strumenti online e desktop

Non esiste un convertitore online generico affidabile da JAR ad AAR, perché il risultato corretto dipende dalle risorse Android, dalle dichiarazioni del manifest, dalle dipendenze e dalla compatibilità del bytecode. Evitare di caricare librerie proprietarie su servizi web di archiviazione. Utilizzare Android Studio con l'Android Gradle Plugin per le compilazioni dei moduli e il comando JDK jar o 7-Zip per un packaging locale trasparente degli archivi.