VS Code Extension
The alplabai/alp-sdk-vscode extension is the recommended IDE for projects built against the Alp SDK. It ships an LSP-native board.yaml editing experience, command-palette wrappers around the loader and west, debug-aware orchestration for SWD / Linux-userspace / native-host targets, and a CLI that mirrors the same shared core for headless and CI use.
The extension is debugger-aware, not a debugger — it generates, validates, inspects, and launches the right debug configuration for the active target, leaning on marus25.cortex-debug, cppdbg, and CodeLLDB for the actual attach.
Install
| Source | How |
|---|---|
| VS Code Marketplace | Search for Alp SDK in the Extensions panel. |
.vsix artifact | Grab the latest from the extension's Releases page and install via Extensions: Install from VSIX. |
| From source | git clone --recurse-submodules https://github.com/alplabai/alp-sdk-vscode && cd alp-sdk-vscode && npm install && npm run package. The submodule pins to the alp-sdk commit that owns the schema. |
License: Apache-2.0.
board.yaml LSP
Inline language-server support for board.yaml:
- Completion —
som.sku,preset:(board preset), inlinename:/populated:/e1m_routes:,cores.<id>.os(offered only when overriding the topology default),cores.<id>.peripherals,chips,cores.<id>.libraries/cores.<id>.extra_libraries,cores.<id>.inference.default_arena_kib, the v0.6 blocks (boot:,ota:,storage:,security:,cores.<id>.memory:/power:,diagnostics.modules:), with values pulled from the metadata schemas the SDK ships undermetadata/schemas/. - Hover — every field carries its schema description; hovering a SoM SKU shows silicon + form factor + status.
- Diagnostics — schema errors land in the Problems panel as you type. Cross-field validator output (rules R1–R5 + warnings W4–W5) also surfaces inline, mirroring
validate_board_yaml.pyexit codes. - Document symbols — outline view shows the top-level blocks (
som,preset,cores,boot,ota,storage,security,ipc,diagnostics, …) for fast navigation in large files. - Quick fixes — common typos (
hw_rev: r0→ suggest the nearest released revision; missing required field → insert with a placeholder). - Effective-config preview — a side-pane that renders the resolved config after the loader applies the SoM preset, board preset, and library profiles. Useful for understanding what
peripherals:actually compiles in.
Configurator panel
A GUI panel for new projects and for quick experimentation:
- Dropdowns for every released SoM MPN + stock board preset + per-core
os:override (offered only where the topology default isn't what you want). - Live preview of the
board.yamlthat will be written. - First-run project wizard that scaffolds a working app (CMakeLists,
prj.confplaceholder,src/main.c, board overlay) from a template.
Command palette
The extension contributes the Alp: command family (current release: v0.3.4, pre-release channel).
Validate + generate
| Command | What it does |
|---|---|
| Alp: Validate board.yaml | Schema + semantic validation. Same rules as the CLI's alp validate. |
| Alp: Generate all | Runs the loader's per-slice emit modes in one shot: zephyr-conf → alp.conf, dts-overlay → alp.overlay, cmake-args → alp-cmake-args.txt, yocto-conf → the Yocto conf snippet. |
| Alp: Generate alp.conf / alp.overlay / alp-cmake-args.txt / alp-yocto.conf | Individual emit modes. |
| Alp: Preview effective config (LSP) | Show the resolved config (SoM preset + board preset + library profiles applied) without writing files. |
| Alp: Preview build plan | Show the per-core build plan the orchestrator will run before building. |
| Alp: Inspect project state | Effective resolved config + preset origins; supports drilling into a field path. |
Project & SDK setup
| Command | What it does |
|---|---|
| Alp: Get started (walkthrough) | Guided first-run walkthrough. |
| Alp: New project wizard | Scaffold a working app (CMakeLists, prj.conf placeholder, src/main.c, board overlay) from a template. |
| Alp: Open Existing Alp Project | Open + adopt an existing project workspace. |
| Alp: Scaffold module | Add a starter source/peripheral module to an existing project. |
| Alp: Open board configurator (GUI) | The dropdown-driven configurator panel. |
| Alp: Open setup wizard | First-time environment setup flow. |
| Alp: Bootstrap SDK environment (west + Zephyr deps) | Install west + Zephyr dependencies into the workspace. |
| Alp: Select active SDK / Alp: SDK Manager | Pick / manage the SDK checkout the project resolves against. |
| Alp: Switch workspace folder | Re-target the active workspace folder. |
| Alp: Remove west initialization (.west/) | Reset the west workspace state. |
Build + run
| Command | What it does |
|---|---|
| Alp: Build (validate + generate + build) | Validate + generate + west build in one step. |
| Alp: West flash | Wraps west flash for the active target. |
| Alp: Flash (all slices) | Flash every slice of a heterogeneous build. |
| Alp: Build image (assemble image bundle) | Assemble the deployable image bundle. |
| Alp: West update (fetch and update modules) | west update — fetch + update modules. |
| Alp: Clean build (remove build dir) | Remove the build directory. |
| Alp: Run under native_sim | Build + run the host-simulator target. |
| Alp: Run in Renode (simulate) | Build + run under the Renode simulator. |
| Alp: Toolchain doctor | Verify tool availability + project sanity. |
| Alp: Show output log | Open the extension's output channel. |
Explore + debug
| Command | What it does |
|---|---|
| Alp: Hardware Explorer | Browse the resolved board's pads, routes, and populated chips. |
| Alp: Configure debug profile (launch.json) | Resolve a debug profile and write the matching .vscode/launch.json entry. |
| Alp: Debug doctor / Alp: Debug preflight | Verify debug-backend prerequisites — generally, or scoped to a specific profile before launch. |
| Alp: Export debug support bundle | Sanitised archive (inspect output + doctor results + tool versions) for issue filing. |
| Alp: Open troubleshooting panel | Guided debug-failure triage. |
Alp IDE panel
Beyond the command palette the extension ships an integrated Alp IDE surface — an Activity Bar entry with sidebar views and a dedicated panel that ties the configurator, build/flash, SDK manager, and hardware explorer together in one place.
| Command | What it does |
|---|---|
| Alp: Open Alp IDE panel | The main Alp IDE hub. |
| Alp: Open Alp IDE overview | Project-state + next-steps overview. |
| Alp: Open Alp IDE settings | Extension + project settings. |
| Alp: Refresh sidebar views | Re-resolve the sidebar tree views. |
Debug surface
Three debug classes are supported, each with a dedicated launch-config generator:
| Class | Used for | Adapter | Probe / server |
|---|---|---|---|
| MCU | Zephyr + bare-metal targets, SWD/JTAG bring-up, flash + halt + step | marus25.cortex-debug | J-Link · OpenOCD · pyOCD |
| Linux userspace | Yocto userspace apps; remote symbolised debug over SSH | cppdbg + gdbserver (or lldb-dap later) | — |
| Host / native | native_sim, host-side tools, generator helpers | CodeLLDB | — |
The extension itself never embeds a debugger. Alp: Configure debug profile (launch.json) writes the matching .vscode/launch.json entry; the third-party adapter handles attach + breakpoints + stepping. Alp: Debug preflight verifies probe access, gdbserver reachability, or simulator availability before launch.
For the full per-target compatibility matrix, see DEBUG.md in the extension repo.
CLI
The same shared-core that powers the extension is exposed as alp for headless / CI use. Eight command families cover the surface:
| Family | Purpose |
|---|---|
alp validate | Schema + semantic validation; structured issues. |
alp generate | Emit derived artifacts (Kconfig fragment, DTS overlay, CMake args, Yocto conf, hw-info header, west-libraries). |
alp init | Initialise a new project from a template. |
alp scaffold | Add starter files / modules to an existing project. |
alp inspect | Show the resolved config + preset origins (field-path scoped). |
alp trace | Explain why a resolution or generation decision was made. |
alp doctor | Tool availability + project sanity + (optional) debug preflight. |
alp support-bundle | Sanitised diagnostics archive. |
alp debug-config | Resolve a named debug profile and emit a launch artifact. |
alp completion <shell> | Emit shell-completion script for bash / zsh / fish / PowerShell. |
Every command supports --format json for machine-readable output (single JSON document to stdout, prose / progress to stderr) and a stable exit-code matrix (0 success, 2 validation, 3 write failure, 4 doctor/preflight failure, 5 internal). The full contract is in CLI.md.
This is the same logic the extension runs — UI, LSP, and CLI all sit on the shared core, so a validate in CI matches what the editor sees.
Snippets
board.yaml and src/main.c snippets ship with the extension. Trigger with the usual Ctrl+Space; the snippets reference the same instance-ID macros as the SDK's per-peripheral examples (ALP_E1M_I2C0, ALP_E1M_GPIO_IO0, …).
Schema sync
The extension's schema-aware validation pulls from alp-sdk directly via a git submodule (alp-sdk-upstream/metadata/schemas/). When the SDK's schema evolves, the extension bumps the submodule pin in lockstep and republishes; you don't need to do anything on your side beyond updating the extension.
See also
board.yamlreference — the schema the extension validates against- Architecture — what the orchestrator actually does
- Quick start — the SDK-side install + first-build flow
alp-sdk-vscode— extension source repo