Android ADB Management - VS Code

Pilotez vos appareils et émulateurs Android depuis VS Code : sélection de cible, ouverture d’un AVD, compilation Gradle, installation d’APK, Logcat, transferts, captures et scrcpy.

Publisher DataTemplar · Licence MIT · Téléchargements et versions.

L’extension fonctionne sur l’hôte du workspace et s’utilise notamment avec Linux et Remote WSL/WSLg. Consultez les prérequis et les limites connues pour choisir votre environnement. Le débogage Kotlin n’est pas pris en charge.

Sommaire

• Prérequis
• Installer l’extension
• Premiers pas
• Guide des fonctions
• Réglages
• Dépannage
• Sécurité et confidentialité
• Limites connues
• Développer, auditer et réutiliser
• Versions et publication
• Logo de l’extension

Prérequis

Les outils doivent être installés sur l’hôte du workspace, celui qui exécute l’extension. Dans Remote WSL, il s’agit de la distribution Linux, même si la fenêtre VS Code est affichée sous Windows. Utilisez les outils et chemins Linux de cette distribution.

L’extension ne fournit ni Python, ni JDK, ni SDK, ni scrcpy. Le téléchargement d’une image système est une action explicite, après examen des licences. Un projet Gradle n’est nécessaire que pour compiler ; l’installation d’un APK existant et les outils ADB fonctionnent indépendamment.

Installer l’extension

Depuis le Marketplace

Dans Extensions (Ctrl+Shift+X), recherchez l’identifiant :

DataTemplar.android-adb-management-vscode

Vérifiez le publisher DataTemplar sur la fiche Marketplace. Dans Remote WSL, choisissez l’installation dans WSL: votre distribution. Si la fiche n’est pas disponible, utilisez un fichier VSIX.

L’accès aux sources et aux téléchargements GitHub dépend des droits sur le dépôt. L’installation depuis le Marketplace ne nécessite pas cet accès.

Depuis un fichier VSIX

1. Téléchargez le fichier .vsix joint à la release souhaitée, ou construisez-le depuis les sources.
2. Dans Extensions → … → Installer à partir du VSIX…, sélectionnez ce fichier.
3. Rechargez la fenêtre si VS Code le demande. En Remote WSL, vérifiez l’installation côté WSL.

Vous pouvez aussi utiliser le terminal VS Code connecté à cet hôte, en remplaçant le chemin par celui du fichier téléchargé :

code --install-extension "/chemin/vers/extension.vsix"

Les réglages de l’extension sont regroupés sous le préfixe androidAdb.*.

Premiers pas

1. Vérifier l’environnement

Ouvrez un dossier de confiance dans VS Code, puis la palette (Ctrl+Shift+P) et Android ADB : Diagnostiquer l’environnement Android. Le résultat indique l’hôte, Python, les outils trouvés, leurs chemins et leurs versions. Les sorties des commandes sont accessibles dans Affichage → Sortie → Android ADB — journaux.

Si nécessaire, renseignez androidAdb.sdkPath et androidAdb.pythonPath dans les paramètres utilisateur de cet hôte, puis rechargez la fenêtre après un changement d’interpréteur. Un workspace en mode restreint ne démarre aucun backend ni outil Android/Gradle.

2. Choisir un appareil ou un émulateur

Ouvrez Android ADB → Appareils et émulateurs dans la barre d’activité. Cliquez sur la cible voulue : son nom apparaît dans la barre d’état. Par défaut, aucune cible n’est choisie automatiquement, même s’il n’y en a qu’une.

Pour un téléphone physique, activez les options développeur et le débogage USB, puis acceptez la demande d’autorisation affichée par Android. Vérifiez que adb devices -l, exécuté sur l’hôte du workspace, voit bien l’appareil. WSL ne récupère pas automatiquement les périphériques USB de Windows.

3. Ouvrir Android sans compiler

Sélectionnez un AVD puis cliquez sur ▶ Ouvrir l’émulateur Android (sans compilation), dans la barre du panneau ou sur la ligne de l’AVD. Une fenêtre Android native s’ouvre sur l’affichage de l’hôte. Aucun projet Gradle n’est demandé. Un AVD déjà actif est réutilisé ; sa fenêtre peut se trouver sur un autre bureau.

4. Compiler, installer et ouvrir votre application

