Dépendances natives avec le plug-in Android Gradle

Les bibliothèques AAR peuvent contenir des dépendances natives que le plug-in Android Gradle peut consommer. AGP est également capable de produire des AAR qui exposent des bibliothèques natives à leurs consommateurs.

Utiliser des dépendances natives

À partir de la version 4.0 du plug-in Android Gradle, les dépendances en C/C++ peuvent être importées à partir des fichiers AAR associés dans votre fichier build.gradle. Gradle les met automatiquement à la disposition du système de compilation native, mais votre système de compilation doit être configuré pour utiliser les bibliothèques et les en-têtes importés. Étant donné que les dépendances en C/C++ sont distribuées sous forme d'AAR, les ressources suivantes concernant les AAR génériques peuvent être utiles :

  • Créer une bibliothèque Android : documentation sur les AAR génériques et comment les intégrer à votre projet, en particulier lorsque vous souhaitez utiliser un AAR comme dépendance C/C++ locale.
  • Ajouter des dépendances de compilation : pour en savoir plus sur l'ajout de dépendances à votre fichier build.gradle, en particulier pour les dépendances distantes.

Ce document explique comment configurer votre système de compilation natif et suppose que vous avez déjà ajouté une AAR avec une dépendance en C/C++ dans l'environnement de compilation Gradle de votre projet.

Dépendances natives dans des AAR

Les dépendances AAR de vos modules Gradle peuvent exposer les bibliothèques natives qui seront utilisées par votre application. Dans l'AAR, le répertoire prefab contient un package Prefab, qui inclut les en-têtes et les bibliothèques de la dépendance native.

Chaque dépendance peut exposer au maximum un package Prefab, qui comprend un ou plusieurs modules. Un module Prefab est une bibliothèque unique, qui peut être une bibliothèque partagée, statique ou en-tête uniquement.

Les noms des packages et des modules doivent être connus pour pouvoir utiliser les bibliothèques. Par convention, le nom du package correspond au nom de l'artefact Maven et le nom du module au nom de la bibliothèque C/C++. Ce n'est cependant pas une obligation. Consultez la documentation de la dépendance pour déterminer les noms qu'elle utilise.

Créer une configuration système

La fonctionnalité prefab doit être activée pour votre module Android Gradle.

Pour ce faire, ajoutez le code suivant au bloc android du fichier build.gradle de votre module :

Kotlin

buildFeatures {
  prefab = true
}

Groovy

buildFeatures {
  prefab true
}

Vous pouvez éventuellement configurer une version dans le fichier gradle.properties de votre projet :

android.prefabVersion=2.0.0

En général, la version AGP sélectionnée par défaut répond à vos besoins. Vous ne devez sélectionner une version différente que si vous avez besoin de contourner un bug ou d'exploiter une nouvelle fonctionnalité.

Les dépendances importées à partir d'un AAR sont exposées à CMake via CMAKE_FIND_ROOT_PATH. Cette valeur est définie automatiquement par Gradle lorsque CMake est appelé. Par conséquent, si votre compilation modifie cette variable, assurez-vous de l'ajouter au lieu de l'attribuer.

Chaque dépendance expose un package config-file à votre build. Les packages sont importés via la commande find_package. Cette commande recherche les packages config-file correspondant au nom et à la version de package spécifiés, et expose les cibles qu'elle définit pour permettre leur utilisation dans votre build. Par exemple, si votre application définit libapp.so et qu'elle utilise cURL, votre fichier CMakeLists.txt doit inclure les éléments suivants :

add_library(app SHARED app.cpp)

# Add these two lines.
find_package(curl REQUIRED CONFIG)
target_link_libraries(app curl::curl)

app.cpp permet désormais de #include "curl/curl.h", et libapp.so sera automatiquement associé à libcurl.so lors de la compilation, tandis que libcurl.so sera inclus avec l'application.

Publier des bibliothèques natives dans des AAR

La possibilité de créer des AAR natives a été ajoutée pour la première fois dans la version 4.1 d'AGP.

Pour exporter vos bibliothèques natives, ajoutez le code suivant au bloc android du fichier build.gradle.kts de votre projet de bibliothèque :

Kotlin

buildFeatures {
    prefabPublishing = true
}

prefab {
    create("mylibrary") {
      headers = "src/main/cpp/mylibrary/include"
    }

    create("myotherlibrary") {
        headers = "src/main/cpp/myotherlibrary/include"
    }
}

Groovy

buildFeatures {
    prefabPublishing true
}

prefab {
    mylibrary {
      headers "src/main/cpp/mylibrary/include"
    }

    myotherlibrary {
        headers "src/main/cpp/myotherlibrary/include"
    }
}

Dans cet exemple, les bibliothèques mylibrary et myotherlibrary de votre build externe ndk-build ou CMake native seront packagées dans l'AAR produite par votre compilation, et chacune exportera les en-têtes à partir du répertoire spécifié vers leurs dépendances.