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, the tan CLI, and west, debug-aware orchestration for SWD / Linux-userspace / native-host targets, and it drives the same tan binary you would run headless or in CI.
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
The extension is published as AlpLabAI.alp-sdk — publisher AlpLabAI, extension name alp-sdk. Its marketplace display name is "Alp IDE", not "Alp SDK".
| Source | How |
|---|---|
| VS Code Marketplace | Search for Alp IDE in the Extensions panel (id AlpLabAI.alp-sdk). |
.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 && pnpm install && pnpm run package. The submodule pins to the alp-sdk commit that owns the schema. |
Requirements
- VS Code
^1.85.0. - Two extension dependencies, installed automatically alongside it:
redhat.vscode-yaml(theboard.yamlYAML host) andmarus25.cortex-debug(the MCU debug adapter).
Versions and channels
- Current version:
0.5.2. It is merged onorigin/main, but nov0.5.2tag has been cut yet — the last tagged release isv0.5.1. - Channel is decided by the minor version: an odd minor (
0.3.x,0.5.x) publishes to the VS Code pre-release channel; an even minor is a stable release. The current0.5.xline is therefore a pre-release build — that is why the Marketplace shows a pre-release badge. - The extension pins the tan CLI it drives:
SUPPORTED_CLI_VERSION = "0.5.1". It shells the externaltanbinary and does not re-implement build logic.
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, the top-levellibraries:/cores.<id>.extra_libraries,cores.<id>.inference.default_arena_kib, the declarative 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 — 46 commands in 0.5.2 (pre-release channel). The tables below are a curated walkthrough of the ones you reach for; every title is the verbatim palette entry.
Validate + generate
| Command | What it does |
|---|---|
| Alp: Validate board.yaml | Schema + semantic validation. Same rules as the CLI's tan validate. |
| Alp: Generate all (zephyr-conf + dts-overlay + cmake-args + yocto-conf) | 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 (zephyr-conf) · Alp: Generate alp.overlay (dts-overlay) · Alp: Generate alp-cmake-args.txt (cmake-args) · Alp: Generate alp-yocto.conf (yocto-conf) | Individual emit modes. |
| Alp: Generate native_sim overlay (native-sim-overlay) | The host-simulator overlay, emitted on its own. |
| 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 (Zephyr + build deps) | Install Zephyr + build dependencies into the workspace; runs tan bootstrap. |
| Alp: Select active SDK / Alp: SDK Manager | Pick / manage the SDK checkout the project resolves against. The SDK Manager can list releases online, shows a truthful active-SDK badge and Deactivate action, and sits Bootstrap next to Install. Switching SDKs reconciles the west workspace. |
| Alp: Install tan CLI (global) / Alp: Reinstall the pinned tan CLI | Install the tan binary the extension shells, or reinstall the pinned version (0.5.1) when the local one drifts. |
| Alp: Dependencies | The dependency panel — what the toolchain needs, what is present, and what to install. |
| Alp: Switch workspace folder | Re-target the active workspace folder. |
| Alp: Reset workspace (.west/) | Reset the west workspace state by removing .west/. |
Build + run
| Command | What it does |
|---|---|
| Alp: Build (validate + generate + build) | Validate + generate + build in one step; the build itself runs tan build. |
| Alp: Flash (single image) | Flash one image to the active target. |
| Alp: Flash (all slices) | Flash every slice of a heterogeneous build (tan flash). |
| Alp: Build image (assemble image bundle) | Assemble the deployable image bundle (tan image). |
| Alp: Update workspace | Fetch + update the west modules for the workspace. |
| Alp: Clean build (remove build dir) | Remove the build directory (tan clean). |
| Alp: Run under native_sim | Build + run the host-simulator target (tan run). |
| Alp: Run in Renode (simulate) | Build + run under the Renode simulator (tan renode). |
| Alp: Toolchain doctor (opens Dependencies) | Verify tool availability + project sanity; opens the Dependencies panel. |
| Alp: Show output log | Open the extension's output channel. |
Build feedback in 0.5.x: the orchestrator's output streams live to the Alp SDK output channel, each slice reports its memory footprint via tan size, a failed slice says why it failed rather than just failing, and the finish toast can reveal the Build Plan panel.
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 (generate profile + start session) | Generate the profile and start the debug session in one step. |
| 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 | Focus the Alp IDE view container. |
| Alp: Open Hub | The hub: project state + next steps. A deprecated alias, Alp: Open Hub (deprecated alias), is still contributed for anyone with the old keybinding. |
| Alp: Open Alp IDE settings | Extension + project settings. |
| Alp: Refresh sidebar views | Re-resolve the sidebar tree views. |
Settings
The extension contributes eight settings under the alpSdk. namespace:
| Setting | What it controls |
|---|---|
alpSdk.path | Path to the alp-sdk checkout the project resolves against. |
alpSdk.pythonPath | Python interpreter used for the SDK's loader / bootstrap work. |
alpSdk.boardYamlPath | Path to the project's board.yaml when it isn't at the default location. |
alpSdk.westCwd | Working directory for west invocations. |
alpSdk.cliPath | Explicit path to the tan binary. |
alpSdk.preferGlobalCli | Prefer a globally-installed tan over the extension-managed one. |
alpSdk.tanCliDownloadConsent | Consent for the extension to download the tan CLI. |
alpSdk.svdPath | SVD file passed through to tan debug-config --svd for register-aware debugging. |
Downloading tan
The extension asks for consent before it downloads the tan CLI (alpSdk.tanCliDownloadConsent), verifies the checksum of both the downloaded and the cached binary, routes downloads through your configured proxy settings, and — when your platform has no published build — explains that instead of surfacing a bare 404.
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. Alp: Debug (generate profile + start session) does both in one step.
The launch configuration comes from tan — the extension no longer keeps a second draft of it — and diagnostics come from tan doctor rather than an in-process twin. Set alpSdk.svdPath to feed a device SVD through tan debug-config --svd and get register-aware views. Pressing F5 builds first, via a pre-launch task, so you never step through a stale image. MCU debugging needs marus25.cortex-debug with its Memory View and RTOS Views enabled.
For the full per-target compatibility matrix, see docs/DEBUG.md in the extension repo.
CLI
The extension does not ship a CLI of its own any more. It shells tan — the standalone, independently-versioned binary that is also the Alp SDK's sole user-facing command (ADR-0020). As of the 0.5.x line tan is a Python program, and the extension drives that Python tan, pinned to SUPPORTED_CLI_VERSION = "0.5.1"; environment setup therefore calls tan bootstrap, not a --fix flag (Python tan has none). The in-repo TypeScript CLI (packages/alp-cli) and the earlier alp binary it grew out of are retired. The same tan you get from the palette's Alp: Install tan CLI (global) is the one you run headless or in CI:
| Family | Purpose |
|---|---|
tan validate | Schema + semantic validation; structured issues. |
tan generate | Emit derived artifacts — zephyr-conf, dts-overlay, native-sim-overlay, cmake-args, yocto-conf, carrier-netlist. |
tan bootstrap | Install the Zephyr + build dependencies for the workspace. |
tan init | Initialise a new project from a template. |
tan scaffold | Add starter files / modules to an existing project. |
tan inspect | Show the resolved config + preset origins (field-path scoped). |
tan trace | Explain why a resolution or generation decision was made. |
tan doctor | Tool availability + project sanity + (optional) debug preflight. |
tan support-bundle | Sanitised diagnostics archive. |
tan debug-config | Resolve a named debug profile and emit a launch artifact. |
tan completion <shell> | Emit shell-completion script for bash / zsh / fish. |
tan covers more verbs than these — the build-execution surface (tan build / flash / size / image / clean / renode / run) is the same one the tan CLI page documents.
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, 1 command/runtime failure, 2 validation, 3 write failure, 4 doctor/preflight failure, 5 internal). The full envelope contract is in docs/CLI.md.
Command behaviour therefore has one implementation: the extension shells tan rather than re-deriving the same outcomes, so a tan validate in CI matches what the palette runs. The LSP keeps a separate in-process path for the per-keystroke editor intelligence a subprocess can't serve.
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