1. Ouvrez le projet Android et sélectionnez la cible.
2. Exécutez Android ADB : Choisir le projet, module et variante….
3. Choisissez la racine contenant le wrapper Gradle, le module application (par exemple :app) et la variante (par exemple debug). La découverte des variantes exécute Gradle.
4. Exécutez Compiler, installer et ouvrir l’application, depuis le panneau ou le bouton ⏵⏵ de la ligne de cible.
5. Consultez la progression et Android ADB — journaux. Annuler l’opération en cours interrompt les processus de la commande ; un émulateur démarré reste ouvert.

La compilation doit réussir avant l’installation. Le parcours Gradle exige un APK unique, vérifié avec les métadonnées AGP et aapt. L’installation utilise -r pour conserver les données ; une signature incompatible ou une version antérieure peut être refusée par Android, sans désinstallation automatique.

Guide des fonctions

La palette Android ADB et le Catalogue des actions Android… donnent accès aux commandes. Le catalogue permet de chercher une action et explique les outils ou cibles manquants. Certaines actions sont aussi disponibles dans le menu contextuel d’un appareil.

Applications et APK existants

Pour installer un APK sans compiler, sélectionnez une cible prête, ouvrez Installer un APK…, indiquez l’utilisateur Android (current par défaut), choisissez le fichier, puis vérifiez la confirmation. Le fichier doit être accessible sur l’hôte du workspace. Un split isolé est refusé.

Les commandes d’applications permettent de lister les paquets utilisateur/système/tous, ouvrir ou relancer une application, l’arrêter, gérer des permissions et ouvrir une URL ou un lien profond. Android peut refuser une opération selon les droits de l’appareil.

Désinstaller une application… et Effacer les données d’une application… demandent une confirmation précisant le package et la cible. Extraire les APK d’une application… écrit la base et ses éventuels splits dans un nouveau dossier ; leur réinstallation nécessite l’ensemble des fichiers avec adb install-multiple -r.

Logcat

1. Sélectionnez une cible prête et exécutez Ouvrir une session Logcat….
2. Choisissez une application ou tous les journaux, puis l’affichage Webview ou terminal.
3. Dans la Webview, ajustez application, niveau minimal et tags. Vous pouvez copier le tampon, mettre en pause et reprendre.

Plusieurs sessions peuvent rester ouvertes. Les nouveaux PID de l’application et ses processus secondaires sont suivis. Pause arrête la collecte ; la reprise lit les nouvelles lignes et ne récupère pas celles de la pause. Effacer l’affichage ne touche pas aux journaux Android ; leur effacement sur l’appareil demande confirmation. Fermer la vue ou le terminal termine sa session.

Le tampon d’affichage est borné et les pertes lors d’un fort débit sont signalées. Les buffers lus sont main, system et crash.

Captures et écran avec scrcpy

• Capturer l’écran… enregistre un PNG dans un nouveau fichier local.
• Enregistrer une vidéo… propose une durée de 1 à 180 secondes, sous réserve des limites de l’appareil. Arrêter la vidéo et la récupérer finalise la capture ; Annuler abandonne le résultat.
• Créer un bugreport… produit un ZIP local et peut prendre plusieurs minutes. Relisez-le avant de le partager : il peut contenir des données sensibles.
• Informations appareil et batterie affiche les champs disponibles ; certains peuvent manquer selon Android.
• Ouvrir scrcpy… propose Standard, Faible bande passante et Lecture seule. Fermer son terminal ou utiliser Ctrl+C termine la session. Consultez le guide scrcpy pour l’installation et les limites des serveurs distants.

Les captures sont finalisées après succès et les collisions de destination sont refusées.

Fichiers et redirections de ports

Envoyer un fichier ou dossier… et Récupérer un fichier ou dossier… demandent une source et un nouveau chemin de destination, sans fusion ni écrasement. Les chemins Android sont absolus ; les fichiers locaux appartiennent à l’hôte du workspace. Les permissions Android restent applicables.

Les commandes forward et reverse listent, créent et suppriment les redirections de la cible sélectionnée. La suppression générale concerne cette seule cible. La création TCP refuse de réaffecter une règle existante ; tcp:0 permet d’obtenir un port libre. Les sockets Unix nommés et certaines destinations JDWP sont acceptés selon la direction, sans fournir de débogueur Kotlin.

Réseau, shell et serveur ADB

