Installation et configuration
La CLI tk-ota-push (également accessible via l'alias tkushpatch) est un outil en ligne de commande écrit en pur Dart. Elle permet de compiler les applications Flutter avec la toolchain patchée Shorebird, de verrouiller les binaires de référence lors d'une publication Store (release), de générer et signer les patchs différentiels (patch), de promouvoir les patchs entre canaux (promote) et de récupérer les symboles d'obfuscation (symbols).
Prérequis techniques
Avant d'installer et d'exécuter tk-ota-push, assurez-vous que votre poste de travail ou votre agent CI/CD dispose des éléments suivants :
| Composant | Version / Chemin | Rôle |
|---|---|---|
| SDK Dart | >=3.5.4 <4.0.0 | Exécution de la CLI tk_ota_push et gestion des dépendances |
| Toolchain Shorebird | ~/.shorebird/bin/cache/flutter | Moteur Flutter patché incluant flutter, dart, gen_snapshot_arm64, analyze_snapshot_arm64 et aot-tools.dill |
| Android SDK / Gradle | Requis pour -p android | Compilation des archives .apk et .aab |
| Xcode & Command Line Tools | Requis pour -p ios (macOS uniquement) | Compilation de Runner.app, des archives .xcarchive et exportation .ipa |
| curl | Standard POSIX | Utilisé à la volée sur iOS si aot-tools.dill doit être récupéré pour la révision du moteur |
La classe Toolchain.locate() inspecte automatiquement le répertoire $HOME/.shorebird/bin/cache/flutter (ou %USERPROFILE%\.shorebird\bin\cache\flutter sous Windows). Si ce dossier est absent ou vide, la CLI retourne immédiatement le code de sortie 69 (EX_UNAVAILABLE).
Installation globale
1. Depuis un dépôt ou serveur de packages (recommandé)
Activez globalement le package tk_ota_push via le gestionnaire pub de Dart :
dart pub global activate tk_ota_push
2. Depuis une copie locale du code source (mode monorepo / développement)
Si vous travaillez directement dans le dépôt de la plateforme, activez la CLI à partir de son chemin local :
dart pub global activate --source path ./tk_ota_push
3. Configuration du PATH
Assurez-vous que le dossier des exécutables globaux de Dart figure dans votre variable d'environnement PATH :
- macOS / Linux (
~/.zshrcou~/.bashrc) :export PATH="$PATH":"$HOME/.pub-cache/bin" - Windows (PowerShell) :
$env:Path += ";$env:LOCALAPPDATA\Pub\Cache\bin"
Alias d'exécutables disponibles
Le fichier pubspec.yaml du package tk_ota_push déclare deux exécutables strictement équivalents pointant vers bin/tk_ota_push.dart (TkOtaPushRunner) :
executables:
tk-ota-push: tk_ota_push
tkushpatch: tk_ota_push
Vous pouvez également invoquer la CLI sans activation globale si tk_ota_push est listé dans les dependencies ou dev_dependencies de votre projet Flutter :
# Exécutable principal
tk-ota-push --help
# Alias court
tkushpatch --help
# Exécution directe via Dart dans le projet
dart run tk_ota_push --help
Vérification de l'installation
Pour vérifier que la CLI est opérationnelle et correctement reliée à votre environnement :
# 1. Afficher l'aide générale et vérifier le binaire
tk-ota-push --help
# 2. Vérifier l'état de la session locale (~/.tk_ota_push/credentials.json)
tk-ota-push whoami
Si aucune session n'est active, whoami affiche :
Aucune session active. Lancez `tk-ota-push login`.
Alignement automatique avec le SDK Flutter Shorebird
Lors de l'exécution d'une commande release ou patch, la CLI vérifie automatiquement le fichier .dart_tool/package_config.json du projet cible. Si les dépendances avaient été résolues avec un SDK Flutter système différent de la toolchain Shorebird (~/.shorebird/bin/cache/flutter), tk-ota-push exécute automatiquement :
- Synchronisation automatique des dépendances avec le SDK Flutter Shorebird (flutter pub get)...
De plus, chaque sous-processus de compilation est lancé avec les variables d'environnement FLUTTER_ROOT et PATH pointant en priorité absolue vers la toolchain Shorebird, évitant tout conflit d'API interne (comme semantics.dart ou sky_engine).
Mise à jour et désinstallation
Pour mettre à jour la CLI vers la dernière version disponible :
dart pub global activate tk_ota_push
Pour désinstaller l'exécutable global :
dart pub global deactivate tk_ota_push