Activation de la Compilation Kotlin Incrémentale sur Buck2 avec l’API Build Tools KEEP

TL;DR

La compilation incrémentielle Kotlin est désormais intégrée à Buck2 pour accélérer les builds en ne reconstruisant que les fichiers modifiés.
L’approche utilise l’API Build Tools KEEP, offrant une intégration stable et orientée vers l’avenir, avec gestion des problèmes de shading et de conflits de classpath.
Les actions incrémentielles Buck2 préservent les sorties entre les exécutions et utilisent des hachages pour détecter les changements et ne recompilent que le nécessaire.
Certains modules critiques atteignent jusqu’à 3x plus vite, démontrant des gains de productivité significatifs à l’échelle.
Les plugins et le traitement des annotations (KSP2) sont adaptés pour fonctionner avec des tours incrémentiels, garantissant des résultats cohérents sur plusieurs passes. Source : blog d’ingénierie de Meta sur l’activation de la compilation incrémentielle Kotlin dans Buck2. Voir https://engineering.fb.com/2025/08/26/open-source/enabling-kotlin-incremental-compilation-on-buck2/ pour le récit détaillé.

Contexte et antécédents

Le compilateur Kotlin incrémentiel offre depuis longtemps un gain de temps en recompilant uniquement les portions modifiées d’un code. Buck2, le système de build de Meta, prône également de petits modules pour obtenir des builds rapides grâce au parallélisme et à l’exécution incrémentielle. À mesure que les bases de code grossissent et que les équipes évoluent, certains modules deviennent plus volumineux et peuvent influencer le temps total de compilation. Pour explorer si la compilation incrémentielle pouvait apporter des gains mesurables dans Buck2, Meta a évalué le compilateur Kotlin incrémentiel dans la chaîne d’outils Android. Le bénéfice central de la compilation incrémentielle est simple : plutôt que de reconstruire tout le module, le compilateur se concentre sur les fichiers modifiés et ceux qui en dépendent. Meta a observé que plusieurs modules critiques pourraient en tirer un bénéfice significatif, avec des builds accélérés jusqu’à trois fois. Cette constatation a motivé un effort d’intégration plus approfondi, équilibrant stabilité à long terme et besoin de rapidité. Sur le plan technique, certains défis se posent. Au moment de Kotlin 2.2.0, le seul contrat public garanti pour le compilateur est via l’interface en ligne de commande (CLI). La CLI ne supporte pas la compilation incrémentielle, ce qui a poussé Meta vers des points d’intégration alternatifs. Les API internes du compilateur ne sont pas destinées à l’usage public et peuvent être instables face aux évolutions du Kotlin. L’API Build Tools (KEEP), introduite avec Kotlin 1.9.20, s’est imposée comme le point d’intégration officiel et plus stable qui inclut la compilation incrémentielle. La décision a été d’adopter KEEP, tout en ayant l’ambition d’influencer sa direction future. Un autre défi pratique venait des conflits de classpath entre les jars du compilateur Kotlin « shade » et le toolchain Android historiquement construit autour d’un compilateur non shade. Pour résoudre ce problème, Meta a d’abord procédé à une désombrement temporaire de l’API Build Tools (avec jarjar) afin d’obtenir un prototype fonctionnel, puis a migré l’outil complet vers le compilateur shade pour assurer une stabilité à long terme. Pour activer la compilation incrémentielle, Buck2 doit accéder aux sorties de la construction précédente, car Buck2 supprime les sorties par défaut avant de reconstruire un module. L’équipe a introduit un mode dans les actions incrémentielles qui permet de supprimer la suppression automatique, afin de réutiliser les sorties passées. Cela implique que les développeurs doivent nettoyer manuellement ce qui n’est plus utile. Ce changement était indispensable pour débloquer l’incrémentalité tout en maintenant l’hygiène du cache. L’objectif plus large était également de supporter les builds distribués—Buck2 peut être exécuté à distance et renvoyer les résultats. Pour cela, un cache de compilation relocatable est crucial afin d’éviter les conflits de chemin entre différentes machines. Meta a configuré explicitement le répertoire racine du projet et le répertoire de build dans les paramètres d’incrémentalité afin de préserver la stabilité du cache entre les différents workers et environnements.

Ce qui est nouveau

