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é.

Chaque dépendance expose un fichier Android.mk à votre build. Ces fichiers sont importés à l'aide de la commande import-module. Cette commande recherche les fichiers Android.mk avec le chemin d'accès indiqué dans les répertoires d'importation du build (tels que configurés par import-add-path) et expose les modules 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 Android.mk doit inclure les éléments suivants :

include $(CLEAR_VARS)
LOCAL_MODULE := libapp
LOCAL_SRC_FILES := app.cpp
LOCAL_SHARED_LIBRARIES := curl
include $(BUILD_SHARED_LIBRARY)

# If you don't need your project to build with NDKs older than r21, you can omit
# this block.
ifneq ($(call ndk-major-at-least,21),true)
    $(call import-add-path,$(NDK_GRADLE_INJECTED_IMPORT_PATH))
endif

$(call import-module,prefab/curl)

Notez que le import-add-path explicite n'est requis que si vous utilisez des NDK antérieurs à la version r21. À partir de la version r21, NDK_GRADLE_INJECTED_IMPORT_PATH est automatiquement ajouté aux chemins d'importation.

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.