Appairer un appareil… demande l’adresse et le port d’appairage affichés par Android, puis le code dans un champ masqué. Connecter une adresse… utilise le port de connexion, distinct du port d’appairage ; networkPort vaut 5555 par défaut. Une adresse IPv6 avec port s’écrit [IPv6]:port.

Le catalogue propose aussi mDNS, déconnexion, modes USB/TCP-IP et redémarrages Android/recovery/bootloader. Après une reconnexion ou un changement de transport, sélectionnez de nouveau l’appareil. Les possibilités réseau et USB sont celles de l’hôte du workspace.

Shell Android interactif et les arguments ADB libres autorisent des commandes arbitraires. Les arguments libres suivent le quoting POSIX, y compris sous Windows. Les commandes de démarrage, arrêt et redémarrage du serveur ADB ont une portée globale et peuvent affecter plusieurs appareils. L’arrêt forcé est limité aux serveurs locaux Linux identifiés sans ambiguïté.

AVD, images système et licences

Créer un AVD… propose un téléphone ou une tablette, un profil officiel, une image et un nom. La création demande confirmation et refuse d’écraser un AVD existant. Vous pouvez utiliser les images déjà installées hors réseau.

Télécharger une image système…, également accessible depuis l’assistant AVD, consulte le catalogue officiel. Examinez le composant, la taille disponible, la destination, les dépendances et la licence. La tâche interactive sdkmanager --licenses vous laisse répondre vous-même ; l’extension n’accepte aucune licence automatiquement. L’installation suit cette étape explicite. La reprise d’un téléchargement dépend du sdkmanager installé et n’est pas garantie. Une image partielle nécessite une réparation explicite.

Examiner les licences SDK Android… permet aussi d’ouvrir séparément la tâche de licences.

Arrêter l’émulateur sélectionné… demande confirmation et attend la disparition du transport. Le démarrage ne fait aucun wipe. Fermer VS Code ou annuler l’attente ne ferme pas automatiquement les émulateurs.

Réglages

Dans les paramètres VS Code, recherchez androidAdb. Les chemins d’outils sont des réglages machine ; configurez-les sur l’hôte du workspace. Un chemin explicite invalide produit une erreur, sans remplacement silencieux par un autre outil.

Les paramètres de projet sont associés au dossier workspace concerné, y compris en multi-root. Exemple pour une racine Android située dans android/ :

{
  "androidAdb.projectRoot": "android",
  "androidAdb.module": ":app",
  "androidAdb.variant": "debug",
  "androidAdb.apkPath": "",
  "androidAdb.applicationId": "",
  "androidAdb.activity": ""
}

Les champs vides permettent la sélection interactive ou la détection. Les choix interactifs remplacent les valeurs initiales pour la session. apkPath, absolu ou relatif à projectRoot, désigne un APK universel personnalisé produit par le build choisi. applicationId et activity complètent la détection aapt. Changer de projet/module/variante invalide l’application mémorisée par le parcours Gradle. Un projet externe conserve les réglages du dossier qui le référence.

Dépannage

Le guide de démarrage complète ces vérifications. Le démarrage d’un émulateur conserve un fichier temporaire privé android-adb-emulator-*.log dont le chemin est indiqué dans la sortie ; supprimez-le manuellement une fois l’émulateur arrêté si vous n’en avez plus besoin.

Sécurité et confidentialité

L’extension, Python, les outils Android et Gradle s’exécutent avec les droits de votre compte. Workspace Trust contrôle le consentement, sans isoler un projet malveillant. La découverte des variantes exécute aussi Gradle et peut télécharger ses dépendances. Un projet ou wrapper hors du workspace demande une confirmation distincte.

Les opérations gérées vérifient l’identité de la cible (série, transport ADB et démarrage Android). Une identité périmée exige une nouvelle sélection ; aucune autre cible n’est choisie en secours. Les outils externes comme scrcpy ont des limites de ciblage décrites dans leur guide. Le shell et les arguments libres restent sous votre contrôle.

L’extension ne collecte pas de télémétrie. ADB peut utiliser le réseau ; le catalogue d’images contacte des sources officielles et les outils SDK/Gradle peuvent télécharger leurs composants. Les journaux de l’extension restent locaux ; leur copie persistante est désactivée par défaut. VS Code, les outils et les fichiers temporaires peuvent conserver leurs propres diagnostics. Captures, bugreports, journaux et extractions peuvent contenir des données sensibles : relisez-les avant partage.

