Préparer la publication de votre bibliothèque

Cette page décrit les propriétés et les options nécessaires à la préparation de votre projet de bibliothèque Android pour la publication à l'aide du plug-in Android Gradle (AGP). Même si vous avez déjà défini certaines de ces propriétés au début de la création de votre bibliothèque, nous vous recommandons de lire les conseils suivants pour optimiser vos paramètres.

Choisir un espace de noms

Les bibliothèques Android doivent déclarer un espace de noms pour pouvoir générer une classe R unique lorsque leurs ressources sont compilées. Cet espace de noms doit correspondre précisément au package de classe racine de la bibliothèque pour éviter toute confusion lorsque les utilisateurs importent des classes standards depuis la bibliothèque et sa classe R.

À partir de la version 7.0 d'AGP, vous pouvez définir l'espace de noms dans le fichier build.gradle de l'application, comme indiqué dans l'exemple de code suivant :

android {
  namespace = 'com.example.library'
}

android {
  namespace = "com.example.library"
}

L'espace de noms est une propriété de la bibliothèque destinée aux développeurs. Elle n'est pas liée à l'identité de l'application, qui est définie à l'aide de la propriété applicationId.

Dans les versions précédentes d'AGP, la propriété applicationId (pour une application) et la propriété namespace (pour une bibliothèque) pouvaient toutes deux être définies à l'aide de l'attribut package du fichier manifeste, ce qui prêtait à confusion.

Choisir une valeur minSdkVersion

Le choix d'une minSdkVersion est un aspect important de la publication de votre bibliothèque. Le champ minSdkVersion doit refléter la version minimale d'Android prise en charge par votre code.

Tenez compte des points suivants lorsque vous choisissez une minSdkVersion :

• Choisir une valeur minSdkVersion faible permet généralement d'élargir la distribution de votre bibliothèque.

  En règle générale, le code d'une bibliothèque s'exécute uniquement si l'application l'appelle explicitement. Une application peut toujours s'exécuter sur une version d'Android antérieure à celle requise par la dépendance d'une bibliothèque (si la bibliothèque n'est pas essentielle aux fonctionnalités clés de l'application) en effectuant des vérifications d'exécution avant d'appeler la bibliothèque. Par conséquent, définissez un paramètre minSdkVersion de bibliothèque suffisamment faible pour qu'elle puisse être intégrée dans des applications et appelée lorsque cela est possible, afin de toucher plus d'utilisateurs.

• Le choix d'une valeur minSdkVersion élevée peut empêcher les applications d'inclure la bibliothèque.

  La fusion de fichiers manifestes, une étape dans AGP où des fichiers manifestes de l'application et de ses dépendances sont fusionnés, permet d'éviter que les dépendances ne possèdent une valeur minSdkVersion supérieure à celle de l'application.

• Si vous choisissez une valeur minSdkVersion élevée, les développeurs d'applications risquent de désactiver les contrôles de situation pour la fusion du fichier manifeste, ce qui posera des problèmes plus tard dans le processus de compilation.

  Étant donné que la fusion du fichier manifeste empêche les projets d'application d'inclure des bibliothèques dont la valeur minSdkVersion est supérieure à celle de l'application elle-même, les développeurs d'applications peuvent désactiver les contrôles de situation pour la fusion du fichier manifeste afin de limiter au maximum les erreurs de compilation. Toutefois, il existe un risque de vrais problèmes d'incompatibilité en aval.

• Vous devrez peut-être choisir une valeur minSdkVersion élevée dans certains cas particuliers où le fichier manifeste d'une bibliothèque inclut un broadcast receiver ou un autre mécanisme par lequel son code est déclenché automatiquement.

  Dans ce type de situations, le choix d'une valeur minSdkVersion élevée garantit l'exécution du code. Vous pouvez également désactiver le comportement automatisé afin que l'application puisse accepter l'exécution de la bibliothèque après avoir effectué les vérifications appropriées.

Pour autoriser l'intégration dans les applications, utilisez l'annotation RequiresApi dans votre bibliothèque afin d'indiquer aux appelants qu'ils doivent vérifier l'environnement d'exécution. Android Lint se sert des informations RequiresApi pour ses inspections. Pour en savoir plus sur l'utilisation des annotations afin d'améliorer le code et les API, consultez Améliorer l'inspection de code avec des annotations.

Configurer les métadonnées AAR

Une bibliothèque Android est empaquetée sous la forme d'un fichier d'archive Android (AAR). Les métadonnées de l'AAR sont des propriétés qui aident AGP à utiliser les bibliothèques. Si votre bibliothèque est utilisée par une configuration incompatible et que les métadonnées AAR sont définies, un message d'erreur s'affiche pour aider les utilisateurs à résoudre le problème.

Choisir une valeur minCompileSdk

À partir de la version 4.1, AGP est compatible avec minCompileSdk. Cela indique le niveau minimal du compileSdk que les projets consommateurs peuvent utiliser. Si votre bibliothèque contient des entrées de fichier manifeste ou des ressources qui se servent d'attributs de plate-forme plus récents, vous devez définir cette valeur.

La valeur minCompileSdk peut être définie dans les blocs defaultConfig{}, productFlavors{} et buildTypes{} du fichier build.gradle au niveau du module :

android {
  defaultConfig {
    aarMetadata {
      minCompileSdk = 29
    }
  }
  productFlavors {
    foo {
      ...
      aarMetadata {
        minCompileSdk = 30
      }
    }
  }
}

android {
  defaultConfig {
    aarMetadata {
      minCompileSdk = 29
    }
  }
  productFlavors {
    register("foo") {
      ...
      aarMetadata {
        minCompileSdk = 30
      }
    }
  }
}

Si vous définissez la valeur minCompileSdk à plusieurs endroits, Gradle donne la priorité aux emplacements des paramètres, comme suit, au cours du processus de compilation :

1. buildTypes{}

2. productFlavors{}

3. defaultConfig{}

Dans l'exemple précédent, où la valeur minCompileSdk est définie à la fois dans defaultConfig{} et productFlavors{}, productFlavors{} est prioritaire et minCompileSdk est défini sur "30".

Pour en savoir plus sur la manière dont Gradle donne la priorité aux paramètres lorsqu'il combine du code et des ressources, consultez Compiler avec des ensembles de sources.

Activer les outils de test

Les outils de test sont souvent utilisés pour configurer le code testé ou pour effectuer les tests d'un composant. À partir de la version 7.1, AGP peut créer des outils de test pour les projets de bibliothèque (en plus des projets d'application et de fonctionnalités dynamiques).

Lorsque vous publiez une bibliothèque destinée à être utilisée par d'autres personnes, envisagez de créer des outils de test pour votre API. Ces outils sont activables dans le fichier build.gradle au niveau du module :

android {
  testFixtures {
    enable = true
  }
}

android {
  testFixtures {
    enable = true
  }
}

Lorsque vous activez les outils de test, Gradle crée automatiquement un ensemble de sources src/testFixtures dans lequel vous pouvez écrire des outils de test.

Pour en savoir plus, consultez la documentation de Gradle sur l'utilisation des outils de test.