22 KiB
Profil Android
Rôle
Ce document possède les règles réutilisables propres à la plateforme Android.
Il complète 600-PLATFORMS.md, 522-GRADLE.md lorsqu'un projet Android utilise Gradle et 520-JAVA.md lorsqu'il contient du code Java. Android n'implique pas à lui seul l'applicabilité du profil Java.
Une contrainte Android plus spécifique MAY raffiner les règles générales Gradle et, lorsque Java est applicable, les règles JDK/Java dans le seul scope Android lorsqu'une matrice AGP/Gradle/JDK, un SDK ou une contrainte de distribution l'impose.
Les profils Rust/JNI et Tauri ne sont pas définis ici. Ils constituent des compositions plus spécialisées et MUST NOT contaminer le profil Android général.
Structure du projet
Pour un dépôt exclusivement Android, les conventions Android normales restent prioritaires et la racine du dépôt MAY être directement le projet de build Android.
Dans un dépôt multi-plateforme où une zone Android distincte est nécessaire, PGR SHOULD utiliser la racine :
Android/
Cette racine est alors un chemin de plateforme stable. Elle ne doit pas être renommée arbitrairement en android/, mobile/ ou autre uniquement par préférence locale.
Une structure multi-plateforme peut par exemple contenir :
project/
├── VERSION
├── crates/
├── Web/
└── Android/
├── settings.gradle(.kts)
├── build.gradle(.kts)
├── gradle.properties
└── <module>/
Cet exemple décrit une frontière de plateforme, pas une liste obligatoire de fichiers Gradle. Wrapper, version catalog, plugins de convention, modules et autres éléments de build restent gouvernés par la composition réellement choisie et par 522-GRADLE.md.
Les noms et fichiers exacts restent soumis au projet Android réellement utilisé ; PGR ne crée pas de niveau Android/ artificiel dans un dépôt qui est déjà exclusivement Android.
Langage applicatif et logique de build
Android ne sélectionne pas à lui seul le langage applicatif du projet. Les profils langage s'appliquent uniquement aux langages réellement présents.
Lorsqu'un projet Android contient du Java, 520-JAVA.md possède les règles Java correspondantes. La présence d'AGP, d'un JDK de build ou d'un script Gradle ne suffit pas à rendre le profil Java applicable au code produit.
Un autre langage applicatif MAY être utilisé lorsqu'il correspond à la stack réelle du projet. Le profil Android possède uniquement les contraintes imposées par la plateforme et ne transforme pas un choix de langage local en règle Android générale.
Groovy DSL ou Kotlin DSL MAY être utilisés par Gradle comme langage de configuration conformément à 522-GRADLE.md. Leur présence dans le build ne détermine pas le langage applicatif.
Les fichiers Gradle SHOULD rester aussi déclaratifs et courts que raisonnablement possible. Une logique de build importante SHOULD être possédée par une abstraction ou un plugin identifiable plutôt que devenir du code produit caché dans un script Gradle.
Les annotations fonctionnelles Android ou de frameworks restent autorisées lorsqu'elles constituent le mécanisme officiel de l'API concernée.
Matrice AGP / Gradle / JDK
Un projet Android qui utilise AGP MUST exprimer une chaîne de build compatible.
La matrice conceptuelle est :
Android Gradle Plugin
↕
Gradle
↕
JDK de build
La version AGP retenue peut également contraindre les niveaux Android SDK supportés par la chaîne de build. Cette compatibilité appartient au scope Android ; les règles Gradle générales restent possédées par 522-GRADLE.md.
PGR MUST NOT imposer globalement une version Gradle, AGP ou JDK uniquement parce qu'elle est utilisée par un autre projet Android.
La contrainte applicable peut être :
minimum
range min..max
version exacte / pin
latest compatible
Le projet choisit la forme la moins restrictive qui reste réellement compatible avec sa stack et effectivement vérifiable.
Le JDK utilisé pour exécuter Gradle/AGP est une contrainte de build Android même lorsqu'aucun code source Java n'existe. Lorsqu'un projet contient du Java, le niveau Java du code source et du bytecode reste un contrat distinct possédé par 520-JAVA.md.
PGR MUST NOT confondre :
JDK qui exécute Gradle / AGP
≠
niveau Java du code applicatif
Le choix Wrapper ou Gradle système, ainsi que la manière de vérifier la contrainte Gradle, restent possédés par 522-GRADLE.md. Une matrice Android plus étroite MAY raffiner cette contrainte dans le seul scope Android.
compileSdk, targetSdk et minSdk
Ces trois valeurs représentent des contrats différents.
compileSdk définit le niveau d'API Android disponible lors de la compilation. Il doit être compatible avec la version AGP réellement utilisée et MAY évoluer sans entraîner mécaniquement une hausse de targetSdk ou minSdk.
targetSdk déclare le niveau Android pour lequel l'application a été adaptée et testée du point de vue des comportements de plateforme. Il MUST respecter les exigences applicables au canal de distribution réellement visé.
minSdk définit le plus ancien niveau d'API Android que le produit choisit réellement de supporter. Il participe notamment à l'éligibilité d'installation sur les appareils plus anciens.
PGR MUST NOT déduire une hausse de minSdk d'une hausse de compileSdk ou targetSdk.
Le choix de minSdk MUST être justifié par le contrat produit et ses contraintes réelles : population visée, capacités nécessaires, dépendances, sécurité, coût de maintenance et preuves de compatibilité. PGR ne privilégie ni le niveau le plus bas possible ni une hausse de confort sans justification.
Une hausse de minSdk retire explicitement des appareils auparavant éligibles ; elle constitue donc un changement de compatibilité utilisateur et MUST être traitée comme tel.
Identité applicative et namespace
Pour un module application Android, applicationId et namespace sont deux contrats distincts.
applicationId identifie l'application installée et distribuée. Pour une application déjà publiée, le modifier ne constitue pas un simple renommage de code : il crée une identité applicative différente du point de vue de la plateforme et des canaux de distribution.
namespace possède l'espace de noms utilisé par le code et les ressources générées du module. Il MAY évoluer indépendamment de applicationId lorsque le projet a une raison réelle de dissocier identité distribuée et organisation du code.
PGR SHOULD conserver namespace et applicationId alignés lorsque cela suffit, mais MUST NOT les confondre ni dériver implicitement l'identité distribuée d'un renommage de namespace. Toute divergence ou modification d'applicationId doit être explicite dans la configuration Android concernée.
Les valeurs concrètes telles que com.example.product appartiennent au projet ; PGR n'impose aucun domaine ou préfixe universel.
VERSION, versionName et versionCode
Lorsqu'une application Android appartient au même release train que le projet, le fichier PGR VERSION reste la version SemVer canonique de cette unité de release.
versionName est un miroir technique de cette version lorsqu'elle doit représenter la même release à l'utilisateur ou au canal de distribution.
versionCode est un compteur Android monotone distinct du SemVer.
PGR MUST NOT confondre versionCode avec VERSION ou versionName.
Pour une application publiée, versionCode MUST NOT diminuer. Lorsqu'un dépôt publie plusieurs applications indépendantes, chaque application MAY posséder son propre compteur versionné.
Le projet MAY stocker ce compteur dans un fichier explicite tel que :
Android/app/VERSION_CODE
si cela correspond à son architecture.
PGR SHOULD NOT imposer une formule dérivant automatiquement versionCode du SemVer sans décision explicite du projet.
Un futur audit read-only MAY vérifier séparément :
VERSION ↔ versionName
VERSION_CODE ↔ configuration Android
lorsqu'un projet ou skeleton réel fournit des fichiers à contrôler. Cet audit ne doit jamais modifier les versions.
Configuration locale
local.properties appartient à l'environnement local du build Android/AGP, notamment pour des chemins machine tels que l'emplacement du SDK. Il SHOULD rester hors Git.
PGR MUST NOT utiliser local.properties comme source normative de configuration partagée ni comme fourre-tout pour des propriétés locales propres au produit. La documentation Android réserve ce fichier aux propriétés locales comprises par la toolchain Android ; une propriété locale spécifique au projet doit utiliser un mécanisme séparé et explicitement possédé.
Les propriétés Gradle partagées, portables et non secrètes restent gouvernées par 522-GRADLE.md. Les chemins machine, credentials, secrets et overrides développeur restent locaux, via variables d'environnement, propriétés utilisateur ou fichier explicitement ignoré selon le besoin réel.
Si l'outil ou l'IDE régénère intégralement un état local, aucun fichier exemple n'est nécessaire. Lorsqu'une valeur locale obligatoire n'est pas automatiquement reproductible, un template MAY être fourni conformément aux règles générales PGR.
Un fichier local tel que keystore.properties ou une variante *.local.properties MAY exister lorsqu'il possède une responsabilité claire, mais il MUST rester hors Git lorsqu'il contient des secrets ou valeurs propres à la machine.
Signing et secrets
L'interdiction générale de versionner ou distribuer des secrets reste possédée par RULES.md. Le profil Android ajoute uniquement les conséquences propres au signing de cette plateforme.
Dans le scope Android, les éléments suivants sont notamment des secrets ou artefacts privés soumis à cette interdiction :
release / upload keystore
private signing key
passwords
credentials
service account secret
Une configuration versionnée MAY référencer des variables ou propriétés telles que :
RELEASE_KEYSTORE
RELEASE_KEY_ALIAS
mais MUST NOT contenir leurs valeurs privées.
Le debug keystore généré par les outils Android est un état local de développement et ne doit pas être promu comme identité de signing de release.
Les clés de release ou d'upload appartiennent à une frontière de sécurité durable de l'application publiée. Leur stockage, sauvegarde, rotation ou délégation au canal de distribution doit être décidé explicitement par le projet sans introduire la matière secrète dans Git.
Le signing de release ne doit pas être requis pour une validation ordinaire de développement sauf lorsque la tranche valide précisément la distribution ou la signature finale.
Modules Android
Les modules Android SHOULD être nommés par responsabilité.
Des noms tels que :
app
common
game-reflex
game-snake
peuvent être légitimes lorsque ces responsabilités existent réellement.
Des noms opaques tels que module1, module2, misc ou utils2 SHOULD NOT servir de structure durable.
Un module partagé doit posséder une responsabilité commune réelle ; il ne doit pas devenir un dépôt générique de code sans owner.
Dépendances Android
Les dépendances Android doivent rester minimales et explicites.
Une dépendance officielle et étroite SHOULD être préférée à un framework beaucoup plus large lorsqu'une petite capability suffit.
À l'inverse, PGR SHOULD NOT réimplémenter une API de plateforme, un protocole standard ou une primitive de sécurité uniquement pour éviter une dépendance officielle appropriée.
Une BOM ou un mécanisme officiel de gestion de versions MAY être utilisé lorsqu'il réduit réellement les incompatibilités. Il ne doit pas entraîner l'ajout automatique de toute une famille de dépendances non utilisées.
La politique d'un lockfile Android/Gradle, lorsqu'un projet en utilise un, doit être décidée selon le besoin réel de cet écosystème et du projet. Elle n'est pas déduite automatiquement d'un autre profil.
NDK, ABI et code natif
Un projet Android sans bibliothèque native directe ou transitive n'a pas besoin de NDK ni de matrice ABI propre au produit.
Dès qu'un projet contient du code natif via NDK, C/C++, Rust, un SDK précompilé ou une autre frontière native, la toolchain native réellement nécessaire et les ABI réellement supportées MUST être explicites.
PGR ne fixe ni version NDK ni liste universelle d'ABI. La version NDK MAY être épinglée lorsqu'une reproductibilité, une dépendance ou une exigence de packaging le justifie ; elle ne doit pas être copiée depuis un autre projet par défaut.
Les mécanismes tels que abiFilters MAY exprimer la matrice voulue lorsque Gradle/AGP les utilise. La configuration choisie doit refléter le contrat produit et le canal de distribution plutôt qu'une liste maximale par principe.
Une ABI annoncée comme supportée doit disposer d'une preuve adaptée à la propriété annoncée. Il faut distinguer au minimum :
compilation native
→ la bibliothèque est produite pour l'ABI
packaging
→ la bibliothèque et ses dépendances natives sont présentes dans l'artefact Android attendu
runtime
→ le package pertinent s'installe et exécute le chemin critique sur un environnement représentant l'ABI / API concernée
Une cross-compilation native seule ne prouve donc ni l'intégration dans l'APK/AAB, ni le lifecycle Android, ni l'exécution sur device/AVD.
Les bibliothèques natives précompilées ou apportées par un SDK font partie du package final et MUST respecter les mêmes contraintes de compatibilité que les bibliothèques produites par le projet.
Les règles JNI, Rust, SDL, cargo ndk ou toute autre chaîne native spécialisée appartiennent à leurs owners/projets respectifs et restent hors de ce document tant qu'un profil générique séparé n'est pas justifié.
Android Lint
Android Lint est une analyse statique Android distincte de la compilation et des tests.
Lorsqu'un changement touche du code, des resources, un manifest, une configuration Android ou une dépendance susceptible d'être analysée par Lint, la gate SHOULD exécuter la tâche Lint du module et du variant pertinents.
PGR MUST NOT supposer qu'un build Gradle ordinaire exécute Lint automatiquement. Les commandes exactes (lint, lintDebug, lintRelease ou équivalent) appartiennent au projet et à sa stratégie Wrapper/Gradle système.
Une baseline Lint MAY être versionnée lorsqu'elle sert réellement à isoler la dette existante des nouvelles régressions. Elle ne doit pas servir à masquer silencieusement de nouveaux diagnostics applicables.
Niveaux de tests Android
PGR distingue au moins trois niveaux de preuve Android lorsqu'ils sont applicables :
JVM unit
→ logique exécutée sur la JVM hôte sans runtime Android réel
instrumented / integration
→ test exécuté sur device ou émulateur avec le framework Android
smoke device / AVD
→ application ou package réel installé et chemin critique exécuté dans un environnement Android
Un test JVM MUST NOT être enregistré comme preuve d'un comportement réel d'Activity, de lifecycle, de package ou de device.
Un test instrumenté prouve le comportement couvert par son runner et son environnement, mais ne remplace pas automatiquement un smoke du package final lorsque la tranche modifie packaging, signing, native libraries, manifest de lancement ou installation.
Les tâches de tests SHOULD être ciblées par module/variant lorsque cela suffit. Une matrice instrumentée ou multi-device large n'est requise que lorsqu'elle couvre un risque réellement modifié ou une phase de release qui l'exige.
Un appareil physique n'est pas obligatoire pour chaque release. Il devient nécessaire lorsqu'une propriété annoncée dépend d'un matériel, d'une ABI ou d'un comportement qui ne peut pas être suffisamment prouvé par AVD.
Ordre de validation Android
Une validation Android ordinaire SHOULD progresser du ciblé vers le plus coûteux :
format applicable
↓
audits read-only applicables
↓
compilation module ciblé
↓
lint Android ciblé
↓
unit tests ciblés
↓
assemble/package lorsque nécessaire
↓
install
↓
smoke
Les tests globaux, l'instrumentation large, les bundles de release, les matrices multi-ABI et les smokes multi-device sont sélectionnés lorsque le scope ou la phase de release l'exige réellement.
Les commandes exactes appartiennent à la matrice du projet ou du skeleton qui possède un Android build réel.
clean reste une opération de maintenance et ne doit pas précéder automatiquement chaque gate.
Manifest et ressources
AndroidManifest.xml MUST déclarer uniquement les composants, permissions et capabilities de plateforme réellement nécessaires au module.
Une permission sensible ne doit pas être ajoutée « au cas où ». Son introduction constitue un changement significatif qui doit être visible dans le delta et, lorsque pertinent, dans la documentation de release.
applicationId et namespace restent possédés par la configuration Android du module ; PGR SHOULD éviter de créer des sources de vérité concurrentes ou des copies divergentes de ces identités dans des fichiers séparés.
src/main/res/ reste la source canonique des ressources Android d'un module standard.
Dans un projet multi-plateforme, des assets réellement partagés MAY vivre dans un owner commun hors d'Android si leur consommation est définie clairement.
PGR SHOULD NOT maintenir manuellement plusieurs copies divergentes du même asset source dans des arborescences de plateforme différentes.
APK, AAB et artefacts de distribution
PGR distingue les rôles des principaux artefacts :
APK debug
→ développement, installation directe et smokes ordinaires
APK release
→ validation d'un package release installable lorsque nécessaire
AAB
→ artefact de distribution lorsque le canal cible l'exige ; le canal génère ensuite les APK servis aux appareils
La phase de release, le canal de distribution et le scope modifié déterminent l'artefact nécessaire.
Un AAB n'est pas directement une preuve d'installation ou d'exécution sur device. Lorsqu'une propriété runtime ou de packaging doit être prouvée, la gate doit aussi utiliser un APK approprié ou les APK dérivés du bundle selon le canal et le risque concernés.
Une alpha documentaire n'a pas besoin d'un package Android réel si aucun projet Android n'est concerné. Une release d'une application Android peut au contraire nécessiter un package ou smoke réel lorsque versionName, versionCode, signing, manifest, code natif ou packaging sont modifiés.
La promotion stable ne doit pas provoquer mécaniquement un full rebuild sans preuve invalidée ; elle doit toutefois revalider le packaging ciblé lorsque les métadonnées ou composants qui entrent dans l'artefact ont changé.
Les exigences telles que le niveau targetSdk minimal, le format de publication ou les délais de compatibilité appartiennent au canal de distribution et évoluent indépendamment de PGR. Un projet publié MUST vérifier la politique officielle courante de son canal avant une release concernée ; PGR ne transforme pas une valeur datée de Google Play en default Android universel.
Pages mémoire 16 KB et packaging natif
Android supporte des appareils configurés avec des pages mémoire de 16 KB. Cette responsabilité est conditionnelle : un projet sans bibliothèque native directe ou transitive n'a pas de segments ELF à réaligner, même s'il SHOULD tester les comportements importants sur les environnements Android qu'il prétend supporter.
Lorsqu'une application contient du natif et que la plateforme ou le canal de distribution exige la compatibilité 16 KB, le package final MUST être compatible. La preuve doit couvrir les bibliothèques natives du projet ainsi que les dépendances natives précompilées réellement embarquées.
Pour Google Play, la politique officielle courante vérifiée pendant 0.1.3 impose le support 16 KB sur appareils 64 bits aux applications ciblant Android 15 / API 35 ou supérieur. Cette politique est évolutive : le projet MUST la revalider auprès de la documentation officielle au moment où elle devient une gate de release.
Une preuve de compatibilité native 16 KB SHOULD couvrir, selon l'artefact réellement distribué :
ELF 64 bits
→ segments LOAD des bibliothèques embarquées compatibles avec l'alignement 16 KB
APK
→ alignement ZIP des bibliothèques natives vérifié sur le package final
AAB
→ configuration d'alignement du bundle vérifiée lorsque ce bundle est l'artefact de distribution
runtime
→ smoke sur device/AVD 16 KB lorsque le comportement runtime ou la distribution concernée le justifie
Les outils Android officiels peuvent notamment contrôler les segments ELF, zipalign -P 16 pour un APK et l'alignement déclaré par bundletool pour un AAB. Ces commandes sont des moyens de preuve, pas des noms de fichiers ou chemins machine à figer dans PGR.
Une toolchain récente peut fournir cette compatibilité par défaut, mais PGR MUST NOT imposer une version AGP/NDK globale uniquement pour cette raison. La toolchain retenue doit satisfaire la politique courante du canal et toutes les bibliothèques natives précompilées doivent être compatibles elles aussi.
Un mode de compatibilité de plateforme ou le simple fait que l'application démarre sur un appareil 16 KB ne remplace pas la preuve de conformité du package natif lorsque le canal de distribution l'exige.
Validation et futurs audits PGR
Les catégories générales et l'autorité du gate restent possédées par 400-VALIDATION.md.
PGR lui-même ne contient actuellement aucun projet Android à compiler, installer ou exécuter. Cette tranche ne prétend donc pas valider AGP, Gradle, SDK, AVD, APK ou AAB réels.
Aucun audit Android spécialisé n'est créé uniquement pour remplir le profil.
Lorsqu'un skeleton ou projet concret fournira les fichiers nécessaires, des audits monotâches MAY vérifier des propriétés structurelles stables telles que la cohérence de version, la présence d'une configuration locale ignorée ou une matrice de compatibilité explicitement déclarée. Ces audits restent read-only et ne remplacent jamais Gradle, Android Lint, l'installation ou les smokes.