Development, debugging and deployment tooling for OpenHarmony system adaptation
and chip bring-up — packaged as a VSCode extension.
The extension provides host-side tooling for engineers porting OpenHarmony to a
new SoC or working at the system / driver / HAL layer: device discovery over
hdc, shell & file transfer helpers, system property access (param), live
hilog streaming, image flashing, and a native (C/C++) debug adapter that
connects VSCode to on-device gdbserver / lldb-server over an hdc port
forward.
This is the initial scaffold. The hdc / system / debug layers are wired and
tested; the GDB/LLDB backend driver is intentionally pluggable and ships with
a stub — see Roadmap.
Features
| Area |
Status |
Notes |
Device discovery (hdc list targets) |
✅ |
Auto-refreshing tree view + commands |
Shell / file transfer (hdc shell, file push/pull) |
✅ |
Typed Shell & FileTransfer helpers |
System properties (param get/set) |
✅ |
Command + PropertiesService API |
| HiLog streaming |
✅ |
Output channel, level filter, structured parsing |
| Image flashing |
⚠️ scaffold |
dd-based runtime strategy; vendor flasher hook |
Native debug adapter (openharmony-native) |
⚠️ scaffold |
DAP session + runtime; GDB/LLDB driver via registerBackend |
| Multi-version device support |
✅ |
All operations degrade gracefully across OH versions |
Quick start
Prerequisites
- Node.js 20+ (see
.nvmrc)
- pnpm 9+
hdc on your PATH, or set openharmony.hdc.path in VSCode settings
- A connected OpenHarmony device (or emulator) with developer mode enabled
Build & run
pnpm install
pnpm run watch # esbuild: extension (Node side)
pnpm run watch:webview # Vite: webview (browser side) — separate terminal
Then press F5 in VSCode to launch an Extension Development Host
with this extension loaded.
Configuration
| Setting |
Default |
Description |
openharmony.hdc.path |
"" |
Path to the hdc binary. Empty = resolve from PATH. |
openharmony.hdc.timeout |
15000 |
Default timeout (ms) for hdc commands. |
openharmony.hilog.bufferSize |
1024 |
Buffer size (KB) for the hilog stream. |
openharmony.debug.gdbPath |
gdb |
GDB executable used by the native debug adapter. |
openharmony.debug.lldbPath |
lldb |
LLDB executable used by the native debug adapter. |
Debugging a native program
- Build your program for the device (e.g.
out/.../myapp).
- Open the Run & Debug panel → "create a launch.json" → pick
OpenHarmony: Launch native program.
- Set
program to your binary and backend to gdb or lldb.
- F5. The adapter pushes the binary, starts
gdbserver on the
device, opens an hdc fport tunnel, and attaches the host debugger.
Repository layout
src/
extension.ts Activation entry point (wires all layers together)
backend/ Core logic — no VSCode UI dependency
hdc/ hdc client, device manager, shell, file transfer
system/ param properties, hilog streaming, image flashing
testing/ Stability test runners, task manager, report gen
debug/ DAP debug session, runtime, adapter registrar
utils/ process spawning, logger, config, disposables
types/ Shared type definitions (OpenHarmonyDevice, ...)
framework/ VSCode integration layer
commands/ User-facing command handlers (hello world, ...)
views/ Tree view providers (menu, devices)
actions/ Project actions (create, open, adapt, verify)
panels/ Webview panel hosts (selfTestPanel)
frontend/ Vue 3 webview source (built by Vite, not shipped)
stability/ "稳定性测试" panel SPA
App.vue Root layout (header + split + modal)
main.ts Entry: createApp + message listener + CSS imports
types.ts Self-contained webview type definitions
composables/ useStabilityStore (singleton state) + useVsCodeApi
components/ TaskList, TaskCard, NewTaskCard, TaskDetail,
RunStateGroup, RunRow, CrashChips, LogStream,
CreateModal, StepEditor
styles/ theme.css (CSS variables, theme-able) + base.css
test/
unit/ Vitest unit tests (hdc parsing, device manager, ...)
e2e/ @vscode/test-cli integration tests run in a real host
media/ Extension & activity bar icons
esbuild.mjs Extension bundler (src/extension.ts -> dist/extension.js)
vite.webview.config.ts Webview bundler (src/frontend/stability -> dist/webview/)
Scripts
| Script |
Description |
pnpm run watch |
Build the extension in watch mode (esbuild). |
pnpm run watch:webview |
Build the webview in watch mode (Vite). |
pnpm run package |
Production build (extension + webview). |
pnpm run build:webview |
One-shot webview build (Vite). |
pnpm run typecheck |
Typecheck extension (tsc) + webview (vue-tsc). |
pnpm run lint / lint:fix |
ESLint (extension source). |
pnpm run format / format:check |
Prettier (includes .vue files). |
pnpm run test:unit |
Run unit tests with Vitest. |
pnpm run test:e2e |
Run integration tests inside a real VSCode. |
pnpm run test |
Run unit + e2e tests. |
pnpm run clean |
Remove dist/, out/, .vscode-test/. |
Roadmap
- [ ] GDB backend driver (
gdb -i=mi over the fport tunnel)
- [ ] LLDB backend driver (
lldb platform / process connect)
- [ ] Vendor flasher strategies (Hitool, IDE burner) via
FlashService.register
- [ ] HAP/HSP build & install workflow for system apps
- [ ]
hdc hilog rich filtering (by tag / pid / domain)
- [ ] Per-device output channels and a device picker QuickPick
Contributing
See CONTRIBUTING.md. All changes must keep pnpm run typecheck,
pnpm run lint, and pnpm run test green.
License
Apache-2.0. See LICENSE.