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,carrier.name,os,peripherals,chips,inference.backend,libraries, 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-rule diagnostics (e.g. asking for
i2son a SoC that doesn't route I²S) also surface inline, mirroringvalidate_board_yaml.pyexit code 3. - Document symbols — outline view shows the top-level blocks (
som,carrier,peripherals, …) 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, carrier 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 carrier + OS + inference backend.
- 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. The most-used:
| Command | What it does |
|---|---|
Alp: Validate board.yaml | Schema + semantic validation. Same rules as the CLI's alp validate. |
| Alp: Generate all | Runs scripts/alp_orchestrate.py per slice for every --emit mode at once: zephyr-conf → build/<core>-zephyr/alp.conf, cmake-args → …/alp-cmake-args.txt, yocto-conf → build/<core>-yocto/conf/alp-generated.conf, dts-overlay → …/alp.overlay, hw-info-h → …/alp_hw_info_build.h, west-libraries → …/alp-west-libs.yml. Plus the cross-slice artefacts: system-manifest.yaml, alp/system_ipc.h, dts-reservations.dtsi. |
Alp: Generate <target> | Same as above but for a single --emit mode. |
| Alp: Preview effective config | Show the resolved config without writing files. |
| Alp: Scaffold module | Add a starter source/peripheral module to an existing project. |
| Alp: Show presets | List the SoM + carrier presets the active workspace can resolve. |
| Alp: Diff effective config | Compare two board.yamls (or two revisions of one) at the resolved-config level. |
| Alp: Bootstrap workspace | Runs scripts/bootstrap.sh (or its Windows equivalent) and surfaces OS-specific hints. |
| Alp: Build native_sim | Wraps west alp-build -b native_sim/native/64. |
| Alp: Build EVK | Picks the right board file from your board.yaml. |
| Alp: Flash / Alp: Run native_sim | Wraps west flash / west build -t run. |
| Alp: Inspect | Show the effective resolved config + preset origins; supports drilling into a single field path. |
| Alp: Trace | Explain why a generation or resolution decision was made for a given field or target. |
| Alp: Doctor | Verify tool availability, project artifacts, and (optionally) debug-backend prerequisites. |
| Alp: Preflight | Same as Doctor but scoped to a specific debug profile. |
| Alp: Generate launch config | Resolve a debug profile and write the right .vscode/launch.json entry. |
| Alp: Support bundle | Export a sanitized archive (inspect output + doctor results + tool versions + selected profile metadata) for issue filing. |
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: Generate launch config writes the matching .vscode/launch.json entry; the third-party adapter handles attach + breakpoints + stepping. Alp: 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 (E1M_I2C0, 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_version bumps, 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