How nisargjhaveri/vscode-android-debug works
Project Type and Purpose
• This is a VS Code extension (TypeScript) that provides:
– Android app debugging (Java, Native, or dual)
– CPU profiling via simpleperf or Firefox Profiler
– A custom profile viewer inside VS Code
• Key indicators:
– package.json with “activationEvents” and “contributes.debuggers”
– src/ folder with debugAdapter, debugConfigProvider, profile‑converter, profile‑viewer, etc.
File Structure
Top‑level artifacts:
• package.json / tsconfig.json / .vscodeignore – VS Code extension manifest & build config
• src/ – all TypeScript source code
• examples/SampleApplication – test Android app demonstrating usage
• .github/workflows – CI pipeline for building & packaging
• src/test – unit and integration tests
Within src/:
• extension.ts – extension entry point; registers providers & commands
• debugConfigProvider.ts – implements DebugConfigurationProvider for “android-debug”
• debugLifecycleManager.ts – orchestrates launch/attach lifecycles
• debugAdapter.ts & jdwp.ts – implement Debug Adapter Protocol (DAP) interactions, JDWP for Java, spawn LLDB for native
• androidPaths.ts, targetPicker.ts, targetCommand.ts – resolve SDK/NDK paths, pick devices, run ADB commands
• profile-converter/ – converters from simpleperf & Firefox Profiler formats to internal model
• profile-viewer/ – custom editor for displaying converted profiles
• logger.ts, utils.ts – shared utilities
Extract Additional Insights from README
• Extension contributes two debugger types: “android-debug” and “android-profile.”
• Depends on external extensions: CodeLLDB (native) and Java Debugger by Red Hat.
• Relies on Android SDK/NDK and ADB under the hood.
Main Components and Interactions
A. VS Code Host
• User invokes “Start Debugging” or “Open Profile”
• UI & Debug View communicate via the Debug Adapter Protocol (DAP)
B. Extension Host (Your code)
1. Activation & Registration
– extension.ts registers DebugConfigurationProvider, custom editor, commands
2. Debug Configuration Provider
– debugConfigProvider.ts supplies default launch/attach configs to VS Code
3. Debug Lifecycle Manager
– debugLifecycleManager.ts kicks off ADB device selection, installs APK (if needed), resumes process
4. Debug Adapter(s)
– For Java: use jdwp.ts to speak JDWP to device’s VM
– For Native: spawn CodeLLDB (dap) with symbolSearchPaths
– debugAdapter.ts ties both adapters into a “dual” session
5. Profile Conversion Pipeline
– profile-converter/converter.ts invokes either simpleperf or firefox‑profiler submodules
– Generates a common JSON/graph model
6. Profile Viewer
– profile-viewer/profileCustomEditor.ts implements a Custom Editor in VS Code
C. External Services
• Android Device / Emulator (via ADB)
• Android SDK & platform-tools
• Android NDK (for native symbols)
• CodeLLDB & Java Debugger extensions (hosted in VS Code)
Architectural Patterns & Principles
• Modular separation: configuration → lifecycle → protocol adapters → converters → UI
• Use of Debug Adapter Protocol (DAP) as a decoupling layer
• Plugin‑style extension registration via VS Code API
• Single Responsibility: each module handles one aspect (device pick, JDWP, LLDB, profile conversion, viewing)
– VS Code UI & Debug View (green)
– Extension Host
• Activation & Registration
• Debug Configuration Provider
• Debug Lifecycle Manager
• Java Debug Adapter (JDWP)
• Native Debug Adapter (LLDB)
• Profile Converter
• Profile Viewer
– External Entities (gray): Android Device/Emulator, Android SDK/NDK, CodeLLDB & Java Debugger extensions
– User → VS Code UI → Extension (activation)
– Extension → ADB (install/launch) → Device
– Device → JDWP adapter → Extension → VS Code (Java debugging)
– Extension → spawn LLDB → Device (native debugging)
– Device profiling data → Converter → Viewer → VS Code UI
– Purple labels: third‑party extensions