Adoption de l’API KEEP comme point d’intégration officiel pour la compilation incrémentielle du Kotlin dans Buck2, fournissant une voie plus durable et orientée vers l’avenir.
Mise en place d’un workaround lors de la prototypisation pour désombreer l’API Build Tools (avec jarjar) avant d’adopter le compilateur shade complet, garantissant un prototype opérationnel avant la migration complète.
Buck2 incrémentiel préserve les sorties entre exécutions et génère des digests de hash pour chaque entrée d’action afin de détecter précisément les changements et de ne recompilar que le nécessaire.
La détection de changements peut être automatique ou manuelle. L’automatique dépend de la version du Kotlin; pour les versions antérieures à 2.1.20, il faut fournir une liste des fichiers modifiés. Même avec la détection automatique, fournir la liste peut optimiser le processus.
Des snapshots de classpath capturent l’ABI des bibliothèques. En les comparant avec les snapshots précédents, le compilateur peut déterminer quels fichiers du module sont affectés par des changements de dépendances. Une action dédiée génère ces snapshots et l’artéfact peut être mis en cache ou exécuté à distance pour éviter un traitement local lourd.
Si l’analyse des dépendances réalisée par l’outil de build identifie déjà les changements pertinents, la comparaison des snapshots peut être sautée pour accélérer la build.
Intégrer la compilation incrémentielle avec des plugins personnalisés a exigé des adaptations : les plugins doivent être incrémentaux et capables de traiter des entrées partielles, car la compilation incrémentielle peut fonctionner sur des sous-ensembles de fichiers lors de rondes successives. Le Kotlin Symbol Processing (KSP2) a été utilisé pour le traitement des annotations, et KSP2 agit comme un outil autonome qui utilise l’API d’analyse Kotlin, ce qui aide à maintenir la compatibilité avec l’incrémentalité.

Pourquoi cela compte (impact pour les développeurs/entreprises)

L’intégration offre des gains de productivité en réduisant le temps nécessaire pour reconstruire de grandes bases de code Android. En réutilisant les sorties et en ne recompilant que les fichiers modifiés, les builds se terminent plus rapidement, ce qui raccourcit les cycles de cycle de retour et améliore les retours de développement. Dans les environnements de build distribués, un cache relocatable et stable est essentiel pour éviter les conflits de chemin entre machines différentes. Ce travail aide aussi les équipes à faire évoluer leurs toolchains à mesure que les modules grandissent et que les équipes s’agrandissent, tout en conservant la satisfaction des développeurs et l’efficacité des builds.

Détails techniques ou Mise en œuvre

Le compilateur Kotlin incrémentiel nécessite l’accès aux sorties précédentes, que Buck2 efface normalement par défaut. L’équipe a configuré les actions incrémentielles de Buck2 pour préserver ces sorties, avec l’avertissement que les développeurs doivent nettoyer manuellement les sorties obsolètes. Cela rend possible l’état antérieur pour la compilation incrémentielle.
La détection de changement peut être automatique ou manuelle. L’automatique dépend de la version Kotlin; pour les versions antérieures à 2.1.20, il faut fournir une liste de fichiers modifiés. Même avec détection automatique, fournir la liste peut améliorer les performances.
Buck2 capture des digests de hash pour chaque entrée d’action afin de déterminer ce qui a changé depuis la construction précédente. Cela permet d’identifier précisément les fichiers affectés et de minimiser le travail inutile.
Snapshots de classpath capturent l’état ABI des bibliothèques. En les comparant aux snapshots précédents, le compilateur peut déterminer les fichiers du module affectés par des changements de dépendances. Une action séparée génère ces snapshots et l’artefact peut être mis en cache ou exécuté à distance pour éviter un traitement local lourd.
Si l’analyse des dépendances réalisée par l’outil d’intégration identifie déjà les changements pertinents, la comparaison des snapshots peut être ignorée pour accélérer la build.
L’intégration avec des plugins personnalisés a exigé des ajustements : les plugins doivent être incrémentaux et capables de traiter des entrées partielles, car le compilateur incrémentiel peut opérer sur des sous-ensembles de fichiers sur plusieurs passes. Le KSP2 est utilisé pour le traitement des annotations et agit comme un outil autonome utilisant l’API d’analyse Kotlin pour rester compatible avec l’incrémentalité.