Voir les protections et limites de sécurité et les dépendances et licences.

Limites connues

• Débogage Kotlin non opérationnel : la commande explique la limite ; aucun adaptateur ni session de substitution n’est lancé. Logcat et lancement d’application ne valident pas les points d’arrêt, variables ou pas à pas Kotlin.
• Windows/macOS natifs et les environnements SSH/conteneur ne disposent pas encore d’une recette réelle complète. Le navigateur seul ne peut pas exécuter ce backend Python et ce SDK.
• VS Code 1.95 est le minimum déclaré ; les essais IDE documentés utilisent une version plus récente. Les tests unitaires ne prouvent pas la compatibilité de toutes les versions/hôtes.
• La recherche Gradle statique est bornée à 6 niveaux et 2 500 dossiers par racine, caches et sorties exclus. Les aliases, plugins de convention et modules déplacés peuvent nécessiter des paramètres explicites.
• Le parcours de build exige un APK unique : App Bundles, splits et variantes à sorties ambiguës sont refusés. Aucun ancien APK n’est repris après un échec de compilation. Les champs explicites du parcours Gradle n’acceptent pas les noms de classes contenant $.
• La validation des appareils physiques, du téléchargement d’images et de plusieurs comportements avancés est partielle. Les tests automatisés utilisent des outils simulés et ne remplacent pas les essais avec un SDK et des appareils réels.

Développer, auditer et réutiliser

Les sources propres au projet sont sous licence MIT : elles peuvent être étudiées, modifiées, réutilisées et redistribuées en conservant la notice de copyright et de licence. Les outils Android, Gradle, Java et scrcpy gardent leurs licences respectives. BMAD, conservé pour la documentation du développement, possède sa licence amont et est exclu du VSIX.

Aucune dépendance npm/pip n’est nécessaire à l’exécution : JavaScript CommonJS et bibliothèque standard Python. Pour contribuer ou reconstruire, installez Node 24, npm et Python 3.10+ :

git clone https://github.com/quentinbdno/vscode-android-adb-management.git
cd vscode-android-adb-management
npm ci --ignore-scripts
npm test
npm run package
npm run inspect

Le VSIX est généré dans dist/ avec le nom et la version définis dans package.json. Les tests unitaires utilisent de faux SDK/processus ; ils ne nécessitent ni appareil Android ni SDK réel. Les tests IDE/SDK sont décrits dans test/ide/README.md. La CI GitHub Actions teste, construit et inspecte un seul paquet universel sous Ubuntu, avec Node 24 et Python 3.12. Ce paquet contient les sources JavaScript et Python, sans binaire spécifique à Windows, Linux ou macOS ; sa construction ne remplace pas les essais de compatibilité sur chaque plateforme.

Pour s’orienter dans le code :

Pour proposer une modification, décrivez le problème, l’hôte, le comportement attendu et la validation exécutée dans une issue ou une pull request du dépôt. Joignez uniquement des diagnostics relus et anonymisés. Ajoutez des tests pour les changements de comportement, en particulier ciblage, annulation, chemins et données sensibles. Pour une réutilisation, construisez depuis la révision examinée et inspectez le VSIX obtenu ; l’empreinte SHA-256 est affichée par npm run inspect.

Versions et publication

Chaque push sur main et chaque pull request déclenchent les tests, l’audit des dépendances, la construction et l’inspection du VSIX. Un lancement manuel est aussi possible dans Actions → Tests et VSIX → Run workflow. Les paquets de développement sont disponibles dans les artefacts de l’exécution GitHub Actions correspondante.

Le push d’un tag vX.Y.Z, correspondant à la version du manifeste, relance la validation complète et prépare un brouillon de release GitHub contenant le VSIX et son empreinte SHA-256. Les versions publiques sont accessibles depuis la page Releases ; leur historique fonctionnel figure dans le changelog.

Le guide de publication explique comment préparer une version, publier la release et activer la publication Marketplace depuis GitHub Actions avec Trusted Publishing. Le même paquet inspecté est utilisé pour la distribution.

Logo de l’extension

Le logo Hub représente une tablette et un téléphone reliés à un point central.

L’icône de la fiche de l’extension est déjà embarquée dans le VSIX via le champ icon du manifeste. Pour une image de profil du publisher, vous pouvez choisir le même PNG dans les paramètres de ce profil. Le guide de publication précise les fichiers à charger.

npm run icon vérifie le format du